This document offers the basic knowledge for installing , configuring and using the Product Builder component.

This document is copyrighted © 2012 Sakis Terzis / breakdesigns.net. and is licensed under the terms of Creative Commons Attribution-NoDerivs 3.0 Unported (CC BY-ND 3.0) License [http://creativecommons.org/licenses/by-nd/3.0/].

You can distribute it freely as long as you do not modify it and state its source and/or author. You can use this document or any portion of it for commercial purposes too.

Notice — For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to the author's web page.

If you require further permissions, for example to do changes to the current document and disctribute it to your clients, please email the author in order to acquire such a license and the source to this document.

Installation

After downloading the package from our site, just install it using the joomla installation process.

Update to the latest version

To update your version just download the latest version of the component and reinstall it without uninstalling your current version. The upgrade will be done smoothly.
After the update we recommend to visit the Product Builder's settings to check if there is any new setting.

Introduction

Product Builder is used to offer to the end user the ability to create his custom product (configuration) selecting products from predefined product groups.

So in order to work we have to create a set of Custom Products and Groups.

Create a Custom Product

After the installation go to the "Custom Products" view and press "New" to create a new one.
In the form you have to fill in the fields of that Custom Product. Some of them will be displayed in the front-end and some regard functionality issues.

Even if a Custom Product has an image and Description we can set them not to be displayed in the front-end. So these fields can be used for internal use too.

If you intent to use the 'compatibility check' in your products the 'Compatibility' should be set to yes.

A notable field here is the “Language”. Product Builder support's the joomla's multi-language feature. So if you are using more than one language in your e-shop you can create multiple instances of a custom product for the different languages you have.

In the right side of the page there are the Metadata Options. These options are used for generating meta-data tags in the front-end, that can be used by the search-engines.

Create a Group

A group can consists of multiple products or a single product in case we don't want the user to change it.
To create a group go to the "Group" view and press the “New” button.

Basic

Name: The name of the group will be either the group's header or the 1st option in the products list.
Custom Product: is the “Custom Product” in which this group belongs.
Language: In case of multiple languages you can have groups for different languages.

Group Options

Here there are the more advanced options of the group.

Editable: An editable group consists of multiple products while the non-editable has only one product which cannot changed by the user.
If you set a group as non-editable you have to select a Default Product too.

If you set a group as non-editable you have to select a Default Product too.

Connect With: An editable group can get its products either connecting it with one or more Virtuemart Product Categories or connecting it with a custom selection of Virtuemart products.

Default Product: A group can have a preselected product. This can be used like a suggestion to the user. In case of non-editable group every virtuemart product can become default. For editable groups only a product of that group can be set as default.

Quantity Options

The Quantity options can be used to set a default quantity for a group or to configure how the quantity will be displayed.

Default Quantity: The quantity of the group by default.

Display Quantity Box : Display or not the quantity box. If the quantity box is not displayed, the default quantity cannot changed by the user.

Quantity Box : This regards the display type of the quantity box.
It can be a single input with the 'plus' and 'minus' buttons or it can be a drop-down list with predefined options. The drop-down list is useful for products which sold in packs. e.g. 6 items pack or a dozen.

Intoduction

Compatibility is a feature which is not mandatory to use it. If you don't need to use it avoid this step. It is used in order the user to be able to select only products that are compatible between them. Product Builder is using Tags to create compatibility relations between 2 or more products. So the products that have at least 1 same tag between them are considered compatible.

How is working in the front-end

'Compatibility check'  works from the top to the bottom.That means that when a product from the 2nd group is selected pb will check for compatible products in the groups that following that, the 3rd ,the 4th etc groups. Products that are not compatible with a selected product will be disabled (cannot be selected) but will be visible. Lets have an example.
In the following Image we can see the groups of a Custom Product and the tags assigned to our products. Now lets say that the user selects the 1st available motherboard named ASUS M2N68-AM.

PB gets the tags of the products of the current group and disables the products of the following groups that have those tags assigned, leaving enabled only those that have the same tag as the selected product.
In our example the tags of the group 'Motherboards' are AMD and intel. PB gets those 2 tags, then excludes the tags of the selected product (AMD) ,what left are the tags of the products that should be disabled, in our case the products with the tag intel.

Products with no tags assigned are considered compatible with every selection

To use Compatibility Check, the 'Compatibility'  should be enabled in that 'Custom Product's page, in the backend.

You can also let the user decide if he wants to use it, setting the "Display Compatibility" Option to yes from the pb settings and/or the menu item. Even in this case the "Compatibility" field of the used Custom Product should be enabled, to have this functionality working.

How is working in the Backend

If you intent to use compatibility, first you have to create your tags. Then go to the compatibility page and set tags to your products.
The best way to assign tags to your products is to use the Groups filter, starting from the 1st group and continuing down the last.

So first select the desired group and then press the edit button positioned at the right of your products. From the popup window , select the tags you want to assign to that product and press update. Thats it! your product now has some tags assigned.

PB comes with a series of settings which concern functionality, display and styling aspects. To configure it , go to the Dashboard and press the "Settings" icon.Most of those settings have a tooltip. So reading that tooltip is giving enough information.

Front-end Options

The "Ajax Price update on Quantity update " setting is calling AJAX requests when the user changes the quantity. Enable this setting ONLY if you are using prices for quantity ranges (Currently this feature is offered only by commercial plugins).

Almost all of those settings exist in the menu items used to display the 'Custom Products' in the front-end. The settings of the menu items are overwriting those settings. Despite that it is good to set those properly because possibly some 'Custom Products' will not genereted by menu items but will be called by the "Custom Products Browse Page".

Styling

Using the styling settings you can style the front-end layouts. The stlyling tab is offering a series of settings that concerns the design of almost any element displayed in the fron-end. The styling can be done easily using Color Palettes and Slider tools.

After ceating the Custom Products and their Groups its time to create the appropriate menu items to display the product builder layouts to the Front-end.
Product Builder comes with 7 different layouts. Each menu item type represents a different layout.
There are 6 layouts for displaying and customizing a custom product and one for displaying a list with the exitsing custom products (Custom Products Browse Page).

Some info about the layouts.
1. Default : It displays information (Image,Short Description, Manufacturer) about a selected product of a group after the user selects a product.

2. Static Images to the Right : After every selection in a group it displays the image of the selected product at the right of each group.

3. Static Images at the Top : It displays the images of all the selected products at the top of the layout.

4. Image Overlay : The images of the selected products are overlaid one above the other. This way you can use transparent png images to generate the final image of a product which consists of layers. e.g. A t-shirt that consists of the t-shirt and the stamp.

5. Minimal : It just displays the product groups without displaying more info about a selected product in a group.

6. Non-editable : This layout displays only groups that have default products assigned. The user cannot change the default product of the groups. It is usefull for displaying product bundles that can be purchased with one click.

7. Custom Products Browse Page : Displays a list of the existing Custom Products. You can set it to display all or specific Custom Products.

Menu Items Settings

The menu items come with a series of settings. The menu items settings are overwriting the settings of the Product Builder component. Lets see some of those settings.

Required Settings

Here you have to select the Custom Product you intent to display in that layout. This setting is mandatory so you have to select a Custom Product from the list.

Basic Options

Consists of some options that concern this layout. Every type of layout has different features, so you have to set which of those features and how you want to use them.

Component Options

Here there are some of those settings that exist also in the Product Builder Component's settings. As these settings are overwriting the component's settings you have to check them carefully. They regard some important issues such as the price display, the compatibility button display the group display type and others.

• The Virtuemart Products should have prices to be displayed inside the PB groups. A price can be zero (0) or negative but not null (blank).
• A product should be published.
• When there is not even one product that can be displayed in a group, that group won't be displayed in the front-end.
• Only Custom Fields which are set as "Cart Attribute" are being loaded by Product Builder.
• Product Builder follows the settings you have in Virtuemart for the out-of-stock products.
• If the Virtuemart shop is set to be used as catalogue, the cart button/functionality won't be displayed.
• In the dashboard of Product Builder (right side) you are able to see if your version is updated. If not "Download" and "Changelog" information will be displayed.