phpAdsNew is a banner management and tracking system written in PHP.
[faq] [configuration]
[api] [homepage]
[report
bugs] [forum]
As an administrator you need to familiarize yourself with phpAdsNew's backend structure. phpAdsNew gives you three options to include a banner on your site: local mode, remote invocation and remote invocation with JavaScript. It is recommended to use the first method where possible.
This is the traditional style of a including a banner within a PHP-powered website. On every page you want to have a banner, you have to include phpadsnew.inc.php. This file is in your phpAdsNew-installation-directory. Banners are displayed using the view()-function. This function has the following syntax:
int view (mixed what [, int clientID [, string target
[, string source[, bool withText = 0[, array context]]]]);
The view() function does not work well in template-based website's (for example phplib or fasttemplate), because the view() function prints the banner directly to the screen. The banner would appear before the rest of the page is printed. In order to make phpAdsNew work in template based website's there is a function that returns both the html code ($array["html"]) and the banner id ($array["bannerID"]) in an array. The function does not print anything to the screen.
array view_raw (mixed what [, int clientID [, string target
[, string source[, bool withText = 0[, array context]]]]);
It is also possible to use phpAdsNew on sites that lack PHP-support. Random or pre-defined banners can be shown using a standard <img>-construct. Just like in Local Mode, you can use the "what" argument to select the banner.
<a href="click.php"><img src="phpads.php"></a>
To use multiple banners on a single page, select a unique name for each banner and assign it to the "n" argument for both "click.php" and "phpads.php".
Remote Invocation does have some problems and HTML banners won't work at all.
It is recommended to use Remote Invocation with Javascript instead of normal
Remote Invocation.
<a href="click.php?n=ban1"><img src="phpads.php?what=468x60&n=ban1"></a> Show a randomly selected banner of the size 468x60. <a href="click.php?n=top"><img src="phpads.php?what=main&n=top"></a> Show a randomly selected banner from the "main" group with the name "top". <a href="click.php?n=left"><img src="phpads.php?what=468x60&n=left"></a> Show a randomly selected banner of the size 468x60 with the name "left".
This technique allows you to use HTML banners remotely. Just like in Local
Mode, you can use the "what" argument to select the banner. All you
need to do is insert this code:
<script language="JavaScript" src="remotehtmlview.php"></script>
You should also add parameters to the remotehtmlview.php.
<script language="JavaScript" src="remotehtmlview.php?what=main&target=_blank"> </script>
This would show a banner from the main group and, when clicked, a new window would be opened.
The following parameters are used to determine which banners will be displayed. They can be used in local mode and both types of remote invocation. In local mode the parameters will have to be used with the view() function. In remote invocation the parameters need to be added to the phpads.php file. In remote invocation with Javascript the parameters need to be added to remotehtmlview.php.
The "what" parameter is used to specify keywords, discriminate between the different dimensions of the banner, select an html banner or select a banner by identification number.
The "what" parameter can consist of one or more expressions. Each
expression will be executed when the previous expression has failed. Multiple
expression must be separated with the character | and may not be separated by
spaces.
If you don't provide an expression and leave the "what" parameter
empty phpAdsNew match any active banner and will display one randomly.
For example if the first expression does not match any banner the second expression
will be executed. If the second expression does not match any banner the third
expression will be executed. This also means that if the first expression does
match a banner, the second and third expression won't be executed.
You can specify as much expressions as you like, but each additional expression
may require some extra system resources, such a processing time and database
queries.
For example:
RIGHT: expression1
RIGHT: expression1|expression2|expression3
WRONG: expression1 | expression2
Each expression can consist of one or more statements. Each statement tries
to match one or more banners. The simplest expression would only consist of
one statement. phpAdsNew will try to find a banner that matches this statement.
However, it is possible to use multiple statements and use logical operators.
The logical operators look a bit different than the ones used in MySQL and PHP,
but work the same way.
Statements are separated by a comma (,) and statement can begin with a switch
to set the behavior. Do not put a space between the operator and the statement.
If you separate statements without a switch, the separator will become an OR
operator.
statement,statement
Meaning: statement OR statement
If you use the + or _ switch the separator will become an AND operator. Please
note: you can't use the + switch in remote invocation and must use the _ switch,
which means exactly the same.
statement,+statement statement,_statement
Meaning: statement AND statement
If you use the - switch the separator will become a NOT operator. You can use the - switch on the first statement.
statement,-statement Meaning: statement NOT statement
-statement,-statement
Meaning: NOT statement NOT statement
For example
statement1,statement2,statement3
Meaning: statement1 OR statement2 OR statement3 statement1,+statement2,+statement3
Meaning: statement1 AND statement2 AND statement3 statement1,+statement2,-statement3
Meaning: statement1 AND statement2 NOT statement3
OR takes precedence over AND and NOT. AND and NOT have equal precedence. At this moment it is not possible to use parentheses to force precedence!
For example:
statement1,+statement2,statement3 Meaning: (statement1 AND statement2) OR statement3 statement1,+statement2,statement1,+statement3 Meaning: (statement1 AND statement2) OR (statement1 AND statement3)
Meaning: statement1 AND (statement2 OR statement3) statement1,statement2,-statement3 Meaning statement1 OR (statement2 NOT statement3) statement1,-statement3,statement2,-statement3 Meaning (statement1 NOT statement3) OR (statement2 NOT statement3)
Meaning (statement1 OR statement2) NOT statement3
Each statement tries to match a specific property of the available banners.
bannerid:[digits] or [digits]
You can match a banner by looking at the banner ID property. phpAdsNew will
try to find a banner with an ID equal to the digits you specified.
1
Match a banner with ID 1
bannerid:23
Match a banner with ID 23
clientid:[digits]
You can match a banner by looking at the ID of the owner of the banner. phpAdsNew
will try to find a banner, which owner's ID is equal to the digits you specified.
clientid:32 Match a banner which owner had ID 32
[width]x[height]
You can match a banner by looking at the dimension of the banner. phpAdsNew
will try to find a banner with the same width and height you specified. This
will only work for banners stored in MySQL or banners referred through URL.
HTML banners do not have this property and will not be matched when you try
to match a banner with a specific dimension.
468x60
Match a banner with width 468 and height 60
format:[type] or html
You can match a banner by looking at the banner format. phpAdsNew will try to
find a banner with the same format as the type you specified. If you want to
match html banners you can use a shortcut and specify only 'html'.
format:html
Match a banner of type HTML
html
Match a banner of type HTML
[keyword]
You can match a banner by looking at the keywords of the banner. phpAdsNew will
try to find a banner with the keyword you specified. You can use digits in your
keywords, but every keyword must contain at least one character other than a
digit or an 'x'. You can't use a colon (:) in your keywords.
mybanners
Match a banner with keyword "mybanners"
In phpAdsNew you can define global banners. You can add the "global"
keyword to your banners through the admin interface. Every banner with the "global"
keyword will be considered a match.
The behavior only works if you are using one expression with only keywords.
Otherwise you will have to add the "global" keyword to the expressions
by hand.
key1
Meaning: Match a banner with keyword "key1" or "global"
key1|key2,global
Meaning: Match a banner with the keyword "key1". If there are no banners
with this keyword try to match a banner with keyword "key2" or "global"
key1|global
Meaning: Match a banner with the keyword "key1". If there are no matching
banners, match a banner with keyword "global"
In certain conditions you may want to automatically generate keywords and add these to your expression, for example:
$weekday = date("w"); // 0=sunday, 1=monday, etc.
view ("day$weekday");
The above example will try to display a different banner for each day of the
week. On Sunday it will try to display a banner with the keyword "day0",
on Monday it will try to display a banner with the keyword "day1",
etc.
However if you didn't define banners any banner with the keyword "day3".
phpAdsNew will not show any banners on Wednesday. You may want to create a failsafe.
If there are no banners available for a certain day you want to display a general
banner. You could add some new banners and assign the keyword "general"
to them. And use a construction like this :
$weekday = date("w"); // 0=sunday, 1=monday, etc.
view ("day$weekday|general");
The above example will try to display a banner for each day of the week, but if it can't find any banners on a specific day it will try to display a banner with the keyword "general".
key1|main
Match a banner with keyword "key1". If there are no banners with
this keyword try to match a banner with keyword "main"
key1,key2|clientid:3
Match a banner with keyword "key1" or "key2". If there are no banners
with this keyword try to match a banner with client id 3
key1,-clientid:2
Match a banner with keyword "key1", don't match banners with clientid 2.
4|clientid:2,clientid:4|key1|global
Match a banner with id 4. If there are no matching banners try to match a
banner with client id 2 or 4. If there are no matching banners try to match
a banner with keyword "key1". If there are no matching banners try to match
a banner with keyword "global".
html,+key1,+key2,-clientid:2
Match a html banner with keyword "key1" and "key2", but don't match banners
from client with ID 2.
3,+468x60,4,+468x60,5,+468x60
Match a banner with a width of 468 and a height of 60.
The banner ID must be 3, 4 or 5.
key1,-468x60,key2,-468x60
Match a banner with keyword "key1" or "key2".
The banner must not have a width of 468 and a height of 60
The optional argument clientID allows you to retrieve only banners by a specific client. Specify "" to view banners from all clients (in case you need the third or fourth argument, else don't specify it at all).
view("468x60", 1);
The optional argument "target" allow you to specify a frame target
to be used when the user clicks on the ad. For example, use '_blank' to force
a new browser window to open, '_top' to replace the current window (and break
frames), etc. For more information about this parameter you can take a look
at the target attribute in the HTML specification.
view("maingroup", 0, "_blank");
The optional argument "source" allows you to specify the name of the current page (for example: "main page" or "subpage1"). Source ACL can then use this name to allow or deny banner displays on that page.
The optional argument withText allows you to show a banner with its associated line of text below it (for example, "Support our sponsor" is a common line of text). The "WithText" parameter is turned on by default. If want to turn it of you should set this parameter to 0.
view("maingroup", 0, "", 0);
The optional argument "context" is an array specifying banners to limit the search to or/and banners to be excluded from the search. It is an array containing as many associative arrays as you want. The key of the entries must either be "==" to denote a banner to which the search is limited to or "!=" to denote a banner to be excluded from the search. The value of an entry is a banner ID. For example, to show the same randomly selected banner on the top and bottom of a page, you could use the following:
// Top of the page:
$id = view("main", 5);
// Bottom of the page
$arr = array(
array("==" => $id)
);
view("main", 0, "", "", 1, $arr);
To make sure that the page does not show the same banner two times, you could use this:
// Top of the page:
$id = view("main", 5);
// Bottom of the page
$arr = array(
array("!=" => $id)
);
view("main", 0, "", "", 1, $arr);
view(1); Displays the banner with the bannerID of 1.
view("html"); Displays a randomly selected HTML banner
view("468x60", 0, "_blank"); Displays a randomly selected banner with a width of 468 pixels and a height of 60 pixels. If user clicks on it, the target destination will be opened in a new window. view("mybanners"); Displays a randomly selected banner from the group "mybanners" (in other words: with that keyword). view("", 0, "_blank", "Main"); Displays a randomly selected banner which does not have a Deny for Source ACL on "Main"
A sample HTML file could look like this:
<?
require("/usr/local/etc/phpAds/phpadsnew.inc.php");
?>
<html>
<head>
<title>phpAdsNew demo</title>
</head>
<body>
<?
view("468x60");
?>
</body>
</html>