Product Attribute Pictures v7.0 - User Guide

This software is a dynamic and flexible imageing solution for your OpenCart online store. Its features include easy uploading and management of image files together with fine-grained control over display options and bulk copying of images and settings to other products.

We hope you will find this software easy to install and use. The User Guide section of this document is also available online via the help buttons in the PAPs 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.

To unlock the software, please see the Licensing section below.

Contents

System Requirements
Installation
  Fresh Installation
  Optional Installation Steps
  Licensing
Quick Start Guide
User Guide
  Uploading Images
  Adjusting Display Settings
  Bulk Copying
  Configuring Tooltips
  Popup Viewers
  Linked Attribute Images
  Merged Attribute Images
  Swatch Attribute Images
  Settings Profiles
Troubleshooting
Further Support, Customization and Development Services
Appendix

System Requirements

  • PHP 4.3 or later
  • MySQL 5.0 or later (earlier versions may work)
  • OpenCart 1.4.9.1 or later (earlier versions may work, but have not been tested)


Installation

If you have already installed PAPs and used it with the free 14-day trial license prior to purchasing a full license, there is no need to perform any of the steps below. You simply need to request a new license from us by following the instructions in the licensing section.

The installation process for this version of PAPS 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
  • 5 files to edit
  • 7 database tables
If you are upgrading from a free version, you will be able to delete some redundant code (see below).

Fresh Installation

Step 1 - Apart from the 'NOT_FOR_UPLOAD' folder, copy all the files and folders (even if some are empty) from this distribution to their respective places in your Open Cart store.
Step 2 - Backup your database, and then run the code in the file NOT_FOR_UPLOAD/sql/paps_v7.0.sql using your favorite database interface program. REMEMBER: do not add any database table prefixes to the PAPs database table names.
IMPORTANT - It is strongly recommended that before proceeding with the next step, you should obtain either a trial or full license key file because if this software is installed without one, the code will generate error messages in your product pages and PAPs admin page. To obtain a license, see the licensing section.
Step 3 - You now need to edit some files in your existing Open Cart installation. You can do this two ways. EITHER look in the NOT_FOR_UPLOAD/compare_and_merge folder of this distribution and use a compare application to identify the new PAPs code and deleted existing code and make the appropriate changes (these files are based on a vanilla Open Cart installation), OR follow the instructions below:

i) Open the file: admin/controller/common/header.php

BELOW this line: $this->data['title'] = $this->document->title;

add the following lines:

$this->data['text_paps'] = $this->language->get('text_paps');//PAPS

$this->data['paps'] = HTTPS_SERVER . 'index.php?route=catalog/paps&token=' . $this->session->data['token'];//PAPs


ii) Open the file: admin/language/english/common/header.php

before the final ?> add the following:

$_['text_paps'] = 'Product Attribute Pictures';//PAPs

Repeat this for any corresponding language files in the admin/language/ directory.

iii) Open the file: admin/view/template/common/header.tpl

on line 10 (or anywhere inside the 'head' HTML tag), add the following: <link rel="stylesheet" href="view/template/catalog/paps/includes/paps.css" type="text/css">

around line 78 BELOW the line <li><a href="<?php echo $information; ?>"><?php echo $text_information; ?></a></li>

add the following: <li><a href="<?php echo $paps; ?>"><?php echo $text_paps; ?></a></li>

iv) Open the file: catalog/view/theme/YOUR_TEMPLATE_NAME/template/checkout/cart.tpl

Find this line: <td align="center"><a href="<?php echo str_replace('&', '& amp;', $product['href']); ?>"><img src="<?php echo $product['thumb']; ?>" alt="<?php echo $product['name']; ?>" /></a></td>

and REPLACE it with this:

<td align="center">
<?php
//BOF Product Attribute Pictures
$paps_thumb_width = '75px';
require('catalog/view/paps/includes/modules/paps_layout/paps4cart.php');
//EOF Product Attribute Pictures
?>
</td>


NOTE: the value assigned to '$paps_thumb_width' above will determine the size of PAPs thumbnails associated with product option selections made in the product page as they will appear in the shopping cart page if you set 'Show PAPs in Cart' to 'Yes' in the PAPs admin page.

v) Open the file: catalog/view/theme/YOUR_TEMPLATE_NAME/template/product/product.tpl

Find this line: <?php if ($options) { ?>

and immediately ABOVE it add the following:

<?php
//BOF Product Attribute Pictures
require_once('catalog/view/paps/includes/modules/paps_layout/includes/classes/paps_delegate.php');
$paps_delegate = new paps_delegate($product_id, $this->config->get('config_language_id'));
//EOF Product Attribute Pictures
?>


Find this line: <?php foreach ($options as $option) { ?>

and immediately BELOW it add the following:

<?php
//BOF Product Attribute Pictures
if(!$paps_delegate->allowAttributeSelection($option['option_id'])){
//EOF Product Attribute Pictures
?>


Find these lines: <?php } ?>
</table>
</div>
<?php } ?>
<?php if ($display_price) { ?>


and immediately ABOVE them add the following:

<?php
//BOF Product Attribute Pictures
}else{
?>
<tr>
<td>
Select '<b><?php echo $option['name']; ?></b>' option below.
<input id="selattr<?php echo $option['option_id']; ?>" type="hidden" name ="option[<?php echo $option['option_id']; ?>]" value="<?php echo $option['option_value'][0]['option_value_id']; ?>"></td>
</tr>
<?php
}
//EOF Product Attribute Pictures
?>


NOTE - the following code from the lines above: Select '<b><?php echo $option['name']; ?></b>' option below. will appear in the default Open Cart attributes box instead of the native dropdown box to instruct users to make attribute selections via PAPs images if attribute selection via PAPs is enabled in PAPs admin. You can change the text/language used here as required.

Find this line: <div class="tabs">

and immediately ABOVE them add the following:

<?php //BOF Product Attribute Pictures ?>
<div><table><?php include_once('catalog/view/paps/includes/modules/paps.php'); ?></table></div>
<?php //EOF Product Attribute Pictures ?>


IMPORTANT - The code above determines the position of the PAPs display in the product page. The default positioning is just above the tabbed information area but you can experiment with putting it in different places. The ultimate look and feel of the PAPs display area will also depend on your selected settings in PAPs admin, e.g. the position of the thumbnails relative to the enlarged (selected) picture etc.
NOTE - If you want to enable automatic price updating and/or the 'detach from enlarged image' thumbnails position in your product info page, please see the Optional Installation Steps section below.
Step 4 - Ensure the following folders are fully writeable:

image/paps
image/paps/linked
image/paps/fonts
image/paps/swatch_enl
image/paps/swatch_enl/tmp
image/paps/tmp

Installation is now complete. You are now ready to proceed to the User Guide and follow the steps outlined there.

Optional Installation Steps

The following steps are not required to get PAPs working, but may increase or enhance performance if required.
Enable Automatic Price Update When Attribute Option Images Are Clicked - In catalog/view/theme/YOUR_TEMPLATE_NAME/template/product/product.tpl:

Find the following line:
<td><?php if (!$special) { ?>
and REPLACE it with:

<?php //BOF Product Attribute Pictures ?>
<td id="price_display"><?php if (!$special) { ?>
<?php //EOF Product Attribute Pictures ?>


Enable 'Detached From Enlarged Image' as a Thumbnails Position Option - In catalog/view/theme/YOUR_TEMPLATE_NAME/template/product/product.tpl:

If you want the position of your thumbnails to not be directly adjacent to the enlarged image, you need to select the 'Detached From Enlarged Image' position from the dropdown menu in the PAPs admin panel. In this case, the position of the line:

<?php include_once('catalog/view/paps/includes/modules/paps.php'); ?>

within the product.tpl file (which is placed in step 3 of the Fresh Installation process above) determines only the position of the thumbnails. A separate file must be included in the product.tpl file which will generate the enlarged picture wherever you place it. To include the enlarged picture elsewhere in your page, add the following line:

<?php include_once('catalog/view/paps/includes/modules/paps_layout/enlarged_pic.php'); ?>

to your product.tpl file. As with the paps.php file included earlier, this display begins and ends with 'tr' tags, so should be placed within 'table' tags.



 

Licensing

To get a 14-day shareware license key for this product:

1) Go to the Product Attribute Pictures website and create an account.
2) After logging in to your account, click 'My Account' in the 'User Menu' on the left side of the page.
3) In the 'License Section' of the 'My Account' page, select this product from the dropdown list and click 'Get License'.
4) You will immediately be sent a license for this product as an email attachment. Copy the license file into the root directory of your store (e.g. 'catalog/' or its parent folder) and test your installation by viewing a product info page in your store.

To get a full pre-paid license key for this product:

1) Go to the contact page at the Product Attribute Pictures website.
2) Fill out the form, choosing 'Licensing' in the 'Subject' dropdown.
3) In the main body of your enquiry you must include the domain name of the website where you'd like to run Product Attribute Pictures. The 'www' is optional. Also please include the Purchase Order Number which was sent to you when you purchased the software.
4) We will send you a license that will work on your domain and on local development machines. In all cases, we aim to send you the license within 6 hours of receiving the request, depending on time of day.
5) When you get the license, drop it into the root folder of your cart installation or the folder above it - usually the web root of the server. You should now be able to run the product.

Click here to return to the installation section of this guide.


Quick Start Guide



A full rundown of all the available settings in PAPs can be found in the User Guide section below. As you will see when first accessing the PAPs admin panel, there are many settings that can be adjusted to vary the presentation of your pictures and this can seem quite daunting at first, so below is a list of some possible scenarios achievable using PAPs together with the settings you should adjust to achieve the required effect. You could try to achieve the solution which is closest to your requirement and then fine-tune it by changing individual settings.

One of the most important things to remember is that regardless of layout choices, if you want to allow users to select attributes for inclusion in the cart via PAPs you either have to set up product attributes/options in your admin component's attribute/option handling section or check the 'Create Native Attribute' checkbox when uploading images first, and then 'Allow Attribue Selection' to 'Yes' in the PAPs admin page.


I want to display a simple gallery of product pictures without the separate 'enlarged image' area.

Uploading:
Enter a name for the group of pictures in the 'New PAPs group' text field in the uploads section. Add the number of images to upload and click 'Submit'. You will then have a chance to give a name to each of the pictures individually.
Settings:
- Enable Selected Image: No
- Number of Pictures Per Row (as required)
- Width of Thumbnails (as required)
Optional Settings:
- Enable Tooltips
- Overflow Panes
- Display Group Name
- Display Group Values
- Popup Type
Comments:
By experimenting with the size of overflow panes and images, you could set up a scrollable window of large images.


I want to let customers enlarge the thumbnails in the viewing area and select attributes to add to the cart.

Uploading:
Set up your attributes using the native attribute configuration component in admin. Then select the name of the attribute set from the 'Existing native attribute:' dropdown in the upload section. Upload an image for each attribute option value.
Settings:
- Enable Selected Image: No
- Allow Attribute Selection: Yes
- Select For Cart Using (as required)
- Enlarge Thumbnails By (as required)
- Number of Pictures Per Row (as required)
- Width of Thumbnails (as required)
Optional Settings:
- Show PAPs in Cart
- Enable Tooltips
- Overflow Panes
- Display Group Name
- Display Group Values
- Popup Type
...
Comments:
If uploading images for more than one attribute set per product, we recommend setting 'Select For Cart Using:' to 'Radio Buttons' so that users can see which attribute options they have selected from each set.


I have many pictures and don't want users to have to scroll up and down the page to select then view thumbnails. The images represent product attributes and I want to display attribute option names and price differentials below each thumbnail, but want users to select attributes via default dropdowns.

Uploading:
Set up your attributes using the native attribute configuration component in admin. Then select the name of the attribute set from the 'Existing native attribute:' dropdown in the upload section. Upload an image for each attribute option value.
Settings:
- Allow Attribute Selection: No
- Display Group Values: Yes
- Display Attribute Prices: No
- Overflow Panes (as required)
- Enlarge Thumbnails By (as required)
- Number of Pictures Per Row (as required)
- Width of Thumbnails (as required)
Optional Settings:
- Enable Selected Image
- Enable Tooltips
- Popup Type
Comments:
If you have multiple attribute sets to display you can choose either to display each set in its own 'Overflow Pane' or have one pane containing all attribute picture sets.


I want to show hybrid pictures depicting combinations of attribute selections from different groups.

Uploading:
Initially, you will need to upload pictures for each individual attribute showing only that attribute. You will need to do this for each group of pictures you want to link together. Then set 'Use Composite Images' to 'Yes' and perform the uploading of the linked (hybrid) attribute pictures.
Settings:
- Use Composite Images: Yes
- Enable Selected Image: Yes
- Enlarge Thumbnails By: Click Thumbnails
- Allow Attribute Selection: Yes
- Select For Cart Using: Click Thumbnails
Optional Settings:
- Show PAPs in Cart
- Overflow Panes
- Popup Type
and others
Comments:
Further information on using linked attribute pictures can be found here.


I want to allow users to select attributes for inclusion in the cart from more than one attribute set.

Uploading:
Select from the 'Existing Native Attribute' dropdown to choose the group you will upload images for then click 'Submit'. Repeat for more than one attribute group as required.
Settings:
- Allow Attribute Selection: Yes
- Select For Cart Using: Click Thumbnails or Radio Buttons
Optional Settings:
- Use Composite Images
- Enable Selected Image
- Enlarge Thumbnails By
Comments:
Attributes/options need to be set up for the product in your admin component's attribute/option handling section prior to upload.

User Guide

Uploading Images

This is the first step to setting up your images for any given product.

1) In the Admin component, go to Catalog->Attribute Pictures via the menu on the left.
2) Select the product to which you would like to add images using either its model number or name. Use the dropdown menus to choose.
3) Initially, you will see a message stating that there are no pictures available for this product. Beneath this message, you will see the upload section.
4) In the uploads section you can choose between uploading images for the following types of attributes:

Existing Native Attribute - An existing native attribute is an attribute which you have already assigned to the selected product via your admin component's attribute/option handling section. You should select an attribute from this dropdown box if this is the FIRST time you are adding any images at all to the attribute. If you select an attribute from this dropdown box for which you have already added images, you will be required to re-upload images for all the existing option values.

If you intend to upload pairs of images to create a swatch configuration, check the 'Create swatch' checkbox before selecting the attribute name from the dropdown. For more information on creating swatches, see the Swatch Attribute Images section.

New PAPs Attribute - A new PAPs attribute is an attribute which hasn't been set up as a native product attribute/option. Using this dropdown will give you the option of automatically setting up this PAPs attribute as a native attribute/opion (using the 'Create Native Attribute' checkbox) without having to set it up via your admin component's attribute/option section at all (see point 6, below). Using this option without clicking 'Create Native Attribute' will create a non-native picture set whose option names you can edit at any time, and use as standalone extra product images not related to product options.

Existing PAPs Attribute - Use this dropdown box to select an attribute (either native or PAPs-only) to which you have already assigned images but now wish to add some more. The new images will be grouped together with the attribute's existing images. Using this dropdown will also give you the option of automatically setting up this PAPs attribute as a native attribute (if it isn't already) without having to access your admin component's attribute/option handling section at all (see point 6, below).

SUGGESTION: You should upload at least 2 pictures for each new attribute. Enter a number in the box provided and click 'Submit'.

5) You will now see a number of rows allowing you to upload your product attribute images. You will need to fill every row before uploading. Each row has 2 columns:

  • Group Value - This is the specific name of the individual attribute (e.g. Red, Large, Gothic etc). If you chose to add images for an existing native attribute, you will see the first column automatically populated with a list of all relevent attribute values. These attribute values are the ones you previously set up either in your admin component's attribute/option handling section, or by using 'Create Native Attribute' during a previous upload (see point6, below).
  • File - This is the filepath and name of the image file that you will choose by clicking on the 'Browse' button. All attribute values must be assigned a filename or the files will not be properly uploaded.
For example, if you wanted to upload 3 pictures showing different colors, your upload section would look like this:

Group ValueFile
Red[FILENAME].jpg
Green[FILENAME].jpg
Blue[FILENAME].jpg


WARNING: If you plan to upload several large image files, make sure that the total aggregate size of all files added together does not exceed the 'upload_max_filesize' or 'post_max_size' settings in your web server's php.ini file.

6) Create Native Attribute - If this checkbox is checked, the attribute names and associated option values will be saved as native attributes associated with the currently selected product in the native OpenCart database tables. This is designed to save time in setting up attributes by avoiding the need to access your admin component's attribute/option handling section in order to allow your users to select attributes/options for inclusion in the cart via PAPs. PAPs attributes set up in this way will appear in your admin component's attribute/option handling section as if they had been set up there previously. Here are a few points to remember:
  • All editing/deletion of attributes created in this way must be done in your admin component's attribute/option handling section.
  • Price differentials for product attributes/options created in this way are always set to +0.00. This can be changed in your admin component's attribute/option handling section.
  • If the attribute name is already associated with the product prior to uploading the images, the effect of checking this box will be nullified.
  • If your store is multi-lingual, the attribute name and option values you entered prior to uploading will be applied to all languages. You will need to edit the values for each language in your admin component's attribute/option handling section.


7) WATERMARKING - If you do not require watermarks to be overlaid on your uploaded images, select 'No Watermark' from the 'Font Type' dropdown and click 'Upload', ignoring the other watermark settings. The watermarking system allows watermarks to be added to all pictures in the current upload dialogue. This means that different text, fonts and positioning can be applied to different picture sets if required. All uploaded image files must be either .jpg, .gif or .png to work with watermarks. To use the watermarking functionality, adjust the following settings before clicking 'Upload':

Font Type: - Choose the font you wish to use. PAPs comes with the Arial font as default. To make other fonts available you should add the required .ttf (font) files to this folder in your store: images/paps/fonts . All .ttf files within this folder will appear in the Font Type dropdown for selection. .ttf files can be downloaded freely from sites such as http://www.1001freefonts.com
Watermark Text: - This is the text which will appear as the watermark.
Font Size: - If your server has the GD1 graphics library installed, this setting is the font size in pixels. If you are using the GD2 library, it is the point size of the font. You can discover the optimal font size by experimenting with a few trial uploads.
Font Opacity: - This setting controls the opacity of the watermark text. The value must be from 0 to 127. 0 is completely opaque and 127 is completely transparent.
Pixels From Left Edge: - The base of the first character of the watermark text will appear this distance from the left edge of the uploaded image.
Pixels From Top Edge: - This is the vertical distance from the top edge of the uploaded image to the baseline of the watermark text.
Rotation: - The angle in degrees, with 0 degrees being left-to-right reading text. Higher values represent a counter-clockwise rotation. For example, a value of 90 would result in bottom-to-top reading text.


8) When you have entered the information in both columns of the uploads section and entered the watermark information (if required), click 'Upload'. Congratulations! Your pictures have been attached to the selected product and you should now be able to see them if you look at the item's product info page in your store.
At this point, you can make adjustments to the way your pictures are displayed. The next section deals with these options.


Adjusting Display Settings

After you have uploaded a group of images, you can make various adjustments to the way in which those images are displayed. To make adjustments for images already uploaded for a different product simply select the product from the dropdown menus at the top of the screen.

You should now see the Current Images section, which has the heading: 'CURRENT PRODUCT ATTRIBUTE PICTURES FOR: ' followed by the product name and model number. Below this you will see the following product-level options:


Enable Tooltips (Yes/No):

'Yes': you will be able to add and edit option-specific (i.e. per thumbnail) tooltips to each image. Tooltips can be added to thumbnails regardless of whether or not they are associated with product attribute options. When set to 'Yes', a column entitled 'Tooltip' will appear in the attribute-specific table below. Click on the icon corresponding to the specific attribute value to add/edit tooltip information. You will also be able to edit a variety of display settings to better integrate the tooltip display with your webpages by clicking the 'Configure Tooltips...' link next to this setting.
'No' (default): this setting will disable tooltips and hide the tooltip configuration link.

Show PAPs in Cart (Yes/No):

'Yes': if the user selects an option value via a PAPs thumbnail (or if the default OpenCart dropdown box is used for the selection of an attribute which also has a PAP associated with it) and adds the item to the cart, the selected option picture will be displayed in the shopping cart instead of the default product picture. For linked or merged attribute combination images, the image depicting the selected combination of options will appear in the cart. For swatch selections, the enlarged image corresponding to the selected swatch thumbnail is shown in the cart at a reduced size.
'No' (default): the default OpenCart product picture will be displayed in the cart regardless of which product attribute (if any) has been selected by the user.

Use Composite Images (Yes/No):

This option is only available if 2 or more groups of images have been uploaded for a product.

Composite images can be either 'linked' or 'merged'. Both types of composite provide images that represent the currently selected combination from 2 or more sets of options after a thumbnail from any set is activated. For more information, see the sections on linked attribute pictures (LAPs) and merged attribute pictures (MAPs).

Enable Selected Image (Yes/No):

If you want to have a vanilla gallery without using a separate larger image area to display clicked thumbnails, set this to 'No'. You can still use one of the Javascript popups in the 'Popup Type' dropdown if you want to enlarge your pictures that way.

Preload Selected Image (Yes/No):

With this option set to 'Yes', all enlarged images will be preloaded into the browser using Javascript, so that when the user activates a thumbnail in order to produce the enlarged image, the enlarged image will be displayed immediately. This option works best for relatively few numbers of images (roughly up to 30-40) per page, depending on the size of the enlarged image. It does not apply to images displayed via Javascript popups. The setting should be 'No' if you are not planning on using selected images.

Viewing Area Title:

Edit this textbox to change the main heading for PAPs viewing section on your product information page. This textbox will be reproduced for all the available languages in the store.

Viewing Area Subtitle:

Edit this textbox to change the text below the main title. This could include a brief instruction for users on how to use the viewing area. This textbox will be reproduced for all the available languages in the store.

Main Image Title:

Edit this textbox to change the text which will appear above the enlarged image which the user has selected. If you check the 'Use Option Name' checkbox next to the text box, the title of the selected (main) image will automatically revert to the attribute value whose thumbnail the user has selected. This textbox will be reproduced for all the available languages in the store.

Thumbnails Position:

Choose the appropriate layout for the viewing area on the product information page. Thumbnail positions are relative to the enlarged 'selected image' display area. If this is disabled via the 'Enable Selected Image' setting, this setting will become redundant and therefore hidden.

NOTE - If you want to enable the 'Detach From Enlarged Image' option, please ensure you have followed the additional installation step in the Optional Installation Steps section.

Overflow Panes:

If you have many pictures to display but don't want your visitors to have to scroll up and down the page in order to first select, then view the enlarged thumbnail then you should use an overflow pane. This is in effect a separate 'window' inside the web page the dimensions of which you can set. Thumbnails will be displayed inside this area and scrollbars added to the area as more pictures are added. This allows users to view all your pictures by scrolling the window (overflow pane) instead of the entire page.

Enlarge Thumbnails By:

This option is only available if 'Enable Selected Image' is set to 'Yes', since the 'selected image' is the enlarged image. You can choose the manner in which users choose to have a thumbnail enlarged in the 'selected image' area.

Popup Type:

If you want the user to have a choice of viewing an even larger image of the selected attribute picture as a popup, here you can choose the method by which the popup will be rendered. Please note - even if you have selected one of the viewers from this list, the user will only be able to activate the selected (enlarged) picture and view the popup if the image file you originally uploaded as the product attribute picture is larger than the selected (enlarged) picture. The PAPs system automatically calculates if the uploaded file's image size is larger than the enlarged picture, and creates a link to the popup if this is the case. For more information on the various viewers you can choose from, see the Popup Viewers section.

Popup Type - Create Gallery:

Some popup types support the automatic creation of image galleries which can be navigated within the popup itself. The implementation of each popup's gallery is different but generally they all include a 'previous' and 'next' button for users to change the popup image without having to click PAPs thumbnails or enlarged images.

Popup galleries support either swatch or non-swatch picture sets, or a mix of both. The popup viewers which support gallery creation are: Thickbox, Colorbox, GreyBox, Lightwindow, Fancybox and Slimbox. The 'Create Gallery' checkbox will only appear if one of these viewers is currently selected.

NOTE: if 'Enable Selected Image' is set to 'No' and a Popup Type has been selected, users will be able to activate the popups from the thumbnails themselves.

Image Effect:

PAPs includes a rich set of effects you can apply to your thumbnails, regardless of their size. They are applied across all image sets on a per-product basis. Available image effects are:
  • Curved Buttons - Makes rounded edges for your thumbnails.
  • Apple Cover Flow - Presents your thumbnails using the popular Cover Flow layout.
  • Shaded - Adds a shadow behind your thumbnails to make them look like they are lifted off the page.
  • Curled Corner - Creates a 'dog-ear' on the bottom-right corner of your tumbnails. Only applicable to one image set per product.
  • Blurred Edges - Adds a smoked-glass finish and slightly rounded edges to your thumbnails.
  • Film Roll - Frames your thumbnails within old-style film.
  • Shiny Buttons - Rounds the corners and applies a shine to your thumbnails.
  • Polaroids - Presents your thumbnails as old-style instant photos. Only applicable to one image set per product.
  • Photo Slides - Puts you thumbnails in old-style slide frames.
NOTE: Image effects cannot be applied to the enlarged image or Javascript popup images.

Beneath these settings, you will see one column of settings for each product picture group that you have uploaded pictures for. Each column consists of the following:

  • A 'Current Product Attributes Pictures' table -

    This table shows which pictures you have already uploaded to the server as a group, together with the names with which they are associated. Tooltip content, price differentials and other information are also shown here. You can also view or delete any of the pictures via this table.

    NOTE: Both group and individual image names can be edited at any time for non-native picture groups, but not for native picture groups.

    The fields in this table are:
    • Order: (only available if 2 or more picture groups are present) - set the display order of this group of pictures relative to the other group(s).
    • Group Value - A list of all the group values (i.e. names) currently associated with the group name. If the attribute/option group is non-native, this field will be editable.
    • Attribute Price - Displays the price differential of the attribute relative to the default product's price. This field will only be displayed if attribute/option group is native.
    • Tooltip - This field displays icons which when clicked next to the desired attribute value will show a text area containing the current tooltip content. You can add extra information about each individual attribute value. It is also possible to add HTML tags within the content to further enhance the presentation of your tooltip if required. Please avoid using double quotes in your content because this may cause the tooltip feature to malfunction - single quotes or apostrophies are fine. Click 'Update' to save your changes. All changes made will be instantly accessible in your storefront once you refresh your product_info page. The 'Tootltip' field will only be displayed in this table if 'Enable Image Tooltips' is set to 'Yes'.
    • View - View the uploaded image for a particular group value. This field is displayed for all non-swatch picture sets.
    • Swatch - View the swatch (thumbnail) image. This field will only be displayed if the attribute set has been set up as a swatch.
    • Enlarged - View the enlarged image associated with the attribute option swatch. This field will only be displayed if the attribute set has been set up as a swatch.
    • Sort - Enter the sort order of the images within the group.
    • [ICON] Delete - Check the box if you wish to delete a particular group value, then click the nearest 'Save' icon.

    NB - The fact that your uploaded pictures appear in this table does NOT necessarily mean that they are currently being displayed in the product info page.

  • Display Group Name:

    'Yes' (default): the group name (general heading e.g. Material, Size etc.) will be displayed above the group of pictures showing the different attribute values.
    'No': the attribute name is hidden.

  • Display Group Values:

    'Yes' (default): the group value (specific title e.g. Cotton, Large etc.) will be displayed below each attribute value picture.
    'No': the group value (i.e. name of the picture) is hidden.

  • Display Attribute Prices (available for native attributes only):

    'Yes': the price differential (e.g. +$2.00, -$3.50) will be displayed below each attribute value picture.
    NB - the price differential should already be set via your admin component's attribute/option handling section.
    'No' (default): the price differential is hidden.

  • Allow Attribute Selection: (available for native attributes only):

    'Yes': a radio button will be displayed below each attribute value picture. Customers can select which attribute value they would like to purchase by clicking on the radio button. When the item is added to the shopping cart, the attribute value will be added to the cart, together with the price differential. The store's native selection method will not be displayed for this attribute/option group.
    'No' (default): the radio buttons will be hidden, and customers will use your store's native selection method to choose which option they require.

  • Select for Cart Using: (available for native attributes only)

    The method by which users will be able to select the attribute for inclusion in the cart.

  • Number of pictures per row:

    Default: 3 - enter the maximum number of thumbnail pictures to be displayed per row next to the main selected picture frame.

  • Width of thumbnails (pixels):

    Default: 80 - enter the width in pixels of each thumbnail (attribute value picture).

  • Width of selected pic (pixels):

    Default: 300 - enter the width in pixels of the enlarged picture which displays the selected thumbnail.

NB - Only image widths can be set in order to maintain the aspect ratio of each image. You should always ensure that you upload pictures which are slightly larger than required because the system can reduce large images but will not increase the size of smaller images. Again, this is to maintain the quality of the image.

Bulk Copying


If you have uploaded a set of pictures which you want to use with other products, you can copy an entire image set (i.e. all attribute value pictures for a specific attribute name), together with its current settings, to one or more other products with just one click.

Overwrite if attribute exists:

If this checkbox is checked and a PAPs-enabled attribute with the same name is already associated with the target product, all PAPs images and their settings associated with the currently selected attribute on the target product will be overwritten by the current product's attribute images and settings.

If left unchecked, all current PAPs images and settings associated with the currently selected attribute will be added to any existing PAPs images and settings already associated with the same attribute on the target product.

If the target product doesn't have the same attribute name already associated with it, either setting (checked or unchecked) will result in the PAPs images and settings associated with the currently selected attribute being copied to the target product.
Create native attribute:

If this checkbox is checked, PAPs will set up attribute information for the target product on the native store database tables. This is useful only if you want users to be able to select attributes for inclusion in the shopping cart via PAPs in the target product's product information page. More information on the process of creating native attributes this way can be found in step 6 of the Uploading Images section.
Copy to product:

Select a product to which you want to copy the set of attribute pictures. To select multiple products, press CTRL + Left-Click on each additional product. Please note that ONLY PAPs settings and pictures are copied to the target product. Native product attribute settings e.g. price differentials etc. are NOT copied over to the target product unless you check the 'Create native attribute' checkbox.

Configuring Tooltips


To access the tooltip settings box, you need to set 'Enable Image Tooltips' to 'Yes' in the 'Product Settings' box, then click on the 'Configure Tooltips...' link which will appear next to it. The 'Tooltips Settings' box is where you can configure site-wide settings for your PAPs tooltips. Tooltip settings are split into three groups - 'General', 'Tooltip Heading' and 'Tooltip Body' and are as follows:

General
  • Click To View:

    'Yes': the tooltip will only appear if the thumbnail is clicked.
    'No'(default): the tooltip will appear if the mouse pointer is hovered over the thumbnail.

  • Display Delay:

    Default: '0' enter a number in milliseconds for the period of delay before the tooltip is displayed after it is triggered.

  • Fade:

    'Yes': the tooltip will fade in at a speed set below. NB - some browsers do not support this feature.
    'No'(default): the tooltip will appear immediately when it is triggered.

  • Fade Speed:

    Default: '0.04' enter a number between 0 and 1 to represent how fast the tooltip fades in. NB - some browsers do not support this feature.


Tooltip Heading
  • Border Color:

    Default: 'A5CFE9' enter a 6-digit hexadecimal value representing the color of the border around the heading area of the tooltip (do not include the hash sign '#').

  • Width:

    Default: '150' enter the desired width in pixels of the heading area of the tooltip.

  • Text Color:

    Default: '4B7A98' enter a 6-digit hexadecimal value representing the color of the text within the heading area of the tooltip (do not include the hash sign '#').

  • Background Color:

    Default: 'D5EBF9' enter a 6-digit hexadecimal value representing the color of the background of the heading area of the tooltip (do not include the hash sign '#').

  • Opacity:

    Default: '85' enter a number between 0 and 100 to represent the degree of opacity of the heading area. '0' denotes completely transparent, '100' is completely opaque.

  • Font Family:

    Default: 'arial' enter the font family of the text within the tooltip heading area. Multiple families can be added, separated with a comma.

  • Font Size:

    Default: '11' enter a number representing the size of the font in the tooltip heading area. The higher the number, the larger the font.

  • Font Weight:

    Default: 'Bold' select a font weight from the dropdown box.


Tooltip Body

The inputs for the tooltip body are the same as for the heading area (see above) except that the font weight cannot be set in the tooltip body. You can add further flexibility to your tooltips display by including HTML tags within the tooltip content, but please remember to use single - not double - quotes when doing this.

Popup Viewers


You have a choice of 11 popular open source popup viewers to allow your customers to get an even closer look at your attribute pictures. Certain features of these viewers can be customized to varying degrees. To make customizations, you will need to find the relevent .js or .css files for each viewer in the catalog/includes/popups folder. Further support for each viewer can be found at the websites shown below:
  • Thumbnail Viewer - This is the most lightweight, no-frills viewer of the eleven available. Few customizations are possible. Support can be found at http://www.dynamicdrive.com/dynamicindex4/thumbnail.htm
  • Facebox - This is a fairly popular viewer derived from the popup viewer used on the Facebook website. Still fairly lightweight but slightly more configurable than thumbnail viewer. Website is at http://famspam.com/facebox
  • Lightbox - A very popular and versatile viewer, although more complex to customize. More information at http://www.huddletogether.com/projects/lightbox2/
  • Thickbox - Originally meant as a demo of the popular jQuery.js library of functions, this has grown in popularity because of its relative ease of use, versatility and small footprint. Popup galleries are supported by Thickbox. See more info at http://jquery.com/demo/thickbox/
  • Zoom - Inside Image - This option allows the user to hover the cursor over the selected (enlarged) image and display a zoomed area over the image which follows the path of the cursor for as long as it stays within its bounds. The effect is similar to using a magnifying glass on top of the image.
  • Zoom - Outside Image - This option also lets the user magnify whichever section of the selected image the cursor hovers over, but the zoomed section will not be displayed on top of the image but instead in a separate popup window to the right of the selected image.
  • ColorBox - ColorBox is a light-weight, customizable lightbox plugin which uses the popular jQuery Javascript library. Available on an MIT license, more information available here: http://colorpowered.com/colorbox/. Popup galleries are supported by ColorBox.
  • GreyBox - This is a very lightweight popup script that doesn't conflict with popup blockers and is styled via CSS. More information at http://orangoo.com/labs/GreyBox/. Popup galleries are supported by GreyBox.
  • LightWindow - LightWindow v2.0 is a versatile popup generator allowing separate galleries per picture set. More information is available here: http://www.p51labs.com/lightwindow/. Popup galleries are supported by LightWindow.
  • Fancybox - Fancybox (v1.3.1) displays images in a Mac-style lightbox. Released on an MIT license and further information is available here: http://fancybox.net/. Popup galleries are supported by Fancybox.
  • Slimbox - Slimbox 2.04 was designed to be very small (4Kb), efficient, standards-friendly, fully customizable. It uses the jQuery Javascript library and is made available via the MIT license. More information is available here: http://www.digitalia.be/software/slimbox2. Popup galleries are supported by Slimbox.

NB - the zoom tools are powered by MojoZoom and Mojo Magnify and are made available here under the terms of the MPL license. Customizations can be made by adjusting code in the '/includes/popups/zooms' directory of this distribution. For further information on customizations to their presentation within your web pages, please refer to the creators' website here: http://www.nihilogic.dk/


Linked Attribute Pictures


Linked Attribute Pictures (LAPs) add an extra dimension to your customers' buying experience by allowing them to see pictures representing combinations of options from different option groups they have selected via PAPs. Follow these steps to set up your linked attribute pictures.
  • Firstly, make sure you have either set up all attribute/option groups that you want to link together in your admin component's attribute/option handling section, or checked the 'Create Native Attribute' checkbox when uploading the attribute images.
  • Then scroll down to the upload section in PAPs admin and select from the 'Existing native attribute:' dropdown. You will see the file upload section with the value (name) of each attribute picture filled in. Upload images depicting the individual attributes (uploading the linked pictures comes later). Repeat this process for the other attribute groups you want to link together.
  • You will now see lists of the attribute groups in PAPs admin. Set 'Use Composite Images:' to 'Yes' and save.
  • Scroll down and you will now see the Composite Pictures Upload area. Ensure that the 'Linked Images' radio button is checked. This section contains all the possible combinations which can be made between the various options from each group. You don't need to upload every single image file in one go. You will have the chance to upload any files you leave out at this stage later on.
  • Make sure you have adjusted the relevent settings as outlined here.

WARNING - Try to limit the size of your linked attribute groups. The number of possible combinations rises exponentially with each added attribute value.
WARNING - Uploading large numbers of files in one go may result in your browser hanging if the MAX_UPLOAD_SIZE setting in your server's php.ini file is too low. If this happens, try uploading a small number of files first. You can then upload further files to add to those already uploaded.
When the product page loads, the user will click on a thumbnail and the system will assess what current combination of attributes has been selected. The current selection is always the combination of the last attribute pictures clicked in each attribute group. If a particular combination does not have an associated LAP, the main enlarged picture will not change so you need to make sure you have uploaded linked images for all of the possible attribute combinations.

When the 'Add To Cart' button is clicked, each one of the attribute selections which make up the current combination will be added to the cart.

Merged Attribute Pictures


Merged Attribute Pictures (MAPs) are an alternative type of composite image which - like LAPs - allow you to display as the selected image a separate image in response to the currently selected combination of two or more options from different option sets. However, the image displayed using MAPs is not a separately-uploaded image as it is with LAPs, but instead is an image produced by layering the already-uploaded images for each currently selected option on top of each other. Using this method, no extra images need to be uploaded as the originally uploaded attribute images are the ones that are used to create the merged picture. Before setting up MAPs, please bear in mind the following points:

  • The first attribute picture set that you upload will always be the 'base' or 'bottom-most' image in the stack of image layers processed by PAPs. It can include .jpg, .png or .gif files.
  • The second - and any other subsequent - attribute picture sets uploaded will be layered (superimposed) on top of the base layer in the order they have been uploaded in. This means that they must be transparent images in order to not totally cover up the base layer and any other layers beneath them. It is IMPORTANT therefore to use only transparent .gif or .png images, and NOT .jpg's for any layer other than the base layer.
  • For best results, the images used for all attribute sets (ie in this sense, layers) should all be the same size.

MAPs can be set up as follows:
  • Firstly, make sure you have either set up all attribute groups that you want to link together in your admin component's attribute/option handling section, or checked the 'Create Native Attribute' checkbox when uploading the attribute images.
  • Then scroll down to the upload section in PAPs admin and select from the 'Existing native attribute:' dropdown. You will see the file upload section with the value (name) of each attribute picture filled in. Upload images depicting the individual attributes (uploading the linked pictures comes later). Repeat this process for the other attribute groups you want to link together.
  • You will now see lists of the attribute groups in PAPs admin. Set 'Use Composite Images:' to 'Yes' and save.
  • Scroll down and you will now see the Composite Pictures Upload area. Select the combination of option groups (attribute groups) you want to merge images for, then click the 'Continue' icon.
  • You should now see the list of all possible option combinations. Do not upload any files. Instead, click the 'Merged Images' radio button.
  • Merged images for all possible option combinations will now be generated. The attribute combination list should now show 'Auto-merged from attribute images' in the 'filename' column for each combination. You will also be able to preview the newly created merged images for any combination.

Setup of MAPs is complete. You should now test the results in your product page.


Swatch Attribute Pictures


Swatch images are pictures which represent a product attribute, but when the swatch image is clicked the enlarged picture portrays a different image, usually one which shows the attribute being applied to the product itself. A common example is the color attribute for t-shirts. The swatch images are simply blocks of pure color, and when clicked the enlarged picture shows a t-shirt of that color.
SAPs can be set up as follows:
  • Firstly, make sure you have already set up the attribute and attribute options in the native attributes setup section of your shopping cart's admin component.
  • In the upload section, click on the 'Create swatch' checkbox and select the existing native attribute name to which you'd like to apply the swatches from the dropdown directly below.
  • For each attribute option, you will be required to upload two files - the 'Swatch File' (which will be the thumbnail) and the Enlarged File (which is the enlarged image).
  • You can choose to watermark either the swatch image, the enlarged image, or both. Watermarking takes place during upload.
  • Once uploading is complete, you will be able to view both swatch and enlarged images for each option by clicking the 'Swatch' and 'Enlarged' icons for each attribute option in the main attribute listing for the product.
Some points to remember about swatch images:
  • Swatch thumbnails can be used in conjunction with CSS tooltips, and the enlarged images can be used with Javascript Popups and Popup galleries.
  • It is possible to mix swatch and non-swatch attributes for the same product.

Settings Profiles


The first time you upload pictures for a product via PAPs, the settings in the 'Product Settings' section of the PAPs admin panel are configured according to default values determined by the SQL script which was run during the installation of PAPs. These settings then need to be changed to suit the individual display requirements for each product page.

Settings Profiles enable you to save settings configurations so that you can use them again and again with multiple products without having to configure each setting individually every time you create PAPs for a new product.

Initially, the default settings profile is 'No Profile'. Once you have configured your settings in a way which you would like to use with other products in future, enter a profile name in the 'Save As Profile' text box and hit the 'Enter' or 'Return' key. The current configuration will now be saved and its name will be available for selection in the 'Change To Profile' dropdown box. When you subsequently upload images for a different product, you will be able to select the pre-saved profile and all settings in the 'Product Settings' section will be changed to the saved configuration.

If after selecting a settings profile you then change any of the settings in the 'Product Settings' section, the current profile name will revert to 'No Profile' as the current configuration will no longer be the same as the saved one. You can then save the altered configuration under a different profile name if you want to use it with other products.

NB - It is not a requirement to associate PAPs-enabled products with a settings profile. Settings profiles are simply a convenient way to configure the same settings across multiple products.

Troubleshooting

Q) I have completed installation, but I'm getting errors relating to Ioncube.
A) Ioncube is required to decode encoded PAPs files. For articles on how to get it working correctly on your site, see the Ioncube Installation Articles on the PAPs website.

Q) I have completed installation, but when I click on 'Attribute Pictures' in the Admin menu, I get an 'Access Denied' message.
A) If you have Administrator rights to the Admin component, then go to System->Users->User Groups. Then select your user group and then check the checkboxes corresponding to 'catalog/paps' in both the 'Access Permission' and 'Modify Permission' lists.

Q) My images are being displayed smaller than required even though I have set the image widths in the control panel.
A) You should create your images at least as large as the size required for the enlarged (selected) picture before uploading them. If you intend to use Javascript popups, the uploaded images should be larger than the intended size of the enlarged (selected) images.

Q) My product info page has been completely rearranged and has lost its original structure.
A) You should first try changing the 'Thumbnails Position' setting in PAPs admin to a position which better suits your page layout. If this doesn't fix the problem, you could try moving this line:

<?php include_once('catalog/view/paps/includes/modules/paps.php'); ?>

In this file: catalog/view/theme/YOUR_TEMPLATE_NAME/template/checkout/cart.tpl

to another location in the same file. Be sure to place it within 'table' tags wherever possible.

Q) I'm getting an error similar to: 1146 - Table [TABLE_NAME] doesn't exist.
A) Please ensure that you have NOT added any database tablename prefixes to the PAPs database table names.

Q) I have added content to a tooltip, but now when I click the Tooltip icon in the PAPs admin area the textarea does not display.
A) This can happen if you have used double quotes in your tooltip content. To fix it you will need to access your database and look through the table called 'paps_tips_txt' for the 'tip_txt' column, then find the row associated with your attribute and eliminate the offending double quotes from the data. Refresh your PAPs admin page, then try to edit the tooltip content again.

Further Support

Please remember to send us your versions of PHP, MySQL and OpenCart when sending a support query.

Product Attribute Pictures Website http://www.product-attribute-pictures.com
Support & Discussion Forum http://www.product-attribute-pictures.com/index.php/component/option,com_ccboard/Itemid,30/view,forumlist/
Support Email it@product-attribute-pictures.com
Other Enquiries http://www.product-attribute-pictures.com/index.php/component/option,com_chronocontact/Itemid,60/

Appendix


Admin Section Icons
Some icons in the PAPs admin panel have two states. When greyed-out they cannot be activated, and when they are colored they can be clicked. Here is a rundown of all icons:
Icon Name Behaviour
Back Always activated. Go back to previous page
Delete Non-clickable column heading
Help Activate by hovering over
View Always activated. View popup of a PAPs image
Tooltip Always activated. Click to edit tooltip content
Save Activate by changing a setting in the same section
Continue Activate by selecting required settings
Upload Activate by selecting files for upload

Toggling Admin Display Elements
After you upload your first set of attribute/option images, you will see a box stuck to the right side of the screen entitled 'Toggle Display Elements'. By clicking the checkboxes within this box, you can show or hide any of the main boxes containing inofrmation about your images. Sometimes the screen can become congested if you are using several option sets or if your product names are very long. Toggling display elements makes it easier to focus on just the settings you want to deal with.

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