Review of an import system of JBZoo 2.x

9.5/10 rating (2 votes)

Attention! Don't forget to make an actual backup before making any experiments with your website. It greatly saves time, nerves and money.

Starting with JBZoo 2.0, we have our own import/export system that uses CSV format.

In this article we'll examine settings and the process for items only. All this information is relevant for categories too. But before we start, you should know some important things.

  • Import works only with UTF-8 encoding (preferably without BOM). It's not a whim of JBZoo developers because Joomla websites always work with this encoding.
  • Not all desktop applications work well with UTF-8. For example, often there are problems with MS Excel. We recommend to use OpenOffice (LibreOffice) for editing. It is great free alternative.
  • There is no need to re-index your website after the loading process is finished. It is done automatically in the background.
  • The import speed greatly depends on the amount of data, field types and their quantity, size of your CSV file (and on the quality of your hosting). Maybe it would be better to load your data in parts. There is no recipe for ration of speed and convenience - everything is very individual.

How to edit CSV file locally?

You can see an example with default options for LibreOffice on this screenshot. All other programs have similar options. Pay attention to outlined options.

Opening csv file

JBZoo import configuration

You can easily find import button in the tools section.

JBZoo control panelChoose what to import

Import options - step #1

On the first step we set parameters only for CSV file recognition.

Step 1. CSV file parameters

  1. Choose CSV file (not an archive, only a text *.csv file).
  2. Specify if there is a header. Usually it is present as a utility information.
  3. A separator is a symbol which separates data of one table cell from another. It is a comma by default.
  4. An enclosure is a symbol which wraps data within one cell. It is double-quotes by default.

CSV formattingFormatting looks like this in the file. Red is a separator. Blue is an enclosure. Each row is a different entry.

Usually, these settings shouldn't be changed. You only have to load a file and continue to the next step.

Import options - step #2

On the second step you should specify the correspondence between the CSF file columns and item fields. You will see a list of columns from your CSV on the left and item fields of a specific item type on the right (after you choose an item type).

Some very important options are listed at the top.

Step 2. Import settings

  1. Application (Catalogue) into which import will be made.
  2. Item type. A set of fields of the sixth point depends on it.
  3. Import key. It is a field that will be used to connect CSV rows with website data.
    • ID (number) is a unique identifier (sequence number) that was generated within your website.
    • Name - searches for an exact match of item or category name.
    • Alias is a unique text key. Usually it is an item name written in Latin characters in lowercase without special symbols.
    • SKU is a value from the special price element - JBPrice Advance (only from this element!).

    It is mandatory to make a relation of CSV fields with an item type using this option. Otherwise, new items will be created because a search for the key would not provide results.

    If an import process will be unable to set relation by key, new item will be created.

  4. Fill the radio etc. When importing data for a strict list, it is important that CSV values would match preconfigured item types. Sometimes it's not convenient. This setting allows you to automatically "extend" the list of options in the specified elements. Thus you'll have less manual work to do and probability to miss something is reduced. Only standard select, checkbox and radio elements are supported, as well as cascade select.
  5. The rows that were not in the file. For the 100% synchronization of your website with an external database it is useful for an import to not only add/edit existing fields, but also to delete/disable the ones which are not in the CSV. This option allows you to do just that.
  6. This is a list of relations between CSV columns and item fields.

Import - step #3

Step 3. Import process start

On the third step an actual import process will start. Do not close this window until you will see a message that everything is completed.

Attention! On the last step, after 100% there will be an additional server request that will either delete or hide items (it depends on import settings from the second step). It could take some time if you have a lot of items. So do not close this window too early.

If you suddenly see an alert message, don't worry. It is an error (not necessary because of import). Just make a screenshot and show it to the tech support. In this case import will stop and it would be better not to restart it until the problem is solved.

Formatting examples of some fields

Almost any type of ZOO or JBZoo element has its own data format. So it can affect the format of data in CSV for the import. In order to be sure, just make an export of an item that you need and use it as an example. Below we'll examine special data types in JBZoo.

Prices

Starting from JBZoo v2.0 it is recommended to use JBPrice Advance element for a price fields. It supports different filling methods.

Let's assume that we want to fill prices in this way:

Prices example

Full format

For the first cell (basic information):

balance:-1;new:0;sku:HO9754;value:14800;currency:EUR;discount:-10;discount_currency:%;description:Item description

For the second cell (price variation):

balance:-1;value:12800;currency:EUR;sku:HO9754;param1:amd

This format is the longest one but it can fully change element values.

As you can see, it is a set of key1:value1;key2:value2.

You don't have to specify all keys - change only what you need. For example, you can skip "currency" value and the import will keep default currency value (as in element settings). Also, if some value is empty, you can skip it.

In our example there is param1 but there are no param2 and param3. Because they can be skipped.

Special symbols such as ":" and ";" are used as delimiters.

If these symbols are used in the description, you should replace them with %col% or %sem% respectively.

Simple format

This format is supported in order to keep the possibility to work with old price element and to make import easier. All missing fields will be filled according to default values (e.g. stock will be infinite) or will betaken from element's settings (e.g. currency).

Variant 1

HO9754|||1|||14800|||Item description - sku, availability flag, price, description.

Variant 2

HO9754|||14800|||Item description - sku, price, description.

Variant 3

14800|||Item description - price, description.

Variant 4

14800 - only price.

Important information regarding prices!

  • In CSV file you should put basic information first. After that variants should be placed (if any).
  • Be careful when you prepare CSV file. If in doubt, make a backup of a database or of the whole website
  • Price works as a multiple field. That's why import file will use several cells for it. This improves convenience of editing.
  • Import of an old JBPrice is supported but only in simplified format.

Category

You can specify that an item belongs to a category by several means.

Example of a full variant

Name 1|||alias-1///Name 2|||alias-2///Name 3|||alias-3

Defines a full path to a category to which this item belongs. Last one will be set as its category. I you need to specify several categories, then category field should be multiple.

Import will search through categories by alias and if it will find nothing, by name. If nothing is found, category will be created.

Example of a shortened variant

Name 1///Name 2///Name 3

It is same as full variant but without aliases.

Example of a simplest variant

Name 1

or

alias-1

This variant specifies only final category, without nesting. If the category exists, its nesting will not change and an item will be attached. Otherwise, category will be created in the application root.

Other formatting examples

Boolean values. Usually they are used for the simplest switches. To turn on and off comments, for example. In order to set a positive value, you can use such values as 1, y, yes, on and any positive numbers. Everything else is treated like no

Date fields. It is recommended to set them in a Y-m-d H:i:s format. 1999-12-31 23:59:59, for example. Any other format which is supported by PHP function strtotime will do as well.

Related item or category. Fields that point to the relation with a different item should contain its alias. It's not possible to make a relation using ID.

Author (user). You can specify either ID of real user or some random word that will be saved as an author name.

Country. For the country element you should specify a two-letter code. US for the USA, for example.

You can find a full list of all countries in this file: /administrator/components/com_zoo/framework/helpers/country.php

Galleries, images, files. There are some elements that can store a path to a file or a folder. You should specify the same path like in the control panel for such elements. Preferably, without unnecessary slashes. Existence of files or folders is not checked during the import.

Cascade select. Each cell should point to one of the variants of a cascade select. Example:

USA|||Phoenix|||Tempe
USA|||Phoenix
USA

Joomla module and Widgetkit. Strict relation to a Joomla module ID or a widget ID.

Useful to know

  • If you don't know how specific field looks in CSV, try to fill it and make an export.
  • Each step of the import processes no more than 25 items. Of course, it could have been more, but such size was chosen in order to be within time and memory limits of most hostings.
Import

Still gotta questions, who can help me?

Visit our special JBZoo tech support forum which is specifically meant for JBZoo so the priority of the response and its promptness are much better there than in any other place. With inactive account with a “Plus” sign in a tariff plan you can ask for support in one of these sections or use any of our contacts.