phpLinkBid Manual v1.4

This document contains instructions and information on phpLinkBid Admin, and is the official manual for phpLinkBid v1.4.

  1. Installing phpLinkBid
  2. Updating phpLinkBid
  3. Configuring Your Site
    1. Site configuration
    2. Directory configuration
  4. Managing Your Site
    1. Managing site content
    2. Editing system messages
    3. Managing user accounts
    4. Managing emails
    5. Managing the linkroll
  5. Managing Your Directory
    1. Managing links
    2. Managing bids
    3. Managing categories
    4. Managing currencies
  6. Customizing Your Site
    1. Customizing styles
    2. Installing templates
    3. Customizing templates
    4. Template variables list
    5. phpLinkBid Themes
    6. phpLinkBid Themes Structure
    7. Customizing Your Language
  7. Troubleshooting

Installing phpLinkBid

Installing phpLinkBid requires a PHP 4.x enabled server and MySQL. Basic knowledge of FTP and an FTP client will be needed to upload the software to your server.

If you are upgrading to a new version of phpLinkBid, you should follow the steps in Updating phpLinkBid.

Once you have successfully purchased phpLinkBid, you will receive an email containing download instructions. Follow those instructions to download the latest version of phpLinkBid to your computer in .ZIP format. Unzip the file on your desktop or somewhere easy to remember. You should now have a folder named phpLinkBid-1.x.zip (where `1.x` is the version number).

Using your favorite FTP client, upload the contents of the new folder to your Web server. Make sure you upload all files to the folder you want the site to run on. Usually this will be `public_html` or `htdocs`, but you can also upload the files to a subfolder or subdomain on your site.

Once all of your files have been uploaded, you must run the install script to complete installation. Load up your favorite browser and head to:

http://www.yourdomain.com/install/

Make sure you replace `www.yourdomain.com` with the URL where you have uploaded phpLinkBid.

The installer will guide you through the rest of the process. Make sure you delete the `install` folder when complete.

Updating phpLinkBid

IMPORTANT: You should always backup your files and databases before updating!

`phplb-1.x.zip` contains the files needed for a full installation or an upgrade from any version of phpLinkBid. If you are running a heavily modified version of phpLinkBid or have custom templates you may wish to download the changed files only. `phplb-1.x_changed-files.zip` contains the changed files only for v1.0, v1.2 and beta releases.

Upgrading phpLinkBid is easy and similar to the installation process. Use your unique download URL to download phpLinkBid to your computer in .ZIP format. Unzip the file on your desktop or somewhere easy to remember. You should now have a folder named phplb-1.x (where `1.x` is the version number).

Using your favorite FTP client, you can now upload the contents of the folder to your Web server where you have installed phpLinkBid. If you are upgrading and using the full download, upload all files in the `phplb-1.x` folder. If you are using changed files only to upgrade, upload the files from the appropriate folder for your existing version: 1.0_to_1.4, 1.2_to_1.4, etc.

Make sure you upload all files, and make sure that you overwrite any existing files.

Once all of your files have been uploaded, you must run the install script to complete the update. During an upgrade, any existing database records, such as configuration options, links and site bids, will not be removed or modified, but the install script will modify your database, so make sure you backup. Load up your favorite browser and head to:

http://www.yourdomain.com/install/

Make sure you replace `www.yourdomain.com` with the URL where you have uploaded phpLinkBid.

The installer will guide you through the rest of the process. Make sure you delete the `install` folder when complete.

^ Back to top

Configuring Your Site

The installer will get all of the basic information needed to get your site running, so you can test it out immediately. To configure the details of your site, log in to phpLinkBid Admin with the username and password you created during installation by visiting:

http://www.yourdomain.com/admin/

phpLinkBid Admin is divided into two main categories: Site Admin and Auction Admin. You can configure site settings in Site Configuration, and manage auction settings in Auction Configuration. You can configure several important settings from each section.

Site Configuration

Site Configuration lets you change site specific settings like your URL, site title and admin email.

Payment Configuration
URL The full URL to your phpLinkBid site, e.g. `http://www.example.com/`. The URL should always contain a trailing slash (eg. http://www.example.com/)
Site Name The name of your phpLinkBid site, no extra text. E.g. `phpLinkBid Directory`
Site Title The full title and text of your site for the home page title. E.g. `The phpLinkBid Link Directory`
Admin Email Address The administrator email address and recipient of all bid, contact and site notifications.
META Keywords The META keywords to use in the <HEAD></HEAD> tags of your site. Comma-delimited, e.g. `directory, links, bid for position`
META Description The META description to use in the <HEAD></HEAD> tags of your site.
Active Template The currently active template stored in the /tpl/ folder.
Active Language The currently active language file to use for all public text.
Default List/Nav Separator The default separator character(s) for page titles and navigation.
Site Page URL Format URL format for site pages. Available fields: %pg_safename%
Page Title Format Page title format for site pages. Available fields: %site_name%, %pg_name%, %pg_title%
Emails per Queue Run The max. # of email messages to deliver from the queue per job queue run.
Autorun Jobs Queue Trigger the queue run with normal site traffic every X minutes. Set to 0 if the queue is configured via cron. You must set this or configure via cron for outbid notifications and link expirations to function!

Directory Configuration

Directory Configuration allows you to change many settings that control how your site works, and is divided into six sections: Payment Configuration, Links Configuration, Deep Links Configuration, Category Configuration, URL Format Configuration and Title Format Configuration.

Payment Configuration
PayPal Email Address This should be set to the PayPal account that bids will be placed to. Make sure this is set to your valid PayPal email account and can accept payments.
Active Currency The active currency for all bids. This should be the same as your primary currency in PayPal.
Minimum Bid The minimum bid to add a new link to the directory.
Minimum Bid-Up The minimum bid for an existing link in the directory.
Use Whole-Dollar Bid Amounts Allow only whole dollar bids and hide decimal places.
Links Configuration
# of Links in Top List This setting lets you specify how many links you want displayed on the homepage. Set to any number higher than zero (no decimals here, folks).
# of Links Per Page Select how many links you want displayed per page in the directory. Set to any number higher than zero.
Link Title Max Length Sets the maximum allowed length for link titles.
Link Description Max Length Sets the maximum allowed length for each line of link descriptions.
Link Summary Cutoff Length How many characters to display from link descriptions in listings.
Link Leader Link leader is the highest bidding link in the directory. Change to display or hide the link leader's sitewide link.
Extended Link Info Shows/hides the extended link traffic and promotional info in link details.
Use `nofollow` for links Lets you choose to add rel="nofollow attribute to links on the listing and link details pages.
Require Link Approval Set all new links to Inactive and require admin approval to activate.
Link Approval Email Send an approval notification email when links are approved.
Link Expiration Links are set to Disabled after X days without a new bid. Set to 0 for permanent links.
Link Expiration Reminder Send reminder email X days before expiration. Set to 0 for no reminder.
Enable Outbid Notifications Send notification email when a link changes position in listings for a category, letter or in the Top List.
Deep Links Configuration
Use Deep Links Offer up to 5 links to sub-pages on the same domain as a link.
Minimum Bid for Deep Links Minimum bid required to enable deep links for a link.
Deep Links Subdomains Allow deep links to subdomains of the link URL as well as sub-pages.
Category Configuration
Category Mode This option enables or disables Category Mode. Default is Letters Mode, which lists all links alphabetically. Category Mode must be enabled to use categories on your site and allow new links buyers to select a category. All existing links can be categorized via Manage Links in Directory Admin.
# of Columns Specifies how many columns to use for each row of the category list on your site.
# of Subcategories The max. # of subcategories to display in the Category List.
Show Count in Category Lists Show the # of categories or the # of links in Category List.
Use Category Drill-Down Show the current category as the top level category in the Category List. Disable to display top level Category List at all times.
URL Format Configuration
Link URL Format URL format for links. For advanced users only. Available fields: %link_id%, %link_title%, %link_url%, %category_id%, %cat_tag%, %cat_tags%.
Category URL Format Lets you define your own format for category URLs. For advanced users only. Available custom variable for this field includes %cat_tag%.
Letters URL Format URL format for letter listings. Available field: %letter%
Page # URL Format Lets you define your own format for page numbers in URLs. For advanced users only. Available custom variable for this field includes %page_num%.
Title Format Configuration
Link Title Format Page title format for links. Available fields: %site_name%, %link_title%, %link_url%
Category Title Format Page title format for categories. Available fields: %site_name%, %cat_name%
Letters Title Format Page title format for letter listings. Available fields: %site_name%, %letter%

^ Back to top

Managing Your Site

Managing site content

phpLinkBid has a built-in Content Management System for editing existing pages and creating new content. You can access the CMS under Site Pages in the Site Admin menu. From Site Pages you can edit existing pages or create a new page by clicking Create Page.

The following fields are available for site pages:

Page Name The name used in the main menu, usually a nice short nice such as "About".
Page Title The full name of the page used for the title, for example "About Our Website".
Safe Name The URL-safe name for a page, containing no special characters or spaces. For example, "about".
Page Contents The contents of the page. Can contain HTML, CSS or JavaScript code.
Sort Order Sort Order is the position of the page in the main menu, for example 1 for first position.
Display page in menu? Lets you display or hide the page in the main menu. Page can still be viewed when hidden by entering the URL.

Editing system messages

System messages contains automatic email templates that are used for bid and link notifications. You can edit these messages to customize them to your auction.

Message Title The title of the message, used for the email subject or notification title.
Message Text The contents of the message. Do not use HTML. Message text should be plaintext and email-safe.

Dynamic fields are available by surrounding the field name with `[[` and `]]`. For example, typing [[site_name]] in the message title or content field will display the site name in the final message output.

All of the fields in the template variables list are available. Bid messages also have access to bid_amount, bid_url and link_url.

Managing user accounts

You can access User Accounts from the Site Admin menu. You can create additional user accounts, and they will have full administration priveleges. Additional accounts should not be created unless required, such as needing several site editors to review and handle bids.

You can change your administrator account information here, including email address, password and name.

Managing Emails

The Email Manager provides an easy way to send emails to your link owners. You can create a custom subject or message for your email, or select an email template from the "Email Templates" dropdown. Email Templates are built-in messages such as link expiration notices, new link submit messages, etc. When sending emails, you can send an email to each unique email address or to all link owners. When sending a built-in message with link details, make sure you send to all link owners so each recipient receives the appropriate link information in their email.

Managing the Linkroll

You can access the Linkroll Manager from the Site Admin menu. The Linkroll Manager lets you manage a list of links that can be displayed virtually anywhere on your Web site. By default, links in your linkroll appear in a "Recommended Sites" column on every page.

From the Linkroll Manager, you can create, edit and delete links. Each link requires a title and URL. Titles can be formatted with the [a]...[/a] tags to anchor only part of the title with the URL. Descriptions are optional, and you can optionally set the nofollow attribute and open the link in the same or a new window. Links are sorted using the "Link Order" field, in numerically ascending order.

^ Back to top

Managing Your Auction

Managing links

Administrators can access link management via Manage Links on the Auction Admin menu. New links can be created by clicking Create Link, and details of existing links can be changed with the Edit button for the corresponding link. Links can be deleted with the corresponding Delete button. Once deleted, a link is permanently removed from the system!

Links are not activated in the directory until a bid has been placed.

Managing bids

Administrators can access bid management via Manage Bids on the Auction Admin menu. New bids can be created by clicking Create Bid, and details of existing bids can be changed with the Edit button for the corresponding bid. Bids can be deleted with the corresponding Delete button. Once deleted, a bid is permanently removed from the system!

When creating or editing a bid, the link the bid applies to is defined with the selection box labelled Link. Make sure the correct link has been selected here for the bid.

Links require at least one bid to be displayed in the auction directory, so if you are creating a new link as an administrator remember to add a bid here. If you have disabled IPN you must create all paid bids here manually.

Managing categories

Administrators can access category management via Manage Categories on the Auction Admin menu. New categories can be created by clicking Create Category, and existing categories can be edited or deleted with the Edit and Delete buttons.

Category Title is the title of the category displayed on the page when viewing a category from your site. Category Name is the name used in menus for the category, and Category Tag is the ID used in the URL for the category. The Category Tag should usually consist of numbers, letters, underscores and dashes only. Category Status can be set to Active (show the category) and Inactive (hide the category).

Managing Currencies

You can access Manage Currencies from the Directory Admin menu. The currency manager lets you edit, create and delete available currencies for your directory. Your active currency should be set under Directory Admin > Directory Configuration > Payment Configuration > Active Currency.

phpLinkBid comes with 16 predefined currencies, which include all major currencies supported by PayPal. These currency codes are used for PayPal transactions, so creating and experimenting with new currencies may affect your PayPal transactions.

Each currency has 7 required fields: Name, 3-Letter Currency Code (corresponding to ISO 3166-2, Currency Symbol, Decimal Separator, Group Separator, Decimal Places and Currency Symbol Position.

^ Back to top

Customizing Your Site

phpLinkBid uses a custom template system that separates the HTML and CSS of your site from the PHP code. Templates are basically collections of HTML files with the .tpl extension, stylesheet files and image files.

Templates reside in the tpl/ folder in your script installation directory. Files for each template are stored in their own folder, and the folder name is used as the template name and identifier in phpLinkBid. The active template can be set in Site Configuration, and the default template is phpl.

Customizing styles

The easiest way to start customizing phpLinkBid is to edit the style.css file residing in your template folder. The default location of this file is SCRIPT_PATH/tpl/phplb/style.css, where SCRIPT_PATH is the path to your installation of phpLinkBid.

style.css is divided into several main sections for layout styles, menu styles, link styles and form styles.

Installing templates

If you have downloaded a new template and unzipped it on your computer, you should have a folder containing all of the template files with the name templatename (replace with whatever the template happens to be named).

To install the template, upload the folder and it's contents to SCRIPT_PATH/tpl/, where SCRIPT_PATH is the path to your installation of phpLinkBid. Now go to Site Configuration and you can select the new template from the selection box here and click Save to use it immediately.

Customizing templates

You may wish to customize some things that cannot be controlled with the CSS file, which means editing the template files. You can edit individual template files and save to see changes immediately.

It is recommended to make a copy of the default template folder phplb and work on the new template, so you can always revert back to the old template or refer to the old template files. Make a copy of the phplb folder and name it something short and easy to read - no spaces or special characters. For example, starburst or redwine2. You can then go to Site Configuration and select the new template name from the selection box to use it immediately.

You can now edit any template file, image or stylesheet you choose. Do not change the names of any template files or you risk breaking your site. The file structure of a template must remain intact, and is as follows.

/images/ Folder containing images for the template.
bid.tpl Bid confirmation screen - the final confirmation before payment.
error404.tpl The default error message displayed when a visitor requests a page that doesn't exist.
footer.tpl The overall site footer template.
functions.js JavaScript file containing a few JS functions.
header.tpl The overall site header template.
link.tpl This is the link details template used for individual links in the auction.
link_preview.tpl Link preview template - currently unused
style.css The main stylesheet for the template.

Templates use template variables to access common settings and variables from phpLinkBid. Template variables are identified in a template file with surrounding curly brackets. For example, adding { site_title } to a template will display the title of your site as set in Site Configuration. See the template variables list below for all available global template variables.

Template variables list

The following table lists some of the variables available in every template.

Site variables
dir_base Relative path of your site, usually `/`
dir_tpl Relative path to the current template folder
dir_tpl_images Relative path to the current template images folder
Configuration variables
site_title Full title of your site
site_name Name of your site
meta_keywords Site keywords
meta_description Site description
meta_keywords Site keywords
site_url Site URL
site_email Site administrator email address
Auction variables
paypal_email PayPal email address
top_count The number of sites set for Top Sites
link_desc_max Maximum link description length
link_title_max Maximum link title length

phpLinkBid Themes

As of version 1.4 you will see the term "phpLinkBid themes" being used in addition to "phpLinkBid templates". They are mostly interchangeable in common usage, but a phpLinkBid theme is more accurately described as a packaged set of phpLinkBid template files. A phpLinkBid theme uses a common file & folder structure and may optionally include files from the theme author such as instructions, .PSD files, etc. See the next section for details on the phpLinkBid Theme structure.

phpLinkBid Theme Structure

A phpLinkBid Theme should be packaged as a .ZIP file containing your template folder and any additional files or media. Your phpLinkBid template should reside in a folder with a short and descriptive name containing no spaces or special characters. For example, if you named your theme "Fluid 2.0" you might name your folder "fluid" or "fluid2". If it isn't obvious which folder is the template folder to be uploaded, or you have additional information or credits for your theme, create a small readme.txt file and include it in the theme .ZIP package.


^ Back to top

Customizing Your Language

phpLinkBid supports custom language files for use in your directory. By default, phpLinkBid includes one English language file located in /inc/lang/lang_en.php. To create your own custom language file you can copy lang_en.php to a new file with your choice of language extension (e.g. lang_fr.php). Customize this file to your liking and save to the same directory. You can now select your custom language file from phpLinkBid Admin under Site Configuration.


^ Back to top

Troubleshooting

For technical problems, bug reports and additional support please visit the Support Center. To discuss phpLinkBid or find additional help please visit the phpLinkBid Forums.

^ Back to top