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. |
|||||||||||||||||||||||||||||||||
|
|
|||||||||||||||||||||||||||||||||
|
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:
|
|||||||||||||||||||||||||||||||||
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
| |||||||||||||||||||||||||||||||||
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.
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:
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:
|
|||||||||||||||||||||||||||||||||
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:
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 CopyingIf 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 TooltipsTo 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
Tooltip Heading
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 ViewersYou 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:
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 PicturesLinked 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.
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 PicturesMerged 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:
MAPs can be set up as follows:
Setup of MAPs is complete. You should now test the results in your product page. |
|||||||||||||||||||||||||||||||||
Swatch Attribute PicturesSwatch 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:
|
|||||||||||||||||||||||||||||||||
Settings ProfilesThe 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 |
|||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||
Further SupportPlease remember to send us your versions of PHP, MySQL and OpenCart when sending a support query. |
|||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||
Appendix |
|||||||||||||||||||||||||||||||||
Admin Section Icons
|
|||||||||||||||||||||||||||||||||
Toggling Admin Display Elements
|
|||||||||||||||||||||||||||||||||
COPYRIGHT (c) 2011 OPEN SOURCE SERVICES. ALL RIGHTS RESERVED.
|