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

This document is copyrighted © 2012-2021 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.

Introduction

Product Builder is used to offer the end user the ability to create a custom product, 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 a 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.

Use the Minimum allowed quantity and the Maximum allowed quantity if you want your kit to include a specific number of items. e.g. A wines box which can include 10-12 bottles.

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

In the right tab 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 if it's not editable.

To create a group go to the "Group" view and press the “New” button.  Follows an explanation of the fields found in the group's form.

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.

Mandatory: In a mandatory group, the user is forced to select a product, otherwise he/she cannot proceed to the cart.

Searchable: A searchable group, displays a search input field at the top of the group. This is used to search individual products of that group, if it has a lot of products.
The used search engine is quite advanced and is the same used by our Custom Filters extension. It can search products using several fields like product name, meta-data, categories, custom fields, etc.
The search engine can be configured from the component's configuration.

Connect With: An editable group can get its products either from one or more Virtuemart Product Categories or from a custom collection 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.

Products Display Type: How the products of the group will be displayed. If set to "Use Global" will follow the settings in the component's configuration or in the menu items.

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 non mandatory feature.  It is usefull only if there are dependencies between the products of the different groups .
Product Builder is using Tags to create compatibility relations between 2 or more products. Hence the products that have at least 1 common tag between them, are considered compatible.

How is working in the front-end

'Compatibility Check'  works from top to bottom. That means that when a product from the 2nd group is selected, PB will check for compatible products in the following groups (the 3rd ,the 4th etc.). The products which are not compatible with a selected product will be either disabled or hidden (depending on the settings for the incompatible products).
Lets have an example.
In the following Image we a PC builder. 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.
More complex compatibility examples can be found in our Knowledge Base

2 or more groups should have at least 2 common tags between them, in order the compatibility to work

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.

Products Search

With these settings you are configuring the search engine used inside your groups (if it is configured to do so).

1. Word Matching
   Exact: The search engine is looking exactly for the input query but still analyzes it, if it contains category names , manufacturers or custom field values. Do note: This is faster than "Any".
   Any: The search engine is looking for the input query but also for variations of it. E.g. The words in different order. Of course analyzes the query.
2. Search Into Fields
   The fields where the search will search. Do note: The more the fields,  the slower the search process.
   Searching into the product short description and especially into the product description could affect the search performance in a bad way. These are the biggest fields of the product's table and also indexing cannot be use. So searching there costs.