User Guide

Introduction

Content units are divided into two types - Proforma Units and Native Units.

Proforma Content Units - These are content units (including forms) which are created using Proforma. They can be assigned to web pages and positions within those pages. They can be also be deleted. A Proforma content unit will only appear on a webpage if the following conditions are true:

  1. It is Active.
  2. It is linked to a position within the webpage.
  3. One of its URL substrings appears in the URL of the webpage.


Native Content Units - These are content units which are created using the default functionality of osCommerce. Specifically, these units relate to product descriptions (created via the Catalog->Categories/Products component), and newsletters and product notifications (created via the Tools->Newsletter Manager component). The positioning of native units is handled by these components, so they cannot be created, positioned or deleted via Proforma. Proforma will simply display any of these content units for quick and easy editing.

General navigation around the system is controlled via the boxes on either side of the Proforma page title:

Display Box - This box in the top-left corner of the Proforma application can be used to filter which content unit types will be displayed in the configurable list on the Proforma home page. The list is updated each time a checkbox is clicked.

Options Box - In the top-right of the Proforma component, this box contains links to the various management sections of Proforma.

The Proforma home page will display a configurable list of any content units you have selected to view via the Display Box. Click on 'Product Descriptions' to see how multiple units are listed. The displayed units can be sorted in various different ways. Please note, to change the number of units being displayed per page, enter the number required next to the 'Rows Per Page' prompt and press Enter.


Editing an Existing Content Unit

Both Proforma and Native content units can be edited via the content list. As an example, if you have selected to view Product Descriptions, you can edit any one of them in two ways. You can either use the 'Quick Find' dropdown box to find the name of the unit, or you can click on the 'Edit' icon which corresponds with the unit in the list itself.

You will now see the main content editor containing the existing content for that unit. You can make any changes you like to the content before saving by clicking on the 'Save' icon (floppy disk) within the editor's toolbar. If you choose to edit a Proforma content unit, you will also be able to edit its settings e.g. which pages and positions it will appear in.

Creating a New Content Unit

Any content unit (including forms) which you create using Proforma is known as a Proforma content unit. First, click 'Create New Unit' in the Options Box. Before you can start adding content to the unit, you need to enter the following information about it:

  • Name - Enter the name by which this content unit will be known in Proforma (minimum 4 characters).
  • Active - Set this to 'Yes' for the content to be displayed on your site.
  • Group - Choose which content group this unit belongs to. Content groups are a way of classifying your ] content units for easier handling. New groups can be created using the Group Manager.
  • Description - This is an optional description of the content. It is never displayed in the front-end of your store.
  • URL Substrings - This is how you designate which page(s) the content unit will appear in. Enter a part of the URL of the page in which you want the content to appear in. Examples include:
    • index.php - Home Page
    • product_info - All product information pages
    • 36 - Product information page for product with id number 36
    URL Substrings will also work for Search Engine Optimized URL's. Multiple URL Substrings can be assigned for display in a wider range of pages. Multiple URL Substrings should be separated by a comma. (minimum 2 characters).
  • Position - Choose a position where the unit will be displayed within the page. New positions can be created using the Position Manager.
  • Placement - If you intend to display more than one content unit in the same position at the same time, you can enter a number here representing the order in which the content unit will be displayed relative to the other units in the same position.
  • Type - Select if you are creating normal content or a form.

After you click 'Save' you will see the content editor appear below the settings you just entered. You can now use the editor to create your new content or form. Please remember to save your content using the save icon in the editor's toolbar. Clcik 'Cancel' when you have finished saving to be taken back to the Proforma homepage which will list your new content unit if you have checked 'Proforma Content' in the Display Box.


Using the Position Manager

The position manager allows you to create, monitor and delete positions in Proforma. Positions are places within your web pages where you would like to display Proforma content units. Multiple content units can be assigned to a single position. The position manager is split into two parts:

Current Positions - This section displays a list of currently available positions. The coloumns in this list are:

  • Name - The name of the position. This will be referenced when linking content units to this position.
  • Deployed - Proforma will detect if the position has been correctly placed within your webpage. If after having placed your position code in your webpage and opening that page in your browser this setting remains on 'No', then your position code has not been placed correctly. Please try to place it elsewhere in your page and try again.
  • Linked - This will be set to 'Yes' if any content unit has referenced this position.
  • Get Code - Clicking this icon will display the PHP code which must be placed in the webpage where you require the position to be.
  • [trashcan icon] - Check the box for the position you wish to delete and click 'Delete'. Only positions which are not currently linked to a content unit can be deleted.

New Positions - Creating a new position requires only two steps:

  1. Name the Position - Enter the name of the new position and click 'Save Position'. This will be the name referenced when linking content units to this position.
  2. Deploy the Position Code - Once you have entered the name and saved it, you will see the position listed in the 'Current Positions' section. Click on the 'Get Code' icon for this position and you will be presented with some PHP code which you should copy and paste directly into your webpage at the point where you want the content associated with this position to appear. Take care not to place this code in areas where it might not easily be read, for example within 'if' clauses. Also, pay attention to the surrounding HTML. You may need to enclose your position code within <tr> or <td> tags. Feel free to experiment with positions until you find the correct place. The new position will now become available when creating or editing Proforma content units. Click 'Cancel' to return to the Proforma home page.

Using the Group Manager

When dealing with large numbers of content units, it is helpful to organize them under various headings and subheadings in order to facilitate their indexing and finding. The group manager allows you to classify content units by assigning them to a common group name. Group names are used solely in the Admin side of Proforma and do not have a bearing on the way content items are displayed. The group manager is made up of two parts:

Current Groups - This section displays a list of currently available group names. The columns in this list are:

  • Name - The name of the group. This will be referenced when linking content units to this group.
  • Linked - This will be set to 'Yes' if any content unit has referenced this group.
  • [trashcan icon] - Check the box for the group you wish to delete and click 'Delete'. Only groups which are not currently linked to a content unit can be deleted.

New Groups - Creating a new group requires requires only two steps:

  1. Name the group - Enter the name of the new group. This will be the name referenced when linking content units to this group.
  2. Choose a parent - Select the parent group if required.

    Once you have entered the name and parent, click 'Save Group'. You will see the new group listed in the 'Current Groups' section. The new group name will now be available for selection when creating or editing a content unit. Click 'Cancel' to return to the Proforma home page.

Using the Form Manager

If you have previously created one or more forms as content units, they will be listed here in the 'Current Forms' section. The list has the following column names:

  • Form Name - The name of the form.
  • Target Page - The name of the page where the GET or POST name/value pairs will be sent to for processing.
  • Query String - This shows the name-value pairs that will be sent to the target page for procesing.
  • Header Code - Clicking this icon will display the PHP code which must be placed in the header section of the target page together with the content editor containing the form content.
  • [trashcan icon] - Check the box for the form you wish to delete and click 'Delete'.
Please Note: The Target Page and Query String data are parsed from the existing form content. If the content of the form unit does not contain a 'form' HTML element, these columns will remain blank. Furthermore, for correct parsing of the form HTML element, the format '[page_name].php?[name]=[value]' should be used in the 'Action' field when creating the form (it can be edited using the content editor and clicking 'Source', if there is an error). Additional name-value pairs can be appended, separated by a '&' sign.

If you click the 'Header Code' icon for the form unit, you will see a text area where you can add PHP code to act as the processing code for the data produced by submitting the form. This code can be saved anytime and when complete should be pasted into the header section (i.e. before any HTML) of the form's target page.

By clicking the 'Generate Template' button, you can create a template of PHP code to help you get started on the processing code. Proforma will check for all form elements and assign them to local variables for later processing.

Beneath the Header Code you will see the standard content editor where you can make changes to the form or check for correct name-value pairs.

COPYRIGHT (c) 2008 OPEN SOURCE SERVICES. ALL RIGHTS RESERVED.
Copying or re-selling of this material is illegal.