This page was last updated on 3 August, 2007.

Looking for the Marketplace documentation? Check out the Marketplace FAQ.

Documentation

Installation and Upgrading
How to let advertisers find you
WP Text Ads options page
Making changes to WordPress templates
Using the WP Text Ads widgets
Customizing the advertiser form
WP Text Ads configuration file
The WP Text Ads API

Installation and Upgrading

To use WP Text Ads, please ensure you meet the following requirements:

WordPress/WordPress MU 2.0 and higher.
MySQL version 4.1 and higher.
Your WordPress user level is at least 8. Administrators have this level.
WordPress can send emails as WP Text Ads uses WordPress's email feature.

New Install

Download WP Text Ads and unzip it into the 'wp-content/plugins' directory of your WordPress folder. All the files will appear in the 'wptextadsX' subdirectory, where X is the version of WP Text Ads. WordPress MU administrators, please do not unzip into the 'wp-comtent/mu-plugins' directory.

Go to Options → WP Text Ads. If you have never installed WP Text Ads before, you will be prompted to create the database table. This table will be added to your WordPress database. Please do that now.

You need to make sure your blog will display the ads. You can either amend the WordPress template or use the WP Text Ads widgets to do that.

Starting with WP Text Ads 1.2, you can create plugins using the WP Text Ads API. Such plugins can be found here.

Use WP Text Ads images to capture advertisers' attention. You can add these inside the widgets or templates.

After installing, please join the Marketplace so that advertisers can find your blog.

You can also customize the advertiser form if you wish.

Upgrading

Before you begin, you should backup everything in the 'wptextadsX' subdirectory, just in case the upgrade goes awfully wrong.

The most recent version of WP Text Ads is 1.2. Upgrading is usually as simple as overwriting all the files in the 'wptextadsX' subdirectory. Before you do that, try to recall if you made any changes to the files in a previous version.

If you did not make a single change, then you can treat your upgrade as a new install and overwrite everything in the 'wptextadsX' subdirectory.

But if you made changes, they should have been restricted to the advertiser form and the 2 options in wpta_config.php file. This is what you need to do:

Save your changes in wpta_config.php somewhere. After it is overwritten by the new version, edit the options back to your own values.
Save the entire subdirectory that contains the advertiser form somewhere where it will not be overwritten. It is located at 'wp-content/plugins/wptextadsX/templates/adforms'. After you unzip version 1.2, a fresh copy will be installed. Then you can overwrite this subdirectory with your old one.

Whether you made changes or not, the last step is to enter the WP Text Ads options page. The first time this is run, WP Text Ads will automatically upgrade itself.

There are 3 text files included in the zip file that might interest you:

changelog.txt - details about the changes in version 1.2.
sql.txt - SQL source of WP Text Ad's database schema, just in case you need to create it manually.
upgrade.txt - upgrade instructions.

How to let advertisers find you

To give your blog more visibility to attract advertisers, you can join the Marketplace. There's plenty of information about the Marketplace here.

WP Text Ads options page

The WP Text Ads options page is divided into a couple of sections, each with a different focus.

Section	Description
Admin Panel	Accept, reject, extend and edit advertiser information here. More details below.
Prices & Durations	Set up to 3 ad rates and runs for your whole blog, home page and per-post ads.
Email Templates	7 templates to boost your customer service. You can even test them before you go live.
Display Options	Configure the look of your ads and the advertiser form.
Marketplace	Submit information to the marketplace so that advertisers can find you.
Validate License Key	If you upgraded to WP Text Ads Standard Edition, you'd have received a license key in your email. Validate it here.
Give Feedback	Send a message to me (Alex Choo).
Email Announcements	Subscribe to a list to be kept informed of important announcements.
SQL Table Setup	Creates a SQL table for WP Text Ads in your WordPress database. Your advertisers' information is stored here.

Other than Admin Panel, the other sections are self-explanatory when you see it so I will not go into details here.

The Admin Panel

The Admin Panel comes with 8 views available from a drop-down select box. Every view displays a table of advertiser information.

View	Description
Potential Advertisers	Advertisers who have filled in the advertiser form and have not been approved.
Potential Advertisers → Rejected	You rejected these advertisers.
Waiting for Payment	Approved but have not paid up.
Active Links	Ad links that are running at your blog.
Deactivated Links	For some reason, you've chosen to disable these active links so they're not shown on your blog.
Expired Links	Ads that have expired past its duration.
Expiring Links	Ads that are about to expire. The number of days to go before an active link appears here is set in Prices & Durations.
Recycle Bin	Anything you don't want goes here. You can restore it or delete it permanently.

Each view also presents you with actions to take on the rows of data. Here are the actions and their meanings.

Action	Description
Activate links	Display the ads at your blog. Move data to the Active Links view.
Approve → Send email to ask for payment	Approve ads. Move data to the Waiting for Payment view.
Reject → Send email to notify	Reject ads. Move data to the Potential Advertisers → Rejected view.
Send email → Payment reminder	Send advertiser an email to remind him that payment is required.
Send email → Renew → Expired	Inform advertiser that his ad has expired and you'd like to renew it if he agrees.
Send email → Renew → Expiring	Inform advertiser that his ad is expiring and you'd like to extend it if he agrees.
Revert to potential advertisers	Move data back to the Potential Advertisers view.
Deactivate links	Deactivate an ad so that it is no longer shown at your blog. Move data to the Deactivated Links view.
Send to recycle bin	Move data to the Recycle Bin view.
Restore	Moves data from Recycle Bin to the original view that it came from.
Empty recycle bin	Permanently delete data.

At the end of every row of data is an 'edit' link. You use it to alter the ad's information such as advertiser info, ad info and expiry date. The options vary depending on the status of the link.

Making changes to WordPress templates

These changes will help you display the ads and advertiser form links. If you prefer not to edit the templates, you can use the WP Text Ads widgets instead.

There are 2 snippets of PHP code that you can paste into your WordPress templates. The first displays a link for advertisers to buy ads. The second displays the ads.

Using wpta_advertiser_buy()

This PHP function is used to prompt advertisers to buy ads. Once an advertiser clicks on the link, the advertiser form is opened. Use the code like this:

<?php if(function_exists('wpta_advertiser_buy')) {
            wpta_advertiser_buy();
         }
?>

or

<?php if(function_exists('wpta_advertiser_buy')) {
            wpta_advertiser_buy('Buy an ad');
         }
?>

If you leave the function argument empty, wpta_advertiser_buy() will use the default text set in Options → WP Text Ads → Display Options → Advertiser Link Text.

There is no styling option for this text, so you'll have to create markup in the WordPress template yourself. I left it this way to give you maximum flexibility as you might insert this function in various places with different styles.

Using wpta_show_ads()

This function displays the text ads. You are most likely to use it in the sidebar template like this:

<?php if(function_exists('wpta_show_ads')) {
            wpta_show_ads();
         }
?>

WP Text Ads allow you to style the ads. Go to Options → WP Text Ads → Display Options → Ad Links Template to see the options.

The WordPress sidebar contains a few blocks of links under headings such as Pages, Archives, Keywords and Categories. The Ad Links Template lets you create and style one block for your ads.

The Display Header field in the Ad Links Template corresponds to the Archives or Pages block heading text. The default markup in the other text fields are typical of such blocks in most WordPress themes. You should view your sidebar template to be sure.

As an example, this is how you insert wpta_advertiser_buy() and wpta_show_ads() into the sidebar of the Classic and Default WordPress themes. Its sidebar is contained in a nested list like this:

<div id="sidebar">
<ul>
    <li>
        <ul><h2>Pages</h2>
            <li>About me</li>
            <li>Hobbies</li>
        </ul>
    </li>
    <li>
        <ul><h2>Archives</h2>
            <li>Jan 2007</li>
            <li>Feb 2007</li>
        </ul>
    </li>
</ul>
</div>

What you need to do is to insert <li></li> elements and insert wpta_advertiser_buy() and wpta_show_ads() there, like this:

<div id="sidebar">
<ul>
    <li>
        <ul><h2>WordPress Text Ads</h2>
            <li>
                <?php if(function_exists('wpta_advertiser_buy')) {
                            wpta_advertiser_buy();
                         }
                ?>
            </li>
        </ul>
    </li>
    <li>
        <?php if(function_exists('wpta_show_ads')) {
                    wpta_show_ads();
                 }
        ?>
    </li>
    <li>
        <ul><h2>Pages</h2>
            <li>About me</li>
            <li>Hobbies</li>
        </ul>
    </li>
    <li>
        <ul><h2>Archives</h2>
            <li>Jan 2007</li>
            <li>Feb 2007</li>
        </ul>
    </li>
</ul>
</div>

When WordPress runs this template, wpta_show_ads() will show the ads according to the style in Ad Links Template Preview.

Using the WP Text Ads widgets

The WordPress Widgets is a drag-n-drop method for modifying the sidebar. This is the alternative method to editing your WordPress templates.

To get WP Text Ads widgets working:

Check that the WordPress Widgets plugin is installed and activated. Your WordPress theme must also support Widgets.
By default, the WordPress Widgets plugin is installed in your 'wp-content/plugins/widgets' directory. After you have installed WP Text Ads, you will find 2 WP Text Ads widget files in that same directory named wpta_sell_widget.php and wpta_show_widget.php.
Go to the Plugins page and activate the 2 plugins named 'WP Text Ads widget' and 'WP Text Ads advertiser widget'.
Go to Presentation → Sidebar Widgets. You should see 2 widgets named 'WP Text Ads' and 'WP Text Ads: Sell Ads'. The first displays text ads and the second displays the link for advertisers to buy ads. Drag them to the Sidebar.

The 'WP Text Ads: Sell Ads' widget will display a link for advertiser to click. That link's text is taken from Options → WP Text Ads → Display Options → Advertiser Link Text. To the right of this widget is also an icon. Upon clicking, you can fill in the Title text. This is equivalent to the header text of each block of sidebar item, like Pages, Archives and Categories.

The 'WP Text Ads' widget will use the data from Options → WP Text Ads → Display Options → Ad Links Template.

Remember to save all changes.

Customizing the advertiser form

The form that advertisers fill in to buy ads at your blog is customizable. The form templates are located in the 'wp-content/plugins/wptextadsX/templates/adforms' directory.

There are 4 templates - buy.html, thanks.html, math_error.html and no_js_incomplete.html.

buy.html - Advertisers fill in this form.
thanks.html - Displays 'Thank you' page after form is filled.
math_error.html - Displayed when a math question is incorrectly answered. Prevents spam.
no_js_incomplete.html - If Javascript is disabled, this is displayed for empty fields.

The templates are saved in the .html extension so that you can easily view your customizations in a browser.

Every template contains template variables. WP Text Ads will replace those variables with data during run-time. There is currently no way to test these templates with real data, so please do not change them unless you know what you are doing.

Besides the templates, there are configuration options presented in Options → WP Text Ads → Display Options → Advertiser Form.

WP Text Ads configuration file

Many configuration options can be changed in WP Text Ads. But a few options that rarely need to be changed are not presented there. You can stay with the default values or tweak them yourself in the wpta_config.php file located in the 'wp-content/plugins/wptextadsX' directory.

Here are the options that you can choose to change, and their default values.

Option	Default	Use
NEHEMIAH_MAX_AJAX_TIMEOUT	30	Seconds before WP Text Ads aborts its AJAX calls.
NEHEMIAH_SPAM_MATH_MAX	50	Largest value for math CAPTCHA in the advertiser form.

Please leave the other options alone or you might break WP Text Ads.

The WP Text Ads API

The WP Text Ads API allows you to create WordPress plugins that use the advertiser data stored in the WP Text Ads database table. This means you can present their ads in your own ways that increase your value proposition!

The API functions are only available if you use WP Text Ads 1.2 and above.

To help you see these API functions in action, I have created some plugins that are built on them. You can find these plugins here. If you have created plugins using the API, tell me and I'll make a mention of it there.

API Functions

Function

Description

wpta_api_get_post_ads($post_id)

Input:

ID of a blog post.

Returns:

An array of associative arrays containing per-post ads that are activated and have not expired. At most 2 links will be returned if you use WP Text Ads Free Edition.

Each associative array contains the following keys:

post_id : ID of this blog post.

ad_url : URL of the text link ad.

ad_text : text description of the ad.

ad_run : Number denoting the ad run in days.

ad_rate : The cost of this ad.

expiry : The expiry date expressed as a UNIX timestamp.

nofollow : Whether this text link uses the rel="nofollow" attribute.

wpta_api_get_blog_ads()

Input:

None.

Returns:

An array of associative arrays containing blog-wide ads that are activated and have not expired. At most 2 links will be returned if you use WP Text Ads Free Edition.

Each associative array contains the following keys:

post_id : Not relevant for blog-wide ads.

ad_url : URL of the text link ad.

ad_text : text description of the ad.

ad_run : Number denoting the ad run in days.

ad_rate : The cost of this ad.

expiry : The expiry date expressed as a UNIX timestamp.

nofollow : Whether this text link uses the rel="nofollow" attribute.

wpta_api_get_home_ads()

Input:

None.

Returns:

An array of associative arrays containing home page ads that are activated and have not expired. At most 2 links will be returned if you use WP Text Ads Free Edition.

Each associative array contains the following keys:

post_id : Not relevant for home page ads.

ad_url : URL of the text link ad.

ad_text : text description of the ad.

ad_run : Number denoting the ad run in days.

ad_rate : The cost of this ad.

expiry : The expiry date expressed as a UNIX timestamp.

nofollow : Whether this text link uses the rel="nofollow" attribute.

wpta_api_get_buy_url($post_id)

Input:	ID of a blog post or leave it empty.
Returns:	A URL that advertisers click on if they wish to puchase ads at your blog. If $post_id is the ID of a blog post, then the advertiser has the extra option of purchasing ads for that post. If left empty, then he can purchase only blog-wide and home page ads.