K2mart

The following documentation applies to K2mart version 2.0 (released March 29th, 2012) and later.

DOWNLOADING

Login to your Member Dashboard and grab the latest release from your "My Subscriptions" page. An active membership is required.

REQUIREMENTS

  • Joomla! 2.5.x latest stable version is highly recommended. K2mart should also work with no problems under Joomla! 1.7 but since this is not a LTS version it is not officially supported. If you are under Joomla! 1.7, you are highly encouraged to upgrade to Joomla! 2.5. K2mart v.2.x will NOT work with Joomla! 1.5.
  • K2 v2.6.3 or later.
  • Virtuemart v2.0.16 or later is highly recommended. K2mart was tested with Virtuemart 2.0.16 and it should work with no problems with next versions of Virtuemart in the same 2.x.x series. K2mart is designed to work with the Virtuemart cart module (mod_virtuemart_cart), so it is recommened that you also enable this module on product pages. K2mart makes sure that when a user clicks on a product in that cart module, the user is properly redirected to the related K2 product page. K2mart v.2.x will NOT work with Virtuemart 1.x.

INSTALLATION & UPDATING

After you download the zip file, use the Joomla! installer by navigating to Extensions->Extension Manager->Install/Uninstall and then choose to upload the zip file.

If you are updating from an older version of K2mart in the 2.x series, do not uninstall the old version. Simply head over to Extensions >> Install/Uninstall and choose to upload the new file. All K2mart files will now be updated maintaining your settings.

UPGRADE

Upgrading from K2mart 1.x to K2mart 2.x is NOT supported. K2mart is based on two other extensions K2 and Virtuemart. Upgrading K2mart means that you should also upgrade them. Although K2 can be upgraded using the jUpgrade extension, there is no easy way to upgrade Virtuemart from version 1.x to version 2.x.

POST INSTALLATION CHECKS

After installing K2mart, in order to ensure that everything is fine, you should check that K2mart plugins are installed and enabled. K2mart comes with one system and one k2 plugin. Both of them should be enabled.

SETUP

After installing K2mart you have to select a K2 category as your catalog root through K2mart system settings. This is a required step in order to tell K2mart what’s the category that’s holding your catalog and your products. You can read more on this below on the settings section of this document.

HOW DOES IT WORK?

K2mart is a powerful extension adding cart functionality to K2 items using Virtuemart, the most popular e-commerce solution for Joomla!.

K2mart integrates most of Virtuemart's product features to K2 items by mapping and syncronizing Virtuemart products with K2 items. This way each K2 item inherits all of Virtuemart's product properties, including manufacturer, vendor, price, discounts, tax rates, currencies, stock, custom fields, dimensions and so on. Every time you save an item through K2, K2mart sends the product information to Virtuemart and keeps a reference between the product and the K2 item. When rendering K2 on the frontend, K2mart attaches the information from Virtuemart to the corresponding K2 item in the form of a block with product information and the required "add to cart" button.

This block output by K2mart comes in four bundled templates with three different layout files (for the K2 item view, K2 item listing view and K2 items fetched within K2 modules) and configuration parameters for each of them to make theming much more easier. These theming options are set into the "Settings" page within K2mart.

K2mart consists of an admin only component, two plugins and an admin module. For greater simplicity all the parameters of the extension can be found on the component along with the migrator. Read on for a complete explanation of each parameter found in K2mart.

WHAT'S SYNCED

In this version, K2mart apart from using Virtuemart’s database tables to store the additional product data, is also performing a sync of some basic fields. The reason for this is to allow basic integration with some Virtuemart modules. The fields that are synced are the following:

K2 item field Virtuemart product field
Title Product Name
Published Published
Featured On Featured
Introtext Short Description
Fulltext Product Description
Image Product Image
Note that the syncing of those fields is one-way only. This means that if you edit any of the above fields through K2 then the Virtuemart fields will also be updated, but if you edit the product through Virtuemart, K2 fields will remain unchanged.

CREATING PRODUCTS

Once K2mart is installed and setup you can begin adding products. The process is exactly the same as creating a K2 item. The only difference is that you have to fill in some extra information regarding the product. In order to do this use the form provided by K2mart. The fields that are required is the SKU and the price. Once you complete them and hit save you have created your first product.

USING THE MIGRATOR

If you have already set up your online shop with Virtuemart and you want to import your products to K2 you can use the K2mart migrator. K2mart migrator will build the corresponding K2 categories for your catalog based on Virtuemart category structure. It will also create a K2 item for every Virtuemart product it finds. Note that if migrator finds a Virtuemart product that is already assigned to a K2 item (has already been imported in the past), this product will be skipped. Also note that Virtuemart's multiple categorization is NOT supported. When the migrator finds a Virtuemart product that belongs to more than one Virtuemart categories it will map the generated K2 item to the corresponding K2 category with the deepest level among them. K2mart migrator will also create tags for Virtuemart categories and will tag each new generated item with them. K2mart migrator comes with three quick settings to customize the migration. These are:

 

K2mart 2 migrator settings
 

K2mart migrator settings


- Catalog root category: All imported categories from Virtuemart will be placed under this category and they will inherit it's settings. Select one of the existing K2 categories or type a category name and let K2mart create this category for you using the default category settings. It is highly recommend that you first create a K2 category through K2, set the desired settings for this category and then use the migrator to import products to K2mart under this category (selecting this category from the list as the catalog root category). This will save you from a lot of work later, especially if you have a lot of products and categories.


- Ignore unpublished Virtuemart products and categories: If you check this the migrator will not import Virtuemart unpublished products and categories. This may be useful if you have a lot of unpublished products or categories in Virtuemart and you do not wish to import them.


- Process product images: Uncheck this if you want the migrator to not import the product images into the K2 items. This may also help if you face performance issues but it will lead to products without images.

Regarding the migration process you should note that:

- It may take a lot of time, depending on the Virtuemart products you have already and the setting about image processing. In any case do not interrupt the operation once you started it. Just wait to complete.

- K2mart migrator should normally be used one time. After the migration each new created product through K2 will auto saved to Virtuemart. If you run the migrator again you may produce uneeded duplicated K2 items and categories.

- The migration process requires that your system is NOT running PHP in safe mode. Otherwise it is very possible that you will get a max execution time error from PHP when you try to use the migrator.

- The K2mart migrator may require a lot of resources especially if you have a lot of products and you also want to process their images. PHP memory limit to 64M or greater is recommended if you want the migrator to also import the product images from Virtuemart to K2. This is an average value. Depending on your current number of products a greater value than this may be needed.

MANAGING PRODUCTS

In this version of K2mart product managing is more easy and simple. While you are viewing the K2 items administration list try to filter the items by category using the corresponding filter provided by K2. If you choose one category that’s inside your catalog ( your catalog is defined by the “Catalog root category ” setting ) then K2mart will enhance K2 items list with some extra columns and filters. The columns that will be added are the following:
  • Price
  • SKU
  • Manufacturer

K2 items list can be sorted using these columns. Additionally K2mart will add two extra filters. These are:
  • Manufacturer filter. Allows to filter K2 items based on the manufacturer.
  • Relation filter. Allows to filter K2 items to children and parents.

Those enhancements combined with K2 can give you a powerful managing interface for your shop. Operations like publish/unpublish , flag as featured are also applied to Virtuemart database. Finally, note that when you delete an Item through K2 all its mapped information is also deleted. This means that if a K2 item which is assigned to a Virtuemart product is deleted, the product is also deleted from the Virtuemart database. Note that those operations are applied to Virtuemart only when the K2 item being edited is under the K2mart catalog root category.

 

K2mart 2 products management
 

 

SETTINGS

The parameters are divided into the following areas:
- Layout/view settings. These settings control which elements (data from Virtuemart) are shown or hidden in the product info block that is output on K2 items. Each view has it's own settings: one for the K2 item view, one for the K2 item listings and one for K2 items displayed through K2 modules like mod_k2_content.
- System settings. These settings control global K2mart behaviour.
- Permissions. Provides basic integration with Joomla! 2.5 permissions system. You can set the user groups which can configure or access administration interface.

Let's examine all the settings in detail:

K2mart 2 layout settingsK2mart layout settings

Layout settings include the following group of parameters

- Product name: This controls if the product name should be shown in the product info block. In most cases you need to set this to "Hide" as the K2 item title ( already displayed before the product info block ) will be the same.

- Product SKU: Show or hide the product SKU.

- Product URL: Show or hide the product URL.

- Product vendor: Show or hide the product vendor.

- Product manufacturer: Show or hide the product manufacturer ( along with a link opening a modal with manufacturer info ).

- Product price (If applicable): Show or hide the product price. Almost always you want to set this to "Show". Note that this requires that the product does have a price and that Virtuemart is also configured to show prices ( "Show prices" setting found under Virtuemart's configuration).

- Product packaging: Show or hide product packaging information.

- Product box info: Show or hide product boxing information.

- Product dimensions: Show or hide product dimensions.

- Product weight: Show or hide product weight.

- Product availability (If applicable): Show or hide product availability.

- Product shipping info: Show or hide product shipping info.

- Product rating : Show or hide product rating. Note that this requires that rating must be enabled through Virtuemart’s configuration.

- Product reviews (only for item view) : Show or hide product reviews. Note that this requires that reviews must be enabled through Virtuemart’s configuration.

- Product fields: Show or hide product fields. This refers to Virtuemart custom fields.

- Add to cart button (If applicable): Show or hide add to cart button. Note that this requires that Virtuemart is not configured to be used as a catalog only. You can find this under Virtuemart's configuration ("Use only as catalogue" setting).

- Cart product fields (only if add to cart button is enabled) : Show or hide cart product fields. This refers to Virtuemart’s custom fields that affect the product price.

- Quantity box (Only if add to cart button is enabled): Show or hide the quantity box for the add to cart form. This also requires that "Add to cart button" is set to "Show". If you set this to "Hide" the user will not be able to select the quantity of the product to add to the cart and the quantity will always be 1.

- 'Ask question' button: Show or hide the ‘Ask question’ link.

- Disable this layout: Set this to Yes if you want to globally disable K2mart for the specific view.

Note that the layout settings are identical on each of the first 3 tabs in "Settings". You obviously set them differently to reflect how you want your K2 catalog/shop to look like in the frontend.

K2mart 2 system settingsK2mart system settings

System settings include the following group of parameters

- Catalog root category: Select the K2 category you want to redirect the user when they request Virtuemart's default page (called shop.browse or shop.index). Usually you will need to set this to your root category, meaning the category which contains all of your K2 items/products in your catalog.

- Template: Select which template will be used in K2mart rendering in the front-end. Templates are located in /plugins/k2/k2mart/tmpl/site directory. Overrides of the templates need to be placed under /templates/YOUR_JOOMLA_TEMPLATE/html/k2mart directory. Note that in order to create a new template it is not necessary to place it under /plugins/k2/k2mart/tmpl/site directory. You can place it directly under /templates/YOUR_JOOMLA_TEMPLATE/html/k2mart directory and K2mart will detect it.

- Cart only for registered users: Set this to yes if you want to hide the add to cart button for non-registered users.

- Show categories filter: Choose whether you want to display the category filter in front-end. This will allow the user to filter the products based on one or more categories.

- Show manufacturers filter: Choose whether you want to display the manufacturer filter in front-end. This will allow the user to filter the products based on one or more manufacturers.

- Show sorting filter: Choose whether you want to display the sorting filter in front-end. This will allow the user to sort the products by some common used criteria. NOTE: Virtuemart 2.0.2 removed the code that was counting the product sales. This means that the product sales sorting provided by K2mart won't be accurate until Virtuemart restores this issue.


- Enable AJAX: Choose wheter you want to enable AJAX functionality for the K2mart filters and the pagination in front-end.

- Show Virtuemart categories list on K2mart form. Setting this to "Yes" will provide K2mart product form with a select list of Virtuemart product categories. This way, when user creates a new product can also select the Virtuemart product categories that the product will be assigned. Note that this does not affect K2 categorization. This is added just for data manipulation. Advanced users can use this to apply batch operations to some products ( tax rate for specific Virtuemart categories for example).

- Show 'Advanced' tab on K2mart form. Setting this to "Yes" will display an extra tab in K2mart product form providing some advanced operations. Through this tab user can assign/unassign an existing Virtuemart product to a K2 item. Other operations provided by the advanced tab are a link for editing the product in Virtuemart and an option to completely remove the product from Virtuemart.

MVC TEMPLATING: THE POWER TO CUSTOMIZE YOUR LAYOUT

You can use HTML and CSS template overrides inside your Joomla! template and completely change the way K2mart elements display on your website! So you can either choose to use the versatile base styling of the bundled K2mart templates or simply override them (both the HTML and CSS code) by copying the K2mart plugin's /tmpl/site/TEMPLATE folder within your Joomla! template's /html folder. Each K2mart template uses 4 layout files (item listings, item view, item in module and filters) and one CSS file. Of course you are able to override all files or selected files, as you would with any other MVC component or module, with the better exception that K2mart overrides CSS files as well!

In order to override the built in templates you can simple copy /plugins/k2/k2mart/tmpl/site/TEMPLATE folder within your Joomla! template's /templates/YOUR_JOOMLA_TEMPLATE/html/k2mart folder, as you would with components and modules. Whatever changes yo do from now on within this folder, will completely override the K2mart output, exactly as you would with any other MVC component or module.

Alternatively you can create your own template by placing your template folder to /templates/YOUR_JOOMLA_TEMPLATE/html/k2mart. There is no need to place your template to the plugin templates directory.

K2mart uses 4 layouts for listing, listing in modules, item pages and filters, with 1 associated CSS file. You are able to override all files or selected files, as you would with any other MVC component or module, with the better exception that K2mart overrides CSS files as well!

Below you can see the file structure of a K2mart template folder inside the plugin:

/item.php
/listing.php
/module.php
/filters.php
/images
|-- (includes images used in the .php or .css files)
/css
|-- style.css


If you maintain this structure within /templates/YOUR_JOOMLA_TEMPLATE/html/k2mart/TEMPLATE you can override the entire plugin output!

FETCHING PRODUCT INFORMATION INTO K2 LAYOUTS

Some of the product information that is available in K2mart layouts is now also available in K2 layouts to support more complex designs. In order to retrieve a K2mart variable when you are in the context of a K2 layout you can request the variable on the item object. For example if you want to fetch the product SKU inside the K2 item.php layout you can use the following code:
<?php echo $this->item->product->sku; ?> 
You can do the same for the most of the variables that are available in K2mart layouts. Note that in the example above $this->item variable is used. Depending on the context $item may be the item object.