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.

    CodePurpose
    !searchinserts the keyword search field and button
    !dateStampinserts the current date (can be omitted)
    !controlPanelinserts the account options menu when a member is logged in, also uses this code to insert the login panel
    !outputinserts 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:

    StylePurpose
    .col1intended to be a table header style
    .col2intended to be a table cell style
    .col3intended to be a table cell style, for use next to col2 to help differentiate between cells
    .statusstandard green / successful message style
    .errorstandard 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:

    ItemURL
    index.cgidisplays the Showcase home page
    index.cgi?act=joindisplays the sign up page
    index.cgi?act=gallerydisplays the photo gallery
    index.cgi?act=page&f=faqdisplays 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.

    ItemDescriptionExample
    System Clock Plus HoursIn case your server time is different to your time, you can add hours here.3
    US Date DisplayThis option will display dates in a US month-first format (MM/DD/YYYY).Yes
    Page Records BreakupControls 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 MembersSet this to yes if you want to screen new members before allowing them access on the system.Yes
    Maximum # Rated Items on Home PageSet 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 PageSet how many newest items to display on the home page.
    Set to zero to disable.
    10
    Maximum # Latest Updates on Home PageSet how many latest updates to display on the home page.
    Set to zero to disable.
    10
    Show Only Categories & Members with RecordsIf 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 PageBy 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 FormatYou can set the method of display for the members list on the home page, or switch it off entirelyNo
    Open to the PublicBy setting this to no, it will close the website. Setting it to yes allows normal operations.Yes
    Accounts OpenBy 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 RatingsThis controls whether or not to allow items to be rated.Yes
    Allow Item CommentsThis controls whether or not to allow comments to be posted on items.Yes
    Integrate Item Description with Item ImagesIf 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 TitleThe name of your website. This is used when sending out emails.WorldWideCars.com
    URL to index.cgiThe 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 ItemControls 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.