allposters.pl Script : Documentation  
Home > allposters.pl > Documentation

Note: This documentation is DRAFT and is incomplete in places.

Configuration

allposters.pl and its associated files comes as a 6MB Windows .zip file (or .tar.gz file). To unpack the .zip file, use WinZip or CuteZip or equivalent software. The .zip file contains:

File Description
allposters.pl allposters.pl Perl script
allposters.ini configuration file
allposters-2.ini auxiliary configuration file
allposters/allposters-1.dat data file
allposters/allposters-2.dat data file
allposters/allposters-3.dat data file
allposters/allposters-4.dat data file
allposters-template/*.html template files
allposters-include/*.html include files

The first thing you must do is configure allposters.pl. Using a text editor, such as Windows Notepad, edit the allposters.ini file. Near the top of the file, there is a section identified as "Settings you must change". Change those settings that apply to you.

The default settings will cause your poster store to be created with all 100,000+ posters; such a poster store requires at least 85MB of disk space when the default templates are used. If you want to include only one or just a few of AllPosters.com's poster categories (e.g.: Movies, Music, etc.), you will need to edit the "categories" line so that the script knows what categories you want included. For details on how to do this, see the "Selecting Poster Categories" section.

Installation

Once you have edited your allposters.ini file, you will need to upload allposters.pl and associated files to your web server.

  1. Using your FTP program, upload allposters.pl and allposters.ini into your cgi-bin directory. You must use ASCII transfer mode when uploading these two files. If you are using the FTP program WS_FTP, click the "ASCII" button at the bottom of the screen. If you are using the FTP program CuteFTP, select ASCII from the "Transfer > Transfer Type" menu.

How to run

For instructions on how to turn allposters.pl, see: allposters-readme.txt

Configuration

Note: Your AllPosters.com ID is set in your allposters-key.txt file. It is not set in the allposters.ini configuration file. If you do not already have your allposters-key.txt file, request your allposters-key.txt file by going to: http://www.c3scripts.com/allposters/key

Command Default Description
amazonID ID   Sets your Amazon.com affiliate ID to ID. For example, "amazonID bimecom1-20" sets the amazon.com affiliate ID to "bimecom1-20".
amazonpl PATH /cgi-bin/ae.pl Specified the URL to use to access the Associate Engine ae.pl script (sold separately) to PATH. This path value is used by the amazon template directive, and it can be either a partial URL (in which case the user's web browser automatically attaches the domain name of your web server) or it can be a full URL (e.g.: "http://www.mydomain.com/cgi-bin/ae.pl").
catdir N:PATH (none) Specifies the directory names to use for poster categories and poster subcategories. Category N and its descendent cateogires will be stored in the directory called PATH. All directory names are relative to the directory specified by the rootdir configuration command. For example, "catdir 101:movies" causes all posters in category #122 (e.g.: Movie posters) and all its descendent categories (e.g.: Action / Adventure Movie posters) to be written to the directory called "movies". The special value of 0 for N represents a catch-all in case no catdir commands match the current category.
categories ID,ID,... 0 Specifies the poster categories to build. To build all categories, use "categories 0". To build one or more categories and their subcategories, if any, specify poster category numbers separated with commas. For example, "categories 101" builds only the Movies category, "categories 101,122" builds both the Movies and Music categories.
catfavicon N 1 Specifies whether to make symbolic links to /favicon.ico in each poster subdirectory of not. The possible values of N are: 1=make symbolic links; 0=don't make symbolic links. In the Microsoft Internet Explorer web browser, if a user select "Add to Favorites...", the web browser automatically tries to download an icon file called "favicon.ico" from the directory where the currently displayed webpage is located and then uses that icon graphic in the user's Favorites menu beside the menu entry for your webpage. Thus if you have several poster directories, all you have to do is create one favicon.ico file in your root directory and the identical icon file automatically is accessible in all poster subdirectories. FYI: a symbolic link is equivalent to a "shortcut" in Windows.
catkeywords N:WORDS (none) Specifies additional keywords WORDS to be added to the standard keywords of the poster category N (i.e.: the name of category N) and its descendent poster categories. These additional keywords are useful to add because sometimes the category name is not specific enough (e.g.: "12211086:music" adds the keyword "music" to the subcategory called "Metal" which is located in the "Music" category; thus the full keywords become "metal music"). The full keywords of the current category are in the {keywords} template variable. For example, "catkeywords 290:sports" adds the keyword "sports" to category 290 (e.g.: Sports category) and its descendent poster categories (e.g.: Baseball, category #290298).
catmkdir N 1 Specifies whether to create poster subdirectories or not. The possible values of N are: 1=make directories; 0=don't make directories. See the catdir configuration command to see how to set the name of directories.
catremote N (none) Specifies that a file for category N and its descendent categories should not be created yet still include an entry for category N in its parent category file. For example, "catremote 1011981" (i.e.: Action / Adventure posters) causes a file for category 101981 to not be created; and, in it's parent category file (i.e.: Movies, #101), an entry for "Action / Adventure" will be included and it will link to that category at the AllPosters.com website.
catskip N (none) Specifies that category N and its descendant poster categories should be completely skipped. A category file will not be created and an entry for the category will not be included in it's parent category file. For example, "catskip 1017664" causes the Film-Noir movie poster category and all its descendent poster categories to be skipped.
clickbankID ID cuscom Sets your ClickBank.com affiliate ID to ID. For example, "clickbankID cuscom" sets the ClickBank.com affiliate ID to "cuscom".
datadir PATH allposters Specifies the disk path to where data files are located to PATH. The path can be relative (e.g.: "allposters") or absolute (e.g.: "/home/user10/cgi-bin/allposters"). Relative paths are relative to the directory where the script is located. If you followed the standard installation instructions, the data files will be located in a directory called "allposters" in the same directory where this script is located.
emerchandiseID ID   Sets your eMerchandise.com affiliate ID to ID. For example, "emerchandiseID A7278" sets the eMerchandise.com affiliate ID to "A7278".
formnewwindow N 1 Specifies whether forms should be adjusted so they open a new web browser window when the user clicks on them or not. The possible values of N are: 1=adjust forms so they open new window; 0=don't adjust forms. Only those forms whose ACTION attribute starts with "http://" or "https://" are adjusted.
htmlext EXT html Specifies the filename extension to attach to the end of filenames to EXT. This extension applies to: category files, templates files, and include files. For example, "htmlext html" sets the filename extension to ".html". The "." period is optional. The value you use will depend upon the web server configuration and what filename extension you prefer; most web servers use ".html" while some web servers are configured to only use ".htm". If you want the script to create PHP3 files, you would use "htmlext php3".
indexfile FILE index.html Specifies the name of your index files to FILE. For example, "indexifle index.html" sets the name of your index files to "index.html". The name that you should use will depend upon the configuration of your web server; "index.html" is supported by most web servers. FYI: When a user types in a URL that refers to a directory on your web server (e.g.: http://www.mydomain.com/myposters"), the web server displays the index file located in that directory (e.g. "posters/index.html").
longfn N 1 Specifies whether to use long filenames or short filenames. 1=use long filenames; 0=use short filenames. Long filenames are in the format "cNUMBER-NAME" and short filenames are in the format "cNUMBER". NUMBER is the current category number and NAME is the name of the current category.
navbarColor COLOR red Navigation bar "You are here" color. COLOR can be either a standard color name (e.g.: red, green, blue, gray, ...) or in hexadecimal format (e.g.: 000000, ..., FFFFFF). Do not include the "#" symbol before the hexadecimal value.
navbarHome N 0 Specifies whether the {navbar} variable should contain a "Home" link or not. 0=do not include link; 1=include link. The URL of the Home link is set via the rooturl configuration command.
newwindow N 1 Specifies whether links should be adjusted so they open a new web browser window when the user clicks on them or not. 1=adjust all links so they open new window; 0=don't adjust links. Only those links whose HREF attribute starts with "http://" or "https://" are adjusted.
postersacross N 4 Set number of posters across the page to N. For example, "postersacross 3" causes pages to have 3 columns of posters per page.
postersdown N 5 Set maximum number of posters down the page to N. For example, "postersdown 5" causes pages to have at most 5 rows of posters per page.
rooturl PATH / Sets the URL of root where written files are located to PATH. For example, if you want your posters at "http://www.mydomain.com/" then use "rooturl /". If you want your posters at "http://www.mydomain.com/myposters/" then use "rooturl myposters". The leading and trailing "/" are optional.
rootdir PATH .. Specifies the disk path to where files are to be written to PATH. The path can be relative (e.g.: "../myposters") or absolute (e.g.: "/home/user10/HTML_files/myposters"). Relative paths are relative to the directory where the script is located. Typically, the script is located in your cgi-bin directory which is in your website's root directory; thus ".." steps back out of your cgi-bin directory to your root directory.
templatedir PATH allposters Specifies the disk path to where templates and include files are located to PATH. The path can be relative (e.g.: "allposters") or absolute (e.g.: "/home/user10/cgi-bin/allposters"). Relative paths are relative to the directory where the script is located. If you followed the standard installation instructions, your template and include files will be located in a directory called "allposters" in the same directory where this script is located.
writeroot N 1 Specifies whether to allow overwriting of the index file in the root directory. 1=allow overwriting; 0=don't allow overwriting. If the file is overwritten, the original file is renamed to "index.NUMBER" where NUMBER starts at 1 and increases sequentially for subsequent builds.

Category Templates

Variables

Variable Description
allposters Grid of posters and art prints from AllPosters.com for the current poster category. See the postersAcross and postersDown configuration commands to set the size of the grid.
allpostersHome

URL for the AllPosters.com home page (includes your AllPosters.com affiliate ID).

For example, to link to the AllPosters.com home page:
<A HREF="{allposterHome}">Click here for AllPosters.com</A>

allpostersID Your allposters.com affiliate ID. Set this value using the allpostersID configuration command.
allpostersMore

URL at AllPosters.com to show more posters of the current category (includes your AllPosters.com affiliate ID).

For example, for more posters in this poster category:
<A HREF="{allpostersMore}">Click here for more {name} posters</A>

amazonHome

URL for the amazon.com home page (includes your amazon.com affiliate ID).

For example, to link to the amazon.com home page:
<A HREF="{amazonHome}">Click here for amazon.com</A>

amazonID Your amazon.com affiliate ID. Set this value using the amazonID configuration command.
amazonMore:MODE

URL at amazon.com to do a keyword search for the current poster category name (includes your amazon.com affiliate ID). The MODE parameter specifies which amazon.com product category to search. The possible values of MODE are:

MODE amazon.com product category
blended Blended search of all product categories
books Books
music Popular music
classical Classical music
dvd DVD's
vhs Videos
theatrical In Theaters
toys Toys
baby Baby
pc-hardware Computer Hardware
videogames Computer & Video Games
electronics Electronics
photo Photography
software Software
tools Tools & Hardware
garden Garden / Outdoor Living
kitchen Kitchen
wireless-phones Cell Phones & Service

For example, to search for related videos:
<A HREF="{amazonMore:vhs}">Click here for {name} videos</A>

catupdateNum The "catupdate" number used at AllPosters.com to specify which sidebar menu to show. Use this variable with the searchNum variable in a link to show all posters of this category. Note: You probably don't need to use this variable -- a more practical variable to use is the allpostersMore variable (see above).
emerchandiseHome

URL for the eMerchandise.com home page (includes your emerchandise.com affiliate ID).

For example, to link to the eMerchandise.com home page:
<A HREF="{emerchandiseHome}">Click here for emarchandise.com</A>

emerchandiseID The value of the eMerchandiseid variable. Set this value using the emerchandiseID configuration command.
emerchandiseMore

URL at eMerchandise.com to show memorabilia products related to this category's name (includes your eMerchandise.com affiliate ID).

For example, to search for related memorabilia at eMerchandise.com:
<A HREF="{emerchandiseMore}">Click here for {name} memorabilia</A>

keywords

The name of the current category plus any category keywords specified for this category or its ancestors using the catkeywords configuration command. Accents and encoding of special characters are removed so this variables is suitable for inclusion in your URL's.

For example:
<A HREF="http://www.google.com/search?q={keywords}">Search Google.com for {name}</A>

name

The name of the category. Any special characters are HTML encoded. For example: for category "Laurel & Hardy", this variable is "Laurel &amp; Hardy"; and for category "Décor", this variable is "D&eacute;cor".

For example, use the category in your page:
<TITLE>{name} posters and art prints</TITLE>
<H1>{name} Posters and Art Prints</H1>

namePlain
name*

The name of the category with accents and encoding of special characters removed. For example: for category "Laurel & Hardy", this variable is "Laurel & Hardy"; and for category "Décor", this variable is "Decor". This makes the name suitable for including in an <INPUT> field of a form or in a URL.

For example:
<INPUT NAME="k" TYPE=TEXT VALUE="{namePlain}>

For example:
<INPUT NAME="k" TYPE=TEXT VALUE="{name*}>

name+

The name of the category with accents and encoding of special characters removed and spaces replaced by + signs. For example: for category "Harrison Ford", this variable is "Harrison+Ford". This makes the name suitable for including in a URL.

For example:
<A HREF="/cgi-bin/ae.pl?type=search&mode=blended&keyword={name+}">Search {name} at amazon.com</A>

navbar

Navigation bar for this category showing this category's name and linked names of its ancestors. For example, for the category "Tom Cruise" (#768), the navbar is "Movies > Actors > Tom Cruise" with "Movies" and "Actors" as links to that category's page, respectively. Set the color of the category name using the navbarcolor configuration command. Note: If you want a "Home" link in {navbar}, you must set use the navbarHome configuration command or include the link yourself in your HTML just before {navbar}.

For example, navbar usage (without navbarHome command):
<P><A HREF="/">Home</A> &gt; {navbar}</P>
Home > Movies > Actors > Tom Cruise

For example, navbar usage (with navbarHome command):
<P>{navbar}</P>
Home > Movies > Actors > Tom Cruise

parent

The name of the parent category with special characters encoded.

For example, as a header:
<P>Here are {name} posters (part of {parent}):</P>

searchNum The "search" number used at AllPosters.com to show all posters in this poster category. Use this variable with the catupdateNum variable in a link to show all posters of this category. Note: You probably don't need to use this variable -- a more practical variable to use is the allpostersMore variable (see above).

Directives

Directive Description
amazon:... This directive is used with our Associate Engine ae.pl script (sold separately) to dynamically include related amazon.com products in your webpage. Parameters of the directive (e.g.: "amazon:books") tell ae.pl what products to include.
include

Include the include file for the current category or one of its ancestor categories. Include files are found in the templates directory. For example: assuming that the current category is #122 and that htmlext=html, then <!--include--> looks for the include file i122.html in your templates directory. If this file is not found, then the ancestor category is tried. This repeats until a file is found or the top level category is reached. If nothing is found, then the default include file (idefault.html) is used, if present.

So, if you want to include something on the Movies category (#101) and all of its subcategories, then you would create the file allposters-include/i101.html If you want to include something different on a particular subcategory page, for example on the Harrison Ford page (category #828: Movies > Actors > Harrison Ford), then you would create allposters-include/i828.html

include:FILE Include the specified FILE found in the include directory. Do not specify a filename ending, that is, leave off the ".html" (or whatever). The ending specified by the htmlext configuration variable is automatically appended to FILE. For example: assuming that htmlext=html and includedir=allposters-include, then <!--include:header--> would include the file allposters-include/header.html
noinherit Turns off inheritance of this template file to its descendant categories. Normally, a category inherits its ancestor's template if the category itself has no template, e.g.: Actors category will use the Movies template (since Actors is a descenant category of Movies) if there is no template for Actors.
nopack Just before each HTML file is written to disk, extraneous spaces and quotation marks are removed from the HTML so the file is as small as possible thus reducing the amount of data that your server must send out. In the rare case that this pack function is introducing errors into Javascript that you may have in your templates, use this directive to turn off the pack function.




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