Showcase 1.00 Documentation, written by Andrew Gilchrist

	Introduction
Thank you for your interest in Showcase. This provides a cost-effective and easy way to setup a website that allows everyone to become of a part of the club and gets to show off. Showcase has many features that allows a wide range of customisation to be done, ensuring you do not lose the styling of the rest of your website by making it appear to be a fully-integrated feature.

Full Showcase Features List

All Pages HTMl template wrapping Keyword search field Main menu Login fields or member account options panel Home Page Randomly-selected item (brief display) / link Categories listing / links Latest Updates listing / links (can be toggled) Top Rated Items listing / links (can be toggled) Members listing / profile links (can be toggled) Item Display Page Item Title Category Title Comment link - goes to comment form View comments Contact member link Rate link - submits rating Rating (displays average of all ratings for item) Item images with thumbnails Item information panel Item description Updates list Member Profile Display Page Member name Member location Member description Contact member link List of items on display with links Join / Sign-Up Page Username, password and email address Email validation / activation required for each member New members able to be screened by admin Member account options menu (logged in) Home - takes member back to front page My Details - member can change their profile details My Items - member can add, edit or delete their items Members can request a new category be added for their item Log out - logs member out of the account Gallery Displays all the photos in the system, page by page Links to each item Admin account options menu (logged in) System Config - change behaviour and settings / preferences for the system and clear databases Categories - add, edit and delete categories Members - edit and delete member accounts Item Setup - create the custom form fields for members to fill out for each item Email Manager - mass-send emails to members and edit the outgoing email templates Log Out - logs admin out of the account

	Technical Support and Bug Reports
To request help with installing Showcase or to report a bug, please visit our home page at www.uplink.com.au or contact the author directory using andrew@uplink.com.au

	System Requirements
Unix or Linux webserver with FTP access. Perl 5 or above. ImageMagick image handling 'convert' utility installed. Webspace for script files. Webspace for images and database. Basic knowledge of HTML and CSS.

	Installation Steps
There are 5 steps involved in installing Showcase: 1. Setup the script file. 2. Setup the HTML wrapper file. 3. Upload files to the web server. 4. Login and set your preferences. 5. Create a test account to test everything. The following sections will discuss these steps in detail.

Setup Showcase for Installation (step 1)

Showcase directory structure: Main directory (contains *.cgi, *.pm and wrapper.html files)  | +--images (contains general web page image files) +--imagesDB (will contain the member's uploaded images) +--db (directory for database files)        |       +--emails (contains outgoing email template files)       +--pages (contains HTMl page files) The main script file (index.cgi) contains 2 important variables that require setting before going any further. 1. Extract everything (retaining folder paths) to a directory on your hard drive (the directory should look like above). 2. Using a text editor, open index.cgi and edit the following variables. 3. On line 4 of index.cgi is the value of your Administrator Password. Change the value inside the quotes to the password you want. 4. On line 7 is the path to the database files. If you plan to hold the database directly under your script files, leave it as is, otherwise change it to a relative or absolute path.

Setup the HTML Wrapper (step 2)

Found in the same directory as the script files, wrapper.html is the HTML file that "wraps" the output of the script in the HTML you include in this file. In order to know where it must output in between HTML in the file, Showcase notices codes placed in the file. Following is a description of the codes. Code Purpose !search inserts the keyword search field and button !dateStamp inserts the current date (can be omitted) !controlPanel inserts the account options menu when a member is logged in, also uses this code to insert the login panel !output inserts the bulk of the script's output Note 1: Each code MUST be placed on a line of its own in the file. Example: Hello, this is a line of text.<br> !search This is another line.<br> Note: It is very important that the included HTML 'FORM' tag is in the file, and its exact properties remain untouched, as it is there to submit process control data and user-entered data. The form tag must be before any of the following codes discussed below, and must have a closing 'FORM' tag after all of the codes have been placed in the file. See the example wrapper.html file in the Showcase ZIP file for an example. Embedding them in between HTML table row tags (as in the example file) will prevent line breaks from appearing on the page. Inside wrapper.html you will find several pre-defined CSS styles called by Showcase. The styles are as follows: Style Purpose .col1 intended to be a table header style .col2 intended to be a table cell style .col3 intended to be a table cell style, for use next to col2 to help differentiate between cells .status standard green / successful message style .error standard red / error message style All CSS styles may be adjusted to your preferences. The best thing to do is experiment with the colours you like. Please make a backup of wrapper.html before changing things, in case you need to revert back for reference. In the wrapper.html example file, there are folder tab style menu options for 'Home', 'Join' and 'FAQ'. These graphics are found in the "images" folder in the Showcase ZIP and may be altered to suit your website styling. These are included as a guide for your website. Please see the section on creating the home, join and FAQ page links.

Creating the Main Menu (Home, FAQ, Join, Gallery) (step 3)

The main menu allows access to the home page of your installed Showcase, the FAQ (frequently asked questions) page, the signup page and the photo gallery. The menu must be created manually so you can switch off any menu items you want, or include new ones amongst the existing ones. The default main menu included in Showcase can be found in the HTML wrapper.html file. Below is a summary of the links and what you can include: Item URL index.cgi displays the Showcase home page index.cgi?act=join displays the sign up page index.cgi?act=gallery displays the photo gallery index.cgi?act=page&f=faq displays the FAQ page Note that the FAQ page is called by opening an HTML file in the database directory 'db/pages/'. It opens faq.html. By using this system, you can create other pages and call them by replacing 'faq' in 'index.cgi?act=page&f=faq' with whatever page / file name you want. For example, to display an about page, you would create a file named 'about.html' in the 'pages' directory and then call 'index.cgi?act=page&f=about'. Using this method allows you to include whatever HTML / page you want inside the HTML wrapper.

Showcase Installation (step 4)

Following below are two types of installation. The first one is intended for quick installations on standard or generic webservers and the second is intended for webservers that may have tighter security and setup. Express Setup Ensure that steps 1, 2 and 3 are completed above. Login to your web server via FTP. Study the directory structure of the Showcase unzipped files. Duplicate all the files, folders and paths on your web server in the directory of your choice that is suitable for running Perl CGI files and can allow file reading and writing, as well as public viewing for the images. Set index.cgi to 755 file permissions. Set all *.txt files to 660 file permissions. Set the 'db' directory to 751. Your directory structure should look like the original ZIP file (click here). Go to the Testing section of this document. Custom Installation Procedure (for webservers with specific settings) Login to your web server via FTP. Study the directory structure of the Showcase unzipped files. Select or create a directory where you want Showcase to run. This is where you need to put the Perl *.cgi and *.pm files. Example: /web/cgi-bin/showcase/ or in your root directory. Upload index.cgi, index.pm and admin.pm. Set index.cgi to 755 file permission. Upload wrapper.html. Create a new directory called 'db' where you wish to store your database files. Note where this new directory is, relative to where you just uploaded index.cgi. The path is to be set in the $filePath variable in index.cgi. Set this directory to 751 file permission. Upload all *.txt files in the ZIP file's "db" folder to this new directory. Set them to 660. Create a new directory in the the database directory called "emails". Upload all *.txt files in the ZIP file's "db/emails" folder to this new directory. Set them to 660. Create a new directory in the the database directory called "pages". Upload the faq.html in the ZIP file's "db/pages" folder to this new directory. Go up to the main directory again, where index.cgi is located. Create a new directory called "images". Upload the files from the 'images' directory in the ZIP file to here. This directory must be able to be publically read. Create a new directory called "imagesDB". This directory must be able to be publically read AND allow file writing and reading. Go to the Testing section below.

Testing Showcase (step 5)

Call index.cgi in your web browser. Check that the HTML, graphics, main menu, login fields and date are displaying okay. Type in "admin" in the Username field and your admin password. Login. Go to the System Configuration screen and begin setting up your preferences. See the Admin > System Configuration section below for more information. Go to the Email Manager and setup your outgoing email templates. See the Admin > Email Manager section below for more information. Go to the Item Setup and fill out the form fields. See the Admin > Item Setup section below for more information. Start creating your categories. Log out. Create a test member account. Check if the email arrived OK. If it didn't, check your path to sendmail is correct. Activate your test account. Login to your test account and create a new item. Test the image handling by uploading an image with your new item. If the thumbnails weren't created or other image / file errors were encounted, check your path to ImageMagick is correct. If everything is going smoothly, then you can open the site. Please edit db/pages/faq.html if you wish to customise the FAQ page.

Administrator System Config Screen

This screen allows the administrator to change system settings and clear databases. Be carefull when clearing databases! Below is a run down of the admin settings available to the administrator using Showcase. Item Description Example System Clock Plus Hours In case your server time is different to your time, you can add hours here. 3 US Date Display This option will display dates in a US month-first format (MM/DD/YYYY). Yes Page Records Breakup Controls how many records to display per page when viewing lists and search results. 20 Gallery Page Images Per Line: Controls how many images to display on the gallery page per row. 5 Gallery Page Images Per Page: Controls how many images to display per gallery page. 5 Screen New Members Set this to yes if you want to screen new members before allowing them access on the system. Yes Maximum # Rated Items on Home Page Set how many top-rated items to display on the home page. Only displays if "Allow Item Ratings" is enabled and if there are rated items to display. 10 Maximum # Newest Items on Home Page Set how many newest items to display on the home page. Set to zero to disable. 10 Maximum # Latest Updates on Home Page Set how many latest updates to display on the home page. Set to zero to disable. 10 Show Only Categories & Members with Records If set to yes, it will only display categories with member items in them, and also only displays members who have items on display. If set to no, it will display all categories and members, even if empty. Yes Extend Category Levels on Home Page By setting this to yes, it will cause the category display on the home page to display step-by-step / level-by-level category navigation, instead of having all category levels combined into a single list. This is useful if you wish to breakup categories more widely, or if you have a very large number of them. Yes List Members on Home Page Format You can set the method of display for the members list on the home page, or switch it off entirely No Open to the Public By setting this to no, it will close the website. Setting it to yes allows normal operations. Yes Accounts Open By setting this to no, it will block members from logging in and updating records and also from creating new accounts. Setting it to yes allows normal operations. Yes Allow Item Ratings This controls whether or not to allow items to be rated. Yes Allow Item Comments This controls whether or not to allow comments to be posted on items. Yes Integrate Item Description with Item Images If selected to yes, the item's description on the item display page will be displayed under the main image, otherwise it will be displayed at the top of the page under the item's title. Yes System Title The name of your website. This is used when sending out emails. WorldWideCars.com URL to index.cgi The URL (with http:// and a trailing slash) to your Showcase index.cgi on the web. This is used when sending out emails with links back to the website. http://www.mywebsite.com/showcase/ Max. Image Upload Size (bytes) Controls the limit, in bytes, of how large uploaded images can be. 150000 Max. Images Per Item Controls the limit of images per member item. 6 Path to Databased Images (server) The relative or absolute server path (with trailing slash) to the 'imagesDB' directory. ./imagesDB/ Path to Databased Images (web URL) The relative or absolute web URL path (with http:// and a trailing slash) to the 'imagesDB' directory. http://www.mywebsite.com/showcase/imagesDB/ Path to ImageMagick (server) The relative or absolute server path (with trailing slash) to the ImageMagick 'convert' utility. /usr/bin/ Convert Uploaded Images to Width (full size, pixels) The width, in pixels, uploaded images are to be converted to for full-size images in the system. 525 Convert Uploaded Images to Width (thumbnails, pixels) The width, in pixels, uploaded images are to be converted to for thumbnail images in the system. 130 Path to sendmail (server) The path (with trailing slash) to the sendmail program on your server. /usr/lib/ Outgoing Emails From (name) The name you wish emails to be sent as 'From'. WorldWideCars.com Outgoing Emails From (email address) The email address you wish emails to be sent as 'From'. help@worldwidecars.com Note that the path to sendmail and ImageMagick may be obtained from your web server technical administrator / support staff. You may need to have ImageMagick installed. ImageMagick is a collection of free image-handling utilities available on the internet.

Admin > Categories

The categories in Showcase are 3-level deep. This allows a flexible setup to cater for most needs. The category manager is designed to be worked through level by level. The structure is as follows: Top Level Category      - Mid-Level Category          - Sub-Level Category An easy way to explain it is to use cars. Categories for a car would be setup as follows: Honda (top)      - Legend (mid)          - Sedan (sub)          - Coupe (sub) In this example, Sedan and Coupe are both Sub-Level categories under the Honda > Legend categories. You can edit and delete each category. Another example would be: Cars (top)      - Honda (mid)          - Legend Sedan (sub)          - Legend Coupe (sub)      - Toyota (mid)          - Corolla Sedan (sub)          - RAV4 (sub) Boats (top)      - Supermarine (mid)          - Silverstream 4 (sub)          - Mightywave V8 (sub)

Admin > Member Manager

The Showcase member manager allows the administrator to edit a member's details, delete their account and set a Member Label for their account. It is also used to enable a member account after screening it, if screening is enabled. To successfully screen a member, simply update their account and it will be enabled. An email will be sent to the member informing them of this. Deleting the account will reject their signup. The Member Label can be used to insert special information about a member, such as to indicate a donating member or founder / webmaster. This label displays under their username on an item page and their member profile page. The information inserted can be plain text or any HTML, such as an image or colour and font styling, etc.

Admin > Item Setup

The item setup screen is where you control the customised form fields displayed when a member adds an item. At the top of the screen is the field that controls the maximum amount of items a member can have. There is the option to allow items to be offered for sale. By setting it to yes, members can fill in a price and it will be displayed with a "for sale" note on the item display page. Next are the item description fields. There are 10 fields that can be used. Each field has a title. If the title is blank, it is disregarded and the member does not see it. Enter a title to use it. Each one can either be a text field or a textarea multi-line input box. By default, every item a member adds has a title and a description. These 10 fields are designed to complement these two. When a field is set to a textarea, members can input data line-by-line and it will be displayed in line-by-line format. Examples of field titles and types (using cars as a subject): Year (text input) Engine / Power / Torque (text input) Colour (text input) Standard Features (textarea) Factory Options (textarea) Modifications (textarea)

Admin > Email manager

This is where you can mass-send emails to members and setup your outgoing email templates. If you select the 'Send Email to Members' option, a screen will load where you can type in an email subject and the message body. Clicking 'send' will send it to all of your enabled members. If you select the 'Outgoing Email Templates' option, you may then select an email to modify. Select one of the emails and an editor screen will appear. Here you can edit the body of the email and use the provided codes to be inserted. A specific set of codes exist for each email. The codes begin with ! and will be replaced by the relevant data.

Showcase > Home Page

On the product's home page, the following sections are displayed: Item spotlight - randomly selects an item and displays a brief teaser about it Category selector - displays the categories on the left Members list - displays the members on the right (toggable) Latest Updates - displays the newest X items and updates in the system (toggable) Top rated items - displays the X highest rated items in the system (toggable) Note that if there is only one item in a category when you view a category, you will be taken straight to it.

Showcase > Item Display Page

When an item is viewed, the following information is displayed: Category and item titles on the top left Comment, rate and member contact options on the top right Category link on the right, or special "only one in this category" notice Next line displays the item's description The next large box displays the member's name and profile link, member's label, for sale info, item fields info To the right of the above section are the item's images The first uploaded image is displayed first, then a collection of the item's thumbnails are displayed that can be clicked on to be enlarged The Admin Config screen allows you to modify the way this page is displayed.

	Showcase > Member Profile Page
When a member's username is clicked on, it will display their profile page: Member's username Member's location with contact link Member's label Member's description Collection of member's items on display, with links to each one and its category

	Showcase > Gallery
The photo gallery displays all the images on the system, from new to last, broken up into a number per page (adjustable in configuration). Users may click on the thumbnail to view a larger version, or go to the itempage the image came from.

Showcase > Troubleshooting

Problem: The actual Perl programming script is shown to me when I execute the script in my browser, but I have followed all the correct setup procedures. Solution 1: Try renaming index.cgi to index.pl and then do a mass search and replace in the file and it's .pm files for ".cgi" and replace all instances with ".pl". It may be that your server requires Perl scripts to run under *.pl extensions. Solution 2: Try installing the script files under your dedicated "cgi-bin" directory if you have installed them elsewhere. Your server may only execute CGI scripts in your "cgi-bin" directory. Problem: Emails are not being sent. Solution 1: Please ensure that the path to sendmail in the admin config screen has been properly set to your server's setting. Please ensure it contains a trailing slash /. Problem: My changes to the database or email files are not being saved. Solution 1: The database files may require a specific file permissions setting other than a standard 660. Please check with your server admin for further information. Solution 2: Your server may require the database files to be located under a different directory to your "cgi-bin" directory. Problem: When I upload an image it always fails with an error. Solution 1: Your server may not allow temporary writing of data files in your "cgi-bin" directory, which is required by Showcase using the standard CGI.pm Perl module to handle file uploading. Try relocating the scripts to a directory outside of "cgi-bin". Problem: No matter what I try, it keeps displaying "500: Internal Server Error." Solution 1: You may have uploaded the Perl, HTML and text files in binary file transfer mode. Please ensure your FTP program is set to ASCII transfer mode for these types of files.