# Proforma v1.0 PLUS (Shareware Version) - Manual
Please note, this manual is essentially the same as the Premium Version manual. It therefore covers the entire functionality of this Shareware distribution, but also references functionality which has been disabled in this version. The main features which have been disabled are: Editing of native osCommerce Product Descriptions, Newsletters and Product Notifications. Groups and Group Manager Forms and Form Manager To purchase the Premium Version with all features enabled, please visit the Proforma v1.0 PLUS Product Information Page.
Thank you for purchasing this software. Proforma is a multifaceted content management system for the osCommerce shopping cart which improves ans extends the default osCommerce functionality. It allows you to create, edit and position your content anywhere in your store. Content units can individually be assigned to appear on specific pages and positions in your site, or on sets of pages (e.g. every product info page). Existing content for product descriptions, newsletters and product notifications can easily be found and edited with a single click, saving time spent on clicking through the osCommerce product catalog tree. Proforma also contains a simple form management section which will parse your form and automatically generate a PHP header code template which you can complete with your own code. There is a simple feedback form included in the package (which you can use straight out of the box on your website) as an example of what can be done. All content editing is done using the popular FCKEditor application which is bundled with Proforma. We hope you will find this software easy to install and use. Most of this document is also available online via the help buttons in the Proforma (PF) admin panel. If you have a support question or comment, please don't hesitate to contact us using the channels shown in the Further Support section, below. We understand that our success is based on your satisfaction and we will therefore continue to provide support to you until you are completely satisfied with the product and beyond.
### Contents
System Requirements
Installation Fresh Installation
User Guide Introduction Editing Existing Content Units Creating New Content Units Position Management Group Management Form Management
Further Support
## System Requirements PHP 4.0 or later MySQL 5.0 or later (earlier versions may work) osCommerce 2.2 Milestone 1 or 2 (earlier versions may work, but are not supported)
## Installation The installation process for this version of Proforma has been pared down to the minimum possible number of steps and file edits. For your convenience it is significantly more streamlined compared to the free version, requiring only: 4 steps 2 files to edit - 1 edit in each 4 database tables
### Fresh Installation
Step 1 - Copy all the files from the 'catalog' directory of this distribution to their respective folders on your server.
Step 2 - Backup your database, and then run the code in the file sql/proforma_v1.0_PLUS_sw_osc.sql using your favorite database interface program. REMEMBER: if you are using prefixes for your database tables you need to add the prefix to the table names in the SQL file before you run the SQL commands.
Step 3 - Open the file catalog/admin/includes/boxes/tools.php Find the line: '<a href="' . tep_href_link(FILENAME_BACKUP) . '" class="menuBoxContentLink">' . BOX_TOOLS_BACKUP . '</a><br>' . and add beneath it: '<a href="' . tep_href_link('proforma.php') . '" class="menuBoxContentLink">Proforma</a><br>' . Save and close the file.
Step 4 - Open the file catalog/index.php This is the position code for an example Proforma position. It will not alter the display of your home page unless you assign a content unit to it later. Find the line: } else { // default page And within the HTML section beneath it add these lines: <tr> <td align="center"><?php require_once(DIR_WS_FUNCTIONS . 'proforma.php'); doProformaContent('Index Default'); ?> </td></tr>
Installation is now complete. You are now ready to proceed to the User Guide and follow the steps outlined there.
## User Guide
### Introduction
To access Proforma, go to Tools->Proforma in the osCommerce admin component. 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: It is Active. It is linked to a position within the webpage. 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. Click '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: 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. 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 only two steps: Name the group - Enter the name of the new group. This will be the name referenced when linking content units to this group. 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.
## Further Support Please remember to send us your versions of PHP, MySQL and osCommerce when sending a support query.
Open Source Services Website | http://www.open-source-services.com
Support Email | support@open-source-services.com
Proforma Support Forum | http://www.open-source-services.com/Forum/Proforma-PF-v1.0-PLUS-Shareware-Version-osCommerce/
Content Editor Support Forums | http://www.fckeditor.net/forums/
Upgrade To Premium Version | Upgrade at http://www.open-source-services.com/Products/OSS-Premium-Add-Ons/Proforma-v1.0-PLUS.html?flypage=0
Other Enquiries | http://www.open-source-services.com/component/option,com_facileforms/Itemid,52/
COPYRIGHT (c) 2008 OPEN SOURCE SERVICES. ALL RIGHTS RESERVED. Copying or re-selling of this material is illegal.