apws.pl Script : Documentation

 
Home > apws.pl > Documentation   Updated: 20-Apr-2009

apws.pl Script Documentation

Browse apws.pl Script Documentation
  1. Installation
  2. Running apws.pl / Parameters
  3. Borders & Styles
  4. Customization
  5. Configuration File
  6. Niche Store
  7. Templates
 
  1. Template Fields: {FieldName}
  2. Virtual Directory
  3. Compatibility with allposters.pl
  4. Inclusion in Existing Webpages
  5. Custom Styles
  6. Revisions History
  7. Support
 

Note:   "cgi-bin" directory
The instructions in this documentation assume that your web server has a directory named cgi-bin where scripts are to be stored on your web server. Some web servers use a different name for this directory, such as: cgi-local, or cgi, or mainwebsite_cgi or something similar. In that case, where you see cgi-bin in any instruction, substitute it with the directory name that your web server uses.



» 1. Installation

The following diagrams illustrate what you will find in the apws.pl .zip file and where those files should be located on your server after you follow the installations instructions below.

Note: Some servers have the cgi-bin directory separate from the publicly visible html files, such as: mainwebsite_cgi for your cgi-bin files, and mainwebsite_html for your html files. So the following diagram may not exactly look like what you have on your server. Ask your hosting company if you don't know where your cgi-bin directory is located.

.zip file:

 

Your server:

Follow these steps to install the apws.pl script:

  1. Download apws.pl .zip file to your computer.

  2. Unzip the .zip file. You should end up with a directory apws-YYMMDD (such as apws-070622).

  3. Run your FTP program and connect to your server.

  4. Go into your cgi-bin directory and create a subdirectory named apws

  5. Go into the newly created subdirectory apws

  6. On your local computer, go into the apws-YYMMDD

  7. Upload apws.pl and apws-ini.txt and apws.dat to your server. Note: Upload these files using ASCII transfer mode. If necessary, change the first line of apws.pl to the path of perl on your server (default is: /usr/local/bin/perl).

  8. Select apws.pl file on your server and do CHMOD 755 (User: read/write/execute; Group: read/execute; Other: read/execute) so that apws.pl can be run.

  9. Select the templates folder (do not go into it) and upload the entire directory. Note: Most FTP programs allows you to upload an entire directory just like you can upload an individual file.

  10. Select the includes folder (do not go into it) and upload the entire directory.

  11. On your server, go to your root directory (the directory where your home page file is located).

  12. Create a subdirectory named apws and then go into it.

  13. On your local computer, select the img directory (do not go into it) and upload the entire directory. Note: Must be uploaded in binary mode since contains .gif/.jpg graphic files.

  14. To test that apws.pl is installed successfully, run your web browser and access DOMAIN.com/cgi-bin/apws/apws.pl (substitute in your own domain name in this URL) and you should see something like what is at www.Million-Posters.com

    500 Internal Server Error
    If you see a "500 Internal Server Error" then follow these steps:

    1. Redownload the .zip file to your Windows PC and unzip it again.

    2. Reupload apws.pl file using ASCII transfer mode (not binary mode!)

    3. Select apws.pl on the server and do CHMOD 755 (User: read/write/execute; Group: read/execute; Other: read/execute)

    4. If necessary, change the first line of apws.pl so it has the correct path to perl on your server (default is /usr/local/bin/perl; try: /usr/bin/perl). If you're not sure, look in any other .pl file on your server that works, or ask your hosting company what is the path to perl.

    5. Test the installation by accessing DOMAIN.com/cgi-bin/apws/apws.pl again. Press your web browser's Refresh/Reload button.

  15. Request an apws-key.txt key file. Note: Until you request and install the key file, apws.pl runs in demo mode and all links have no affiliate ID.

  16. When you receive your key file, upload it to the same directory where apws.pl is located (e.g.: /cgi-bin/apws/).


» 2. Running apws.pl / Parameters

To run apws.pl, access it at:

http://DOMAIN.com/cgi-bin/apws/apws.pl

Parameters can be added at the end of the URL to tell apws.pl what to output. Multiple parameters can be specified. For example, the following parameters would tell apws.pl to output category 976 (Cat posters) displayed in a grid of 2-columns by 4-rows:

http://DOMAIN.com/cgi-bin/apws/apws.pl?cat=976&grid=c:2,r:4

The parameters can be categorized into three groups:

  1. Search criteria
  2. Output formatting
  3. Redirection
  4. Configuration

Search Criteria Parameters

Parameter Default Description

cat

0

AllPosters.com category # to display. To determine a category #, browse through our sample website million-posters.com to the category you want to display and observe the value of the cat parameter in the URL. Category 0 (zero) is the root top-level category.

catok

(none)

Specify this parameter to allow an 'out-of-bounds' category.

If you are using the categories configuration variable to show a subset of categories rather than all categories, normally apws.pl will block access to any category that is outside of this subset, and the user is redirected to the AllPosters.com website. This behaviour can be overridden by specifying the catok parameter thus allowing an 'out-of-bounds' category to be displayed. For example, cat=101&catok will cause category 101 (Movies) to be displayed even if it is an 'out-of-bounds' category.

height

(none)

Limits results to specified product height range. This parameter enables you search for products of a particular height (e.g.: all posters less than 20 inches in height). Examples:

Example Meaning
20 exactly 20 inches
-20 up to and including 20 inches
20- 20 inches or greater
10-20 between 10 and 20 inches (inclusive)

Defaults to the value of the similarly named configuration variable height

keywords

(none)

Keywords to search for. The characters +, |, and > have special meaning:

  • +  Multi-word keywords
    For multi-word keywords (e.g.: "Tom Hanks"), separate each word with a + (plus sign). For example, keywords=tom+hanks

  • |  Alternate keywords (left-to-right order)
    Separate each alternate with a | character. For example, keywords=tom+hanks|harrison+ford|julia+roberts The keywords are tried in left-to-right order until a non-empty result is found.

  • >  Alternate keywords (right-to-left order)
    Separate each alternate with a > character. For example, keywords=Subjects>Animals>Domestic+Animals>Cats>Kittens The keywords are tried in right-to-left order until a non-empty result is found (e.g.: Kittens, then Cats, then Domestic Animals, then Animals, then Subjects). To skip a particular keyword, preceed it with a dash (e.g.: keywords=-Subjects>...)

price

(none)

Limits results to specified product price range. This parameter enables you search for products of a particular price (e.g.: all posters less than $20 in price). Units of this parameter are specified via the currency parameter. Examples:

Example Meaning
20 exactly $20.00
-20 up to and including $20.00
20- $20.00 or greater
10-20 between $10.00 and $20.00 (inclusive)

Defaults to the value of the similarly named configuration variable price

search

(none)

Use pre-defined search defined in the configuration file. For example, search=hanks would use the search parameters defined in the search.hanks configuration variable. For example:

search.hanks "keywords=tom+hanks&grid=c:2,r:3"

Pre-defined searches can contain search criteria parameters as well as output formatting parameters.

sort

PD

Sort order.

Value Meaning
PD Popularity, decreasing
RD Relevancy, decreasing
CA Price, ascending
CD Price, descending
TD Title, descending
TA Title, ascending
DD Date, descending
DA Date, ascending
AD Artist, descending
AA Artist, ascending

Defaults to the value of the similarly named configuration variable sort

width

(none)

Limits results to specified product width range. This parameter enables you search for products of a particular width (e.g.: all posters less than 20 inches in width). Examples:

Example Meaning
20 exactly 20 inches
-20 up to and including 20 inches
20- 20 inches or greater
10-20 between 10 and 20 inches (inclusive)

Defaults to the value of the similarly named configuration variable width


Output Formatting Parameters

Parameter Default Description

border

shadow

Type of border to appear around images. Possible values are: none, outline, shadow, mounted, framed, framed2, framed3, ..., framed10. See: Borders & Styles.

Defaults to the value of the similarly named configuration variable border

currency

USD

Currency to use for prices. Possible values are: USD, AUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, NOK, NZD, SEK, SGD, ZAR.

Defaults to the value of the similarly named configuration variable currency

grid

c:3,r:6

Grid layout. Various options can be specified, each separated by a comma, and options can be specified in any order.

Option Meaning
c:NUMBER NUMBER-columns, unlimited-rows (to end of page)
r:NUMBER NUMBER-rows (defaults to 3-columns)
top Align to top of rows
middle Align to middle of rows
bottom Align to bottom of rows
pack Pack rows and make them variable height rather than fixed height.

Examples:

Example Meaning
c:2 2-columns, unlimited-rows (to end of page)
r:4 4-rows (defaults to 3-columns)
c:2,r:4 2-columns, 4-rows
r:4,c:2 2-columns, 4-rows --- same as c:2,r:4

Defaults to the value of the similarly named configuration variable grid

iframe

(none)

Fomat the output so that it can be used as the source of a <IFRAME> tag so that results can be embedded into a webpage. Example:

<iframe href="/cgi-bin/apws/apws.pl?iframe&cat=101">

kids

yes

Display links to sub-categories ("kids") of the current category.

Defaults to the value of the similarly named configuration variable kids

kids.cols

(none)

Number of columns (1, 2, or 3) to use when displaying links to sub-categories ("kids") of the current category. Defaults to the value of the similarly named configuration variable kids.cols. If no value is specified, then a suitable number of columns is automatically used based on the number of links.

Defaults to the value of the similarly named configuration variable kids.cols

language

1

Language to use for products. Possible values are:

Value Meaning
1 English
2 French
3 German
4 Spanish
5 Italian

Defaults to the value of the similarly named configuration variable language

large

(none)

Specified whether to use large images or thumbnail images. When the large parameter is specified, the grid is automatically set to 1-column. When using large images, it is recommended that the number of rows be kept low, such as 5-rows or less by setting grid r option or by setting size.

Possible values for the large parameter are:

  • large=no
  • large=yes or large without any value
  • WIDTHxHEIGHT (e.g.: 400x300)

Values of the format WIDTHxHEIGHT allow you to specify a maximum width/height for the image. Thus if you find that the standard large images are too large for your website layout, you can shrink them down via this configuration variable. For example, 400x300 specifies a maximum width of 400 pixels and a maximum height of 300 pixels. If the image is large than either of the specified limits, the image is scaled down to fit. If the image is smaller than both specified limits, the image is left as is -- the image is not scaled up.

Defaults to the value of the similarly named configuration variable img.large

navbar

yes

Display navigation bar ("navbar") at the top of pages so can link to parent categories of the current category.

Defaults to the value of the similarly named configuration variable navbar

nokids

(none)

Overrides the kids configuration variable so that links to sub-categories (a.k.a.: "kids") are not displayed. To disable "kids" on a global basis, set the kids configuration variable to no

nopagebar

(none)

Overrides the pagebar configuration variable so that the pagebar is not displayed. To disable the pagebar on a global basis, set the pagebar configuration variable to no

noself

(none)

When apws.pl links back to itself (e.g.: link to a sub-category), parameters in the original URL appear in these self links too -- the parameters are sticky. The noself parameter allows you to turn off stickiness of the specified parameters. You can specify one or more parameter names in noself, separate each with a comma. For example, /cgi-bin/apws/apws.pl?grid=c:2&large&noself=large,grid would make large and grid non-sticky and they would not appear in self links.

page

1

Page to display. First page is 1. See size parameter to select size of each page.

pagebar

yes

Display page bar at the bottom of pages so can link to continuation pages.

Defaults to the value of the similarly named configuration variable pagebar

php

(none)

Fomat the output so that results can be embedded into a PHP webpage. Example:

virtual("/cgi-bin/apws/apws.pl?php&cat=101");

script

(none)

Fomat the output so that it can be used as the source of a <SCRIPT> tag so that results can be embedded into a webpage. Example:

<script src="/cgi-bin/apws/apws.pl?script&cat=101"
TYPE="text/jscript"></script>

search

(none)

Use pre-defined search defined in the configuration file. For example, search=hanks would use the search parameters defined in the search.hanks configuration variable. For example:

search.hanks "keywords=tom+hanks&grid=c:2,r:3"

Pre-defined searches can contain search criteria parameters as well as output formatting parameters.

size

18

Page size specifying number of products to show per page. Maximum is 200. If there are more products than will fit on one page, a pagebar is displayed. See page parameter to select subsequent pages.

Note: If the size parameter is greater than the grid size (#-of-columns X #-of-rows) then size is automatically decreased to the grid size. This adjustment thus makes the page parameter work as expected to show subsequent pages.

skip

0

Number of items to skip forward on the page. This parameter allows you to start displaying products starting at an offset from the first item on the page. This parameter is useful when you include two (or more) calls to apws.pl in an existing webpage and each call has a different page/grid size but you still want the posters to appear sequential.

For example, suppose you have an SSI at the top of your page that displays a grid of 3-columns by 1-row, followed an article, and then a grid of 2-columns by 2-rows. The first grid should display products #1, #2, and #3. Then the second grid should display products #4 through #7. To do that, the second SSI needs to skip forward by 3 since the first SSI displays the first 3 products:

<!--#include virtual="/cgi-bin/apws/apws.pl?cat=101&grid=c:3,r:1"-->
(some article text ...)
<!--#include virtual="/cgi-bin/apws/apws.pl?cat=101&grid=c:2,r:2&skip=3"-->

sort

PD

Sort order.

Meaning Meaning
PD Popularity, decreasing
RD Relevancy, decreasing
CA Price, ascending
CD Price, descending
TD Title, descending
TA Title, ascending
DD Date, descending
DA Date, ascending
AD Artist, descending
AA Artist, ascending

Defaults to the value of the similarly named configuration variable sort

ssi

(none)

Fomat the output so that it can be used as the source of a SSI (server-side-include) tag so that results can be embedded into a webpage. Example:

<!--#include virtual="/cgi-bin/apws/apws.pl?ssi&cat=101"-->

style

1

Item details layout style. Specifies the style to use when displaying the details of each item. Possible values are: 1, 2, 3, 4, 5, 6. See: Borders & Styles.

template

default

Template file to use to display page. Default is the value specified by the cat parameter, otherwise uses "default" which uses file default.html. Do not include the filename ending ".html".

Note: script, ssi, php and iframe take precedence over template.

version

(none)

Displays program version information. Example:
/cgi-bin/apws/apws.pl?version


Redirection Parameters

Parameter Default Description

gocat

(none)

Redirect to the specified category at the AllPosters.com website. For example, to redirect to category 101 (Movies):
/cgi-bin/apws/apws.pl?gocat=101

gohome

(none)

Redirect to the home page of the AllPosters.com website. Example:
/cgi-bin/apws/apws.pl?gohome

goitem

(none)

Redirect to the specified item at the AllPosters.com website. For example, to redirect to item 1234:
/cgi-bin/apws/apws.pl?goitem=1234

goitemframed

(none)

Redirect to the "framing" page at the AllPosters.com website for the specified item. For example, to redirect to item 1234 framed:
/cgi-bin/apws/apws.pl?goitemframed=1234

goitemmounted

(none)

Redirect to the "mounting" page at the AllPosters.com website for the specified item. For example, to redirect to item 1234 mounted:
/cgi-bin/apws/apws.pl?goitemmounted=1234

gosearch

(none)

Redirect to the keywords search results page at the AllPosters.com website for the specified search keywords. For example, to redirect to keywords search for "tom hanks":
/cgi-bin/apws/apws.pl?gosearch=tom+hanks

Parameter gosearch can be combined with cat parameter to limit results to a specified category.


Configuration Parameters

Parameter Default Description

cfg

(none)

An additional configuration file can be loaded by using the cfg parameter. For example, cfg=blog would cause the configuration file blog-ini.txt to be loaded (if it exists). This configuration file is loaded last, after all other configuration files and the key file.



» 3. Borders & Styles


Borders

The various borders available via the border parameter and border configuration variable are:

border=none

Buy Mona Lisa at AllPosters.com

border=outline

Buy Mona Lisa at AllPosters.com

border=shadow

Buy Mona Lisa at AllPosters.com

border=mounted

Buy Mona Lisa at AllPosters.com

border=framed
(Box Stem Black)

Buy Mona Lisa at AllPosters.com

border=framed2
(SoHo Black)

Buy Mona Lisa at AllPosters.com

border=framed3
(Sovia Flat Black)

Buy Mona Lisa at AllPosters.com

border=framed4
(Sovia Medium Brown)

Buy Mona Lisa at AllPosters.com

border=framed5
(Geppetto Dark Brown)

Buy Mona Lisa at AllPosters.com

border=framed6
(Alchemy Soft Gold)

Buy Mona Lisa at AllPosters.com

border=framed7
(Allure Gold)

Buy Mona Lisa at AllPosters.com

border=framed8
(Rococo Gold)

Buy Mona Lisa at AllPosters.com

border=framed9
(Alchemy Warm Silver)

Buy Mona Lisa at AllPosters.com

border=framed10
(Orleans Warm Silver)

Buy Mona Lisa at AllPosters.com

 


Styles

The various styles available via the style parameter and style configuration variable are:

style=1

Mona Lisa
Art Print
24" x 36"
$24.99
Unframed
Framed   Mounted

style=2

Mona Lisa
Art Print
24" x 36"
$24.99

style=3

Mona Lisa
24" x 36"
$24.99
Buy this Art Print at AllPosters.com

style=4

Mona Lisa
Leonardo da Vinci

style=5


Mona Lisa
Leonardo da Vinci

style=6

style=7

Mona Lisa
Buy Now

   

For those styles that display the product's price, you can hide the price by setting the price.show configuration variable to no

See also: Custom Styles if you want to customize the styles or create your own style.



» 4. Customization

Customization is possible through the apws-ini.txt configuration file and also through template files in the cgi-bin/apws/templates directory.


» 5. Configuration File

Customization is possible through the apws-ini.txt configuration file. It is a text file located in the same directory where apws.pl is located. You can edit the file using any plain text editor such as Windows Notepad.


Configuration File Format:

To set a variable, use the line with the following format:

VariableName "VariableValue"

If you want to include a " (quotation mark) in the VariableValue, then use any of these alternate formats:

VariableName 'VariableValue'
VariableName [VariableValue]
VariableName {{VariableValue}}

Blank lines and leading spaces are ignored.

Everything afer a # character is ignored as a comment.


Configuration Variables:

The table below describes the configuration variables:

border

Variable Default Description

border

shadow

Default value for the border parameter.

cache.*

Variable Default Description

cache.dir

cache

Cache directory. Relative to the directory where apws.pl is located.

cache.compress

yes

yes = Compress the cache to save disk space.
no = Do not compress the cache.

cache.stale

3days

Cache stale time (in hours). For units other than hours, add a units suffix: days, months, years.

cache.size

1MB

Cache size (in bytes). For units other than bytes, add a units suffix: KB or MB.

cat.* -- categories

Variable Default Description

cat.none.redirect

yes

yes = Redirect to category at AllPosters.com if no results.
no = Show "no results" message if no results.

Note: "No results" message is defined by format.noresults configuration variable.

catdel.NUMBER

(none)

Causes category NUMBER to be deleted; it will not appear in the list of sub-categories. Any access to category NUMBER, or any of its sub-categories, will redirect to that category at the AllPosters.com website. See also: catdelkids and catkeep. For example, to delete "Movies" (category 101) use:

catdel.101 yes

Note: The yes is required. If you leave it out, an error will be reported when you run apws.pl

catdelkids.NUMBER

(none)

Causes sub-categories of category NUMBER to be deleted; it will appear that category NUMBER has no sub-categories. Any access to sub-categories of category NUMBER will redirect to that category at the AllPosters.com website. See also: catdel and catkeep.

catkeep.NUMBER

(none)

Causes category NUMBER, and sub-categories of it, to be visible. This configuration variable enables you to make accessible specific sub-categories that have been deleted by catdel and catdelkids. Thus, for example, you could delete all Animals posters and then make Cats and Dogs posters (which are sub-categories of Animals) visible. See also: catdel and catdelkids.

For example, to delete all sub-categories of Domestic Animals (41641) except for Cats (976) and Dogs (977) categories, use the following three configuration variable settings:

catdelkids.41641 # delete all kids of Domestic Animals
catkeep.976 # keep Cats
catkeep.977 # keep Dogs

catlocal.NUMBER

(none)

Causes category NUMBER, and sub-categories of it, to be local. This configuration variable enables you to make local specific sub-categories that have been made remote by catremote and catremotekids. Thus, for example, you could make all Animals posters remote and then make Cats and Dogs posters local. See also: catremote and catremotekids.

catname.0

Posters

Name of root category.

catname.none

Posters

Name of nameless results.

catnoitems

no

Leave this configuration variable undefined unless required.

Specifies the category to display if nothing to display. Defaults to catroot value if non-zero, or to 18979 (Posters > Featured Categories > Best Sellers).

catremote.NUMBER

(none)

Causes category NUMBER to be remote. Any access to category NUMBER, or any of its sub-categories, will redirect to that category at the AllPosters.com website. See also: catremotekids and catlocal.

catremotekids.NUMBER

(none)

Causes sub-categories of category NUMBER to be remote; category NUMBER is displayed locally. Any access to sub-categories of category NUMBER (but not to category NUMBER itself) will redirect to that category at the AllPosters.com website. See also: catremotekids and catlocal.

categories

(none)

Category to display as root category. The root category is accessed by using parameter cat=0 or by not specifying the cat parameter.

If set to 0 (zero) then the top-level root category of AllPosters.com is displayed as the root category. Thus all poster categories and sub-categories are available to be displayed.

If set to a NUMBER then that category is displayed as the root category. For example, setting categories to 622 would cause the Animals category (category 622) to be displayed as the root category.

If set to a comma-separated list of numbers would cause those categories to be displayed as the root category. For example, setting categories to 622,101,290 would cause the Animals, Movies, and Sports categories to be displayed as the root category.

currency.*

Variable Default Description

currency

(none)

Default value for the currency parameter.

currency.prefix

$

Currency prefix.

If you use the language parameter or the language configuration variable, apws.pl will use currency.prefix.LANGUAGEID if it is defined, otherwise currency.prefix will be used.

currency.suffix

(none)

Currency suffix.

If you use the language parameter or the language configuration variable, apws.pl will use currency.suffix.LANGUAGEID if it is defined, otherwise currency.suffix will be used.

format.*

Variable Default Description

format.link.framed

Framed

Text for "Framed" link.

format.link.unframed

Unframed

Text for "Unframed" link.

format.link.mounted

Mounted

Text for "Mounted" link.

format.navbar

 

Formatting string for navbar. Default is:

<p class='apwsNavbar'>{navbar}</p>

The formatting string can contain any HTML. The navbar will be substituted in where {navbar} appears in the formatting string.

Note: The default formatting string uses class='apwsNavbar' thus allowing you to style the navbar by simply defining class apwsNavbar in CSS.

format.pagebar

 

Formatting string for pagebar. Default is:

<p class='apwsPagebar'><b>pages:</b> {pages}</p>

The formatting string can contain any HTML. The pagebar will be substituted in where {pages} appears in the formatting string.

Note: The default formatting string uses class='apwsPagebar' thus allowing you to style the pagebar by simply defining class apwsPagebar in CSS.

format.pagebar.remote

 

Formatting string for pagebar when the pagebar.remote configuration variable is set to yes. Default is:

<p class='apwsPagebar'><a href='{link}'>Click here for more {form.keywords} in {name} ...</a></p>

The formatting string can contain any HTML. The URL to the category/search results page at AllPosters.com will be substituted in where {link} appears in the formatting string.

Note: The default formatting string uses class='apwsPagebar' thus allowing you to style the pagebar by simply defining class apwsPagebar in CSS.

format.noresults

 

Formatting string for message when no results. Default is:

<p class='apwsNone'>Nothing found</p>

The formatting string can contain any HTML.

Note: The default formatting string uses class='apwsNone' thus allowing you to style the message by simply defining class apwsNone in CSS.

format.template.script

 

Template formatting string to use when script parameter is specified. Default is:

{results}

The formatting string can contain any HTML.

format.template.ssi

 

Template formatting string to use when ssi parameter is specified. Default is:

{results}

The formatting string can contain any HTML.

format.template.iframe

 

Template formatting string to use when iframe parameter is specified. Default is:

<html><body bgcolor="white" leftmargin="0" topmargin="0" marginwidth="0" marginheight="0">{results}</body></html>

The formatting string can contain any HTML.

format.template.default

 

Template formatting string to use when no other formatting template selected. Default is:

<html><head><title>{name}</title></head><body bgcolor="white">{results}</body></html>

The formatting string can contain any HTML.

grig -- language

Variable Default Description

grid

(none)

Default value for the grid parameter.

height

(none)

Default value for the height parameter.

img.absurl

no

Specifies whether to make image URL's absolute (start with the server's domain name instead of just relative "/"). Useful if you are calling apws.pl remotely from another server.

Note: Images URL are automatically made absolute if parameters absurl, script, or iframe are specified.

img.dir

apws/img

Images directory (relative to directory where your home page file is located). The images directory contains graphic files to generate the border/frame/shadow effect around images.

The apws.pl .zip file contains the img directory that you should have uploaded during the installation procedure.

img.large

no

Default value for the large parameter. Possible values are:

  • yes
  • no
  • WIDTHxHEIGHT (e.g.: 400x300)

Values of the format WIDTHxHEIGHT allow you to specify a maximum width/height for the image. Thus if you find that the standard large images are too large for your website layout, you can shrink them down via this configuration variable. For example, 400x300 specifies a maximum width of 400 pixels and a maximum height of 300 pixels. If the image is large than either of the specified limits, the image is scaled down to fit. If the image is smaller than both specified limits, the image is left as is -- the image is not scaled up.

Note: If you always display large images, it is advisable to set the number of grid rows to a small number (e.g.: 1 through 5) otherwise the page may take some time to load, particularly on slow internet connection.

kids

yes

yes = Show category kids (sub-categories).
no = Do not show category kids.

kids.cols

0

Number of columns in category kids list (0, 1, 2, or 3). The special value 0 causes apws.pl to automatically choose the number of columns based on the number of kids.

language

(none)

Default value for the language parameter.

links.*

Variable Default Description

links.newwindow

no

yes = Links open new windows.
no = Links stay in the current window.

links.newwindow.target

_blank

Target of links when they open a new window. Applies only when links.newwindow is set to yes.

links.relurl

yes

yes = Use relative links when referring to self.
no = Use absolute links when referring to self.

navbar.*

Variable Default Description

navbar

yes

yes = Show navbar.
no = Do not show navbar.

navbar.linked

yes

yes = Link the navbar to self.
no = Do not link the navbar.

navbar.prefix

(none)

Prefix to navbar. This string is appended before the navbar. It can contain any HTML. Typically would be used to add a "Home" link at the start of the navbar, such as:

navbar.prefix "<a href='/'>Home</a>"

navbar.separator

" > "

Navbar link separator. Appears between each link in the navbar.

pagebar.*

Variable Default Description

pagebar

yes

yes = Show pagebar.
no = Do not show pagebar.

The format of the pagebar is specified in the format.pagebar configuration variable.

pagebar.back

"&laquo;back"

Text of pagebar "back" link.

The default value appears as: «back

pagebar.next

"next&raquo;"

Text of pagebar "next" link.

The default value appears as: "next»"

pagebar.separator

"|"

Pagebar page separator.

pagebar.maxpages

50

Maximum pages on pagebar.

pagebar.remote

no

yes = Pagebar has links to AllPosters.com.
no = Pagebar has links to self.

See format.pagebar.remote configuration variable.

price.*

Variable Default Description

price

(none)

Default value for the price parameter.

price.show

yes

yes = Show prices.
no = Do not show prices.

search.*

search.NAME

(none)

Define search parameters. To access a pre-defined search in search.NAME, use parameter search=NAME

For example, to define a search named hanks that does a keyword search for "Tom Hanks" (he is an actor) and outputs as a grid of 2-columns by 3-rows, set the configuration variable search.hanks as:

search.hanks "keywords=tom+hanks&grid=c:2,r:3"

To use this pre-defined search, use parameter search=hanks

search.default

(none)

Default pre-defined search to be used if no parameters specified.

For example, to have Cats posters displays if no parameters are specified, then define:

search.default "cats=976"

Note: This does not change the root category. To do that, use the categories configuration variable.

search.random

(none)

Pre-defined search to be used when search=random is used. This pre-defined search is applied before a randomly selected search from search.random.* is applied. Thus you can apply a common set of parameters to all your random searches such as output parameters (e.g.: search.random "grid=c:3,r:4").

Note: You can leave the pre-defined search search.random undefined and still define search.random.*

search.random.*

(none)

Pre-defined random searches to be used when parameter search=random is used. One of the pre-defined searches from search.random.* is randomly choosen and applied. Note: If search.random is defined, it is applied first and then a randomly chosen pre-defined search is applied.

size -- template.*

size

18

Items per page.

sort

(none)

Default value for the sort parameter.

style

1

Default value for the style parameter.

template

(none)

Default value for the template parameter.

template.dir

templates/1

Templates directory. Relative to the directory where apws.pl is located.

The apws.pl .zip file contains the templates directory that you should have uploaded during the installation procedure.

Four template sets are provided in the apws.pl .zip file. To see the other template sets, change template.dir to templates/2 or to templates/3 or to templates/4

virtual.*

Variable Default Description

virtual.dir

(empty)

Name of virtual directory. If empty, then Virtual Directory is disabled. See: Virtual Directory. Note: If you enable Virtual Directory, virutal.dir must match the directory name that you have specified in your .htaccess file.

virtual.ending

/

Specifies the ending that is used at the end of Virtual Directory URL's. Some possible values:

virtual.ending Example URL Meaning

 

/posters/cat-976

URL looks like a file without an ending

/

/posters/cat-976/

URL looks like a directory

/index.html

/posters/cat-976/index.html

URL looks like a index.html file

.html

/posters/cat-976.html

URL looks like a .html file


virtual.named

yes

Specified whether to include the named portion in the virtual directory URL. The named portion is based on the category path. Example URL's for category 19816 ("Subjects > Animals > Domestic Animals > Cats > Kittens"):

With virtual.named yes:
/posters/subjects/animals/domestic-animals/cats/kittens/-/cat-19816/

With virtual.named no:
/posters/cat-19816/

virtual.named.length

0

Maximum number of directories to include in the named/keyword portion of a virtual directory URL:

  • Zero (0) means no limit.
  • Positive number (1, 2, 3, ...) limits number of directories, counting from the start.
  • Negative number (-1, -2, -3, ...) limits number of directories, counting from the end of named portion. Particularly useful is the value -1 which limits the named portion to just the last directory.

virtual.named.skip

1

Number of leading keywords to skip when generating the named/keyword portion of a virtual directory URL. The default is 1 since the first keyword the name of the root category (typically, "Posters").

virtual.named.empty

no

Specifies whether to include the directory /-/ if there are no keywords in the named portion of a virtual directory URL. (Note: Applies only if virtual.named is true).

width -- www.host

Variable Default Description

width

(none)

Default value for the template parameter.

www.host

 

The domain name to use when processing SSI (server-side-include) back to your server. Defaults to your web server's domain name (from HTTP_HOST http header). In some situations, such as load balance servers, self requests must be to "http://local/" rather than "http://domain.com/". In that case, set www.host to "local".

See the apws-ini.txt file for any other configuration variables that are not documented above.


Configuration Report:

To view the Configuration Report showing the loaded configuration, access /cgi-bin/apws/apws.pl?cfg=CFGVALUE where CFGVALUE is the value of the cfg variable found in your apws-key.txt file. The Configuration Report is organized into collapsible/expandable sections. Click a section to expand it open and see its details.


» 6. Niche Store

By setting the categories configuration variable, you can configure apws.pl to create a niche store that displays products from only a particular category (and its sub-categories) such as only Cats posters. You can also coinfugre apws.pl to display products from a set of categories (and their sub-categories) such as only Movie posters, Music postes, and Sports posters.


One Category (e.g.: Cats)

Edit apws-ini.txt and set the categories configuration variable to the category number that you want to appear at the root category. For example, to display Cats posters (category 976) at the root category, use:

categories 976

Once categories has been set, any access to a category that is outside of this category (e.g.: Travel posters, category 621) will automatically redirect the user to the accessed category at the AllPosters.com website.


Set of Categories (e.g.: Movies, Music, and Sports)

categories Configuration Variable

Edit apws-ini.txt and set the categories configuration variable to the category numbers that you want to appear at the root category. separate each category number by a comma (,). For example, to display Movies posters (category 101) and Music posters (category 122) and Sports posters (category 290) at the root category, use:

categories 101,122,290

A bulleted list of these categories will appear at the root category. The order of the list will be the same order that you specify the categories in the categories configuration variable.

Once categories has been set, any access to a category that is outside of these categories (e.g.: Travel posters, category 621) will automatically redirect the user to the accessed category at the AllPosters.com website.

catnoitems Configuration Variable

You should also set the catnoitems configuration variable. Thumbnails from this category will show up at the root category. If you do not set catnoitems then it defaults to category 18979 (i.e.: Posters > Featured Categories > Best Sellers). For example, to display thumbnails of Movies posters (category 101) at the root category, use:

catnoitems 101

You would typically set catnoitems to one of the categories that you are using in the categories configuration variable. For example, if you have categories 101,122,290 then you might use catnoitems 101


» 7. Templates

Customization is possible through template files in the cgi-bin/apws/templates directory.

Four template sets are provided in the .zip file. During the installation process, you should have uploaded the templates directory to /cgi-bin/apws/templates


Million-Posters.com

(templates "set1")


Million-Posters.com

(templates "set2")


Million-Posters.com

(templates "set3")


Million-Posters.com

(templates "set4")

The template files to use are specified via the template.dir configuration variable as well as the optional template parameter. By default, template.dir is set to templates/1 which causes the templates in /cgi-bin/apws/templates/1 to be used. For example, to use template set 2, change template.dir to templates/2

You can use these templates as is, or modify them in your HTML editor, or create your own from scratch.


Create Template File to Match Your Website

To create a template file that matches the look-and-feel of your website, do the following steps:

  1. Take one of your webpage files (e.g.: your "About Us" page) and copy it to default.html somewhere on your local computer. Making a copy ensures that you do not accidentally overwite the original file!

  2. Cut out the contents portion of the webpage.

  3. At the location in the webpage where you want the poster results to appear, add the following field code:

    {results}

    Note: Those are curly braces shift-[ and shift-], they are not parentheses.

    For example, your template might now be:

    <html>
    <head><title>Posters</title></head>
    <body background="img/back.gif">
    <center><a href="home.html"><img src="img/logo.gif"></a></center>
    <h1>Posters</h1>
    {results}
    </body>
    </html>
  4. Edit all file references so that they start with a leading / character (see next section "Template Files and Broken Graphics" for full details). For example:

    <html>
    <head><title>Posters</title></head>
    <body background="/img/back.gif">
    <center><a href="/home.html"><img src="/img/logo.gif"></a></center>
    <h1>Posters</h1>
    {results}
    </body>
    </html>
  5. (optional) Edit the <TITLE> tag so that the title is more descriptive of the results. The field code {name*} returns the name of the results.

    <title>Posters: {name*}<title>
  6. Using a plain text file (e.g.: Windows Notepad editor or other .txt editor), edit the text file apws-ini.txt (included in the .zip file) and change the template.dir configuration variable:

    template.dir "."
  7. Upload default.html and apws-ini.txt to the same directory where apws.pl is located.

  8. Access http://www.domain.com/cgi-bin/apws/apws.pl and ensure that the page appears correct. If graphics are broken, go back and edit your default.html file.


Template Files and Broken Graphics

If you create your own template files, you must ensure that all <IMG> tags have SRC's that start with a / character or with http:// such as SRC="/logo.gif" or SRC="http://www.mydomain.com/logo.gif"

Relative URL's such as in SRC="logo.gif" will result in broken graphics showing up. Fix this problem by adding a / character to the start of the URL (e.g.: SRC="/logo.gif") or use an absolute URL (e.g.: SRC="http://www.mydomain.com/logo.gif").

The problem is caused by the fact that when apws.pl is run, the URL being accessed in the web browser is http://www.mydomain.com/cgi-bin/apws/apws.pl. A relative URL such as "logo.gif" is relative to the current directory and is thus interpreted as http://www.mydomain.com/cgi-bin/apws/logo.gif -- This is clearly not what you intended to be accessed and will result in a broken graphic. By adding a / character, "/logo.gif" is thus interpretted as http://www.mydomain.com/logo.gif

Note about sub-directories: The above example of logo.gif assumes that logo.gif is located in the root directory. If logo.gif where located in a sub-directory such as at "/img/logo.gif" then, obviously, the correct <IMG> SRC value would be SRC="/img/logo.gif" The full path, starting at the root directory, needs to be specified.

This requirement to start all file references with a leading / character or with http:// applies to all file and image references.

To save time editing your template file, you may want to do the following search-and-replace operations:

Search For Replace With Description

BACKGROUND="

BACKGROUND="/

Fix backgrounds in all <BODY>, <TR> and <TD> tags.

HREF="

HREF="/

Fix HREF's in all links.

SRC="

SRC="/

Fix SRC's in all <IMG> and <SCRIPT> tags.

'img/

'/img/

Fix references to img/ directory.

Note: If your images are in a different directory, then search-and-replace for it instead. Example: Search for 'images/ and replace with '/images/

Note the presence of ' apostrophe. Such references typically occur within link OnMouseOver attributes for "mouse over" hilight effects.

"//

"/

Remove extraneous / introduced by above search-and-replace operations.

"/http

"http

Remove extraneous / introduced by above search-and-replace operations.

Note: The last two search-and-replace operations above should remove any extraneous leading / characters that were erroneous introduced by the earlier search-and-replace operations.


Category Specific Template Files

It is possible for each category or sub-category to have its own template. For example, you may want to use one template for Movie posters (category 101) and a different template for Music posters (category 122). On your Movies template you might include links to DVD's, and on your Music template you might include links to music CD's.

Save your template in the templates directory (e.g.: /cgi-bin/apws/templates/) and name it number.html based on the category number number. For example, the template for Movies (category 101) would be named 101.html and the template for Music (category 122) would be named 122.html

The template for a category is also used for all of that category's sub-categories unless the sub-category itself has its own template file. The sub-category "inherits" the template from its parent category. For example, the template for "Movies" (category 101) would also be applied to the sub-category "Movies > Movie Genres > Comedies" (category 1957). To determine what template to use for a sub-category, apws.pl looks for a template for that sub-category; if not found, apws.pl tries again with the sub-category's parent category and potentially "walks" all the way up to the root category (category 0); if nothing found, then tries the default template file default.html; if not found, then uses the built-in "plain vanilla" template file. If you do not want a template to be inherited by its sub-categories, include the HTML comment <!--noinherit--> in the template; this comment will cause the template to be skipped during the "walk" up to the root.


Template Fields: {FieldName}

When apws.pl runs, it fetches product data from the AllPosters.com website based on the search criteria you specify, and then merges it into the template file, and then outputs the resulting HTML to the user.

To do the merging, apws.pl looks in the template for fields. Fields are placeholders where data will be substituted in and appear as {FieldName} such as {name} for the category name and {results} for the results of the search.

See the sample templates to learn from example how fields are used. For a description of available fields, see the next section in this documentation.


» 8. Template Fields: {FieldName}

When apws.pl runs, it fetches product data from the AllPosters.com website based on the search criteria you specify, and then merges it into the template file, and then outputs the resulting HTML to the user.

To do the merging, apws.pl looks in the template for fields. Fields are placeholders where data will be substituted in and they appear as {FieldName} such as {name} for the category name and {results} for the results of the search.


Template Fields: {FieldName}

The following table describes the template fields:

Field Description

caturl.NUMBER

URL to category NUMBER at the AllPosters.com website.

caturl.best

URL to category "Bestsellers" at the AllPosters.com website. The actual category number is specified by the cat.best configuration variable (default is 18979).

catname.NUMBER

Category name of category NUMBER. See also kids.NUMBER

kids

Bulleted list (<UL>) of sub-categories (a.k.a.: "kids") of the current category. Depending upon the number of items in the list, the list will be either 1-column (1 to 4 items), 2-columns (5 to 30 items) or 3-columns (31 or more items). See kids.cols configuration.

kids.NUMBER

Bulleted list (<UL>) of sub-categories (a.k.a.: "kids") of category NUMBER. The list is always one-column so it can be used in the sidebar of your webpage. See also catname.NUMBER

Tip: To change the style of the list, place {kids} inside a <DIV> tag and use CSS to style its contents. Example:

<STYLE TYPE="text/css">
  DIV.sidebar P { font-size: xx-small; font-weight: bold; margin-bottom: 0px }
  DIV.sidebar UL { list-style-type: none; margin-top: 0px; margin-left: 8px; font-size: xx-small }
</STYLE>
<DIV CLASS="sidebar">
  <p> {catname.101} </p>
  {kids.101}
</DIV>

merch.fullname

The merchant's full name, "AllPosters.com".

merch.home

URL to the AllPosters.com homepage (with your affiliate ID).

merch.id

Your affiliate ID found in your apws-key.txt key file. If there is no key, then this returns "demo".

merch.name

The merchant's name, "AllPosters.com".

name

The name of the results. If the search is for a category then this field returns the category name (e.g.: "Movies" for category 101). If the search is a keyword search then this field returns the keywords (e.g.: "Harry Potter" for keywords "Harry Potter"). If the search is for keywords in a particular category then this field returns the keywords and the category name (e.g.: "Harry Potter in Movies"). If the search is for the root category, then the catname.none configuration variable is return (its default is "Posters").

navbar

The navigation bar (a.k.a.: navbar) for the current search. If a category search, then returns the chain of categories from the root category to the current category (e.g.: "Posters > Animals > Cats > Calico Cats"). Each category in the chain is linked to apws.pl so the user can go to that category.

Note: The navbar will not be displayed if:

pagebar

The page bar (a.k.a.: pagebar) that links to subsequent pages when there are more products than can fit on the page. See size parameter and size configuration variable. Example page bar:

pages: 1 | 2 | 3 | 4 | 5 | 6> | next»

Note: The pagebar will not be displayed if:

results

Displays the results with a navbar, sub-categories (if any), posters (if any), and a pagebar. This field is merely shorthand for:

{navbar}{kids}{items}{pagebar}


Template Field Modifiers

Certain field names can be followed by a modifier that modifies the field's output. For example, adding *, such as {name*}, causes HTML characters and other special characters to be removed so that the field's output can be used inside an HTML tag, such as <title>{name*}</title>

The following table describes the template fields that can be modified:

Field Modifier Description

name*

Similar to {name} except that HTML characters and other special characters are removed so that the field can be used inside an HTML tag, such as <title>{name*}</title>

name+

Similar to {name} except that HTML characters and other special characters are removed and spaces are converted to + so that the field can be used inside a URL, such as href="/search.php?q={name+}"


» 9. Virtual Directory

Important:   linux/unix servers only
Virtual Directory only works on linux/unix servers. It does not work on Windows servers.



What Is Virtual Directory

Virtual Directory makes it possible for apws.pl webpages to appear as if they are static HTML files rather than accessed via a cgi-bin perl program. Virtual Directory is implemented using "mod_rewrite". mod_rewrite is a standard feature of Apache webserver (running on linux/unix servers).

For example, a typical apws.pl URL that uses parameters is as follows:

DOMAIN.com/cgi-bin/apws/apws.pl?cat=19816

The following URL that uses Virtual Directory is equivalent to the above parameter-based URL:

DOMAIN.com/posters/subjects/animals/domestic-animals/cats/kittens/-/cat-19816/

This Virtual Directory URL does not contain anything that suggests that it is a perl program. Another possible advantage of using Virtual Directory is that some search engines consider each directory name as a keyword.

Each of the parameters (NAME=VALUE) has become a directory name (/NAME-VALUE/). And the Category Path for the selected category ("Subjects > Animals > Domestic Animals > Cats > Kittens", category 19816) has been included automatically as a directory path (subjects/animals/domestic-animals/cats/kittens/-/), known as the "named portion" of the virtual directory URL.

The URL looks like it is just referring to a directory that is within several sub-directories. To the "outside world" it appears that your webserver contains directories and sub-directories even though none of them actually exists; they are all virtual.


Configure Virtual Directory

To configure your webserver and apws.pl to use Virtual Directory, you have to do two steps:

  1. Modify the .htaccess file in the root directory of your website.
  2. Set the virtual.dir configuration variable.

There are two versions of these two steps depending upon whehter you want the virtual directory to be a sub-directory (e.g.: /posters/) or the root directory (i.e.: /).


Sub-Directory Virtual Directory (/posters/)

Step 1:

Add the following three lines to the .htaccess file in the root directory of your website. If the file already exists, you should add to it rather than overwriting it.

RewriteEngine  on
RewriteBase  /
RewriteRule  ^(posters)/.*$  /cgi-bin/apws/apws.pl?dir=$1  [L]

The part posters specifies what virtual directory the posters are to appear in (e.g.: DOMAIN.com/posters/). If you want posters to appear in a different virtual directory, change posters (e.g.: shop).

The part /cgi-bin/apws/apws.pl specifies the URL to apws.pl on your website. If you installed apws.pl at a different URL on your server, change this part to your apws.pl URL.

Step 2:

Edit the apws-ini.txt configuration file, and set the virtual.dir configuration variable to the same virtual directory that you specified in Step 1 above (e.g.: posters)

virtual.dir  "posters"

Note: For other configuration variables related to Virtual Directory, see the virtual.* configuration variables. Those variables are optional and can be left at their default values.

Now access DOMAIN.com/posters/ and you should see output from apws.pl


Root Directory Virtual Directory (/)

Step 1:

Add the following four lines to the .htaccess file in the root directory of your website. If the file already exists, you should add to it rather than overwriting it.

RewriteEngine  on
RewriteBase  /
RewriteCond  %{REQUEST_FILENAME}  !-f
RewriteRule  ^.*$  /cgi-bin/apws/apws.pl  [L]

The part /cgi-bin/apws/apws.pl specifies the URL to apws.pl on your website. If you installed apws.pl at a different URL on your server, change this part to your apws.pl URL.

Step 2:

Edit the apws-ini.txt configuration file, and set the virtual.dir configuration variable to /

virtual.dir  "/"

Note: For other configuration variables related to Virtual Directory, see the virtual.* configuration variables. Those variables are optional and can be left at their default values.

Now access DOMAIN.com and you should see output from apws.pl


» 10. Compatibility with allposters.pl


URL Compatibility

If you used our older allposters.pl script, it is possible to keep your old URL's working so that users (and search engines) do not get "404 File Not Found" errors at your old URL's.

An .htaccess file (mod_rewrite) can transparently redirect from the old URL's to the new apws.pl script. Note: This is forward compatibility only; apws.pl does not generate backwardly compatible URL's. The .htaccess file connects the old URL's to apws.pl.

Important:   fnformat in allposters.ini
This compatibility with allposters.pl assumes that the fnformat configuration variable in the allposters.ini configuration file was set to either "cn" or to "c". It will not work if you used "n". The default for fnformat is "cn". The fnformat configuration variable tells allposters.pl what filename format to use when creating HTML files.

Depending upon whether your posters are located at the root directory / or in a sub-directory such as /posters/, view one of the following sample .htaccess files:

Copy the statements (from one of the sample .htaccess files) to your .htaccess file located in your website's root directory (where your home page file is located). If you do not have a .htaccess file, create it in a plain text editor such as Windows Notepad and then upload it to your website's root directory.

Once you have modified the .htaccess file, old URL's will transparently redirect to apws.pl. For example, the old URL domain.com/animals/ (or domain.com/posters/animals/) will continue to show Animals posters (category 622). And the old URL domain.com/animals/c976-cats.html (or domain.com/posters/animals/c976-cats.html) will continue to show Cats posters (category 976). To the user (and search engine), the URL remains the same and only the content changes to the latest content.

There are two statements in the .htaccess file that you may need to change:

  1. Path to apws.pl:

    The sample .htaccess file assumes that apws.pl is located at /cgi-bin/apws/apws.pl

    RewriteRule ^apws-c([0-9]+)$ /cgi-bin/apws/apws.pl?cat=$1 [L]

    If your installation of apws.pl is at a different URL (e.g.: /cgi/apws/apws.cgi), then adjust the part shown in red in the above statement to use that URL. Do not change the "apws-c" part at the beginning of the statement.

  2. Posters Sub-Directory: (skip this section if your posters are in root directory /)

    The sample .htaccess file assumes that your posters are based at the sub-directory /posters/ so that you have directories such as /posters/animals/ and /posters/movies/ ---- If your posters are based at a different sub-directory (e.g.: /myposters/) so that you have directories such as /myposters/animals/ and /myposters/movies/ then you need to modify the .htaccess file. Edit the .htaccess file and search for ^posters/ and replace all occurrences of posters with your sub-directory. Note that there are nearly 80 occurrences that need to be replaced; all must be replaced. For example, replace:

    RewriteRule   ^posters/?$   /apws-c0

    with:

    RewriteRule   ^myposters/?$   /apws-c0


Template Compatibility

For compatibility with our older allposters.pl script, the following template fields are supported:

Field Description

allposters

Displays the results with sub-categories (if any), posters (if any), and a pagebar. This field is merely shorthand for:

{kids}{items}{pagebar}

allpostersHome

URL of AllPosters.com homepage (with AllPosters.com affiliate ID). For example:

<a href="{allpostersHome}">Click here for AllPosters.com</a>

allpostersSignup

URL of AllPosters.com homepage (with AllPosters.com affiliate ID). For example:

<a href="{allpostersSignup}">Click here for AllPosters.com</a>

allpostersMore

URL of current category at AllPosters.com (with AllPosters.com affiliate ID). If the current page is a keyword search without a category, then this URL is the URL of the AllPosters.com homepage (with AllPosters.com affiliate ID). For example:

<a href="{allpostersMore}">Click here for more posters</a>

amazon:MODE

Generates a <script> tag that calls Associate Engine for the specified amazon.com store sections. The keywords of the search are the keywords specified via the keywords parameter. If the keywords parameter is not specified, then the name of the category is used as the keywords. For example:

{amazon:books}

Note: Set your Amazon.com affiliate ID via the amazonID configuration variable.

amazonSSI:MODE

Similar to amazon:MODE except that a SSI Server-Side-Include statement (<!--#include virtual="..."-->) is generated rather than a <script> tag. For example:

{amazonSSI:books}

Note: Set your Amazon.com affiliate ID via the amazonID configuration variable.

amazonMore

URL of Amazon.com search (with amazon.com affiliate ID) for the current keywords. The keywords of the search are the keywords specified via the keywords parameter. If the keywords parameter is not specified, then the name of the category is used as the keywords. For example:

<a href="{amazonMore}">Click here to search amazon.com</a>

Note: Set your Amazon.com affiliate ID via the amazonID configuration variable.

amazonHome

URL of Amazon.com homepage (with amazon.com affiliate ID).

Note: Set your Amazon.com affiliate ID via the amazonID configuration variable.

keywords

Keywords formatted for use in a URL. Spaces are converted to + sign and unsuitable characters are removed. The keywords are the keywords specified via the keywords parameter. If the keywords parameter is not specified, then the name of the category is used as the keywords. For example:

<a href="http://www.google.com/search?q={keywords}">Search Google</a>

namePlain
name*

The name of the current page with all special characters and accents removed.

For compatibility with our older allposters.pl script, the following Amazon.com related configuration variables are supported:

Variable Default Description

amazonid

(none)

Your amazon.com associates ID.

amazonssi

no

Specifies if {amazon:MODE} should be processed as {amazonSSI:MODE}

amazonpl

(none)

URL of Associate Engine (amazon.pl / ae.pl) on your server.

amazonlist

(none)

RGB color to use for title background, e.g.: amazonlist "CC00FF"

amazongridlite

no

Adds lite parameter to ae.pl calls.


» 11. Inclusion in Existing Webpages

You can include results from apws.pl in your existing webpages through the use of:

The first thing you need to do is to figure out what search you want to perform and how you want it to be formatted. For example, to display Movies posters (AllPosters.com category 101) in a 3-column by 4-row grid, you would use the parameters: cat=101&grid=c:3,r:4

Once you know what search parameters and formatting parameters you want to use, it is a simple matter to create an the appropriate inclusion tag.


SSI (server-side-include) Tag

To include results in a webpage using a SSI (server-side-include) tag, add the ssi parameter to the list of parameters (you can add it anywhere in the URL). For example:

<!--#include virtual="/cgi-bin/apws/apws.pl?ssi&PARAMETERS"-->

Note: If you do not see search results in your webpage when you use the SSI tag, try typing the URL (including the ssi parameter) into your web browser. If you see a server error (e.g.: 404 File Not Found, or 500 Internal Server Error), fix the errors.

Note About SSI Virtual URL

If the URL specified in the virtual parameter refers to one of your local .txt files (e.g.: /inc/header.txt) then the file is read directly from your server's hard drive by the apws.pl script. This operation is efficient since the file read operation is done by the apws.pl script, bypassing the web server.

Otherwise, HTML from the specified URL is retrieved by accesing your web server (e.g.: /rss.php). Note: By including a domain in the URL, you can access any URL even if it is on another web server (e.g.: DOMAIN.com/rss.php). To optimize such accesses, you can add the cache attribute to the SSI tag; HTML will be written to the local cache and will be used on repeat requests to the same URL. The freshness of the cache is specified by cache.stale. For example:

<!--#include virtual="/cgi-bin/apws/apws.pl?ssi&PARAMETERS" cache-->

Note: The order of attributes is important, that is, virtual then cache.


<script> Tag

To include results in a webpage using a Javascript <script> tag, add the script parameter to the list of parameters (you can add it anywhere in the URL). For example:

<script src="/cgi-bin/apws/apws.pl?script&PARAMETERS"
TYPE="text/jscript"></script>

Note: If you do not see search results in your webpage when you use the <script> tag, try typing the URL (including the script parameter) into your web browser. If you see a server error (e.g.: 404 File Not Found, or 500 Internal Server Error), fix the errors.


PHP virtual() Function (linux web server)

To include results in a webpage using a PHP virtual() function call, add the php parameter to the list of parameters (you can add it anywhere in the URL). For example:

virtual("/cgi-bin/apws/apws.pl?php&PARAMETERS");

Note: If you do not see search results in your webpage when you use the virtual() function, try typing the URL (including the php parameter) into your web browser. If you see a server error (e.g.: 404 File Not Found, or 500 Internal Server Error), fix the errors.

Note: The URL used in the virtual() function call must be a relative URL. Do not include a domain name. It must start with a / character.


PHP file_get_contents() Function (Windows web server)

To include results in a webpage using a PHP file_get_contents() function, add the php parameter to the list of parameters (you can add it anywhere in the URL).

print file_get_contents("http://www.mydomain.com/cgi-bin/apws/apws.pl?php&PARAMETERS");

Note: If you do not see search results in your webpage when you use the file_get_contents() function, try typing the URL (including the php parameter) into your web browser. If you see a server error (e.g.: 404 File Not Found, or 500 Internal Server Error), fix the errors.

Note: The URL used in the file_get_contents() function must be a full URL. It must start with http:// and a domain name.


Integration with Associate Engine

Output from the apws.pl script can be integrated into the product details pages output from the Associate Engine (AE) script. To do this integration, add an SSI (server-side-include) statement to your AE details template file.

Edit your details template (e.g.: details6.html) and add one of the following suggested SSI statements where you want the apws.pl output to be included:

If your website is Music related: (search by music artist)

{if details.artists}
<!--#include virtual="/cgi-bin/apws/apws.pl?ssi&cat=122&keywords={details.artists+}" -->
{endif}

The cat=122 limits the search to the AllPosters.com Music category #122.

If your website is Movies related: (search by director)

{if details.directors}
<!--#include virtual="/cgi-bin/apws/apws.pl?ssi&cat=101&keywords={details.directors+}" -->
{endif}

The cat=101 limits the search to the AllPosters.com Movies category #101.

If your website is Movies related: (search by actor)

{if details.actors}
<!--#include virtual="/cgi-bin/apws/apws.pl?ssi&cat=101&keywords={details.actors+}" -->
{endif}

The cat=101 limits the search to the AllPosters.com Movies category #101.


» 12. Custom Styles

See: Borders & Styles for information about using styles.

This section provides information on how to customize styles or create your own styles.

For example, to add the artist's name to the APWS format of style 1, create a plain text file (by running Windows Notepad editor or similar plain text editor) and name the file apws-ini.txt and copy the following lines into it. If you already have an apws-ini.txt file, then copy the following lines into it (can go anywhere in the file, such as at the very end).

format.item.8 {
     {img}
     <b>{title}</b>
     {?artist}<br>{artist}{/artist}
     <br>{type}
     <br>{size}
     {?price}<br>{price}{/price}
     <br>{unframed}
     {?framedmounted}<br>{framedmounted}{/framedmounted}
     {?pack}<br><br>{/pack}
}

Note: The } on the last line by itself. It closes the multi-line definition and is required.

Upload the new/revised apws-ini.txt file to the same directory where apws.pl is located (e.g.: cgi-bin/apws/apws-ini.txt). Then you will be able to access that style as style 8 (e.g.: /cgi-bin/apws/apws.pl?style=8&... ).

The above lines are the same as style 1 except for the additional line:
{?artist}<br>{artist}{/artist}

You can move that line around if you want the artist's name to appear elsewhere. Or you can change the formatting such as making it bold ( e.g: {?artist}<br><b>{artist}</b>{/artist} ) or changing its color to red ( e.g.: {?artist}<br><font color="red">{artist}</font>{/artist} ).

The {?artist} is a conditional statement that says, "If there is a value in the artist's field then output everything from here until the closing marker {/artist}". Without the conditional, if there was no artist (sometimes happens on some items) then the <br> would cause a blank line to appear. The conditional eliminates the blank line in that case.

To see the formatting codes for the built-in styles 1 through 7, click here. If you want, you can create your own format.item.8 (or whatever number you want to use) based on these and then add the line {?artist}<br>{artist}{/artist} to show the artist's name wherever you want.


» (To be added)





E.&O.E.; © Cusimano.Com Corporation; www.c3scripts.com