Перейти к содержимому


Фотография
- - - - -

Review of an import system of JBZoo 2.x

documentation import jbzoo 2.0+

  • Закрытая тема Тема закрыта
В этой теме нет ответов

#1 Kess

Kess

Отправлено 29 September 2013 - 04:50

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.
Main differences from the original system are described in this post.
 
 
 
This is important!

  • In the following examples we'll examine settings and the process for items only. But this information is relevant for categories too. In general, the only difference is the context.
  • Import and export work 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 quantity, size of your CSV file (and on the quality of your hosting). Keep this in mind. 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.
9GG9_200x0.png
 
 
 
Where to find JBZoo import/export?
You can easily find import/export button in the toolbar. Pop-up window will appear on click.
4br_200x0.png
 
 
 
Import options - step #1
On the first step we set parameters only for CSV file recognition.
SaNt_200x0.png

 

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

Formatting looks like this in the file. Red is a separator. Blue is an enclosure. Each row is a different entry.
B4oj_200x0.png
 
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 which columns and into which item fields import should be made.
You will see a list of columns from your CSV on the left and item fields in the right (after you choose an item type).
uC45_200x0.png
 
Some very important options are listed at the top.

 

  • Application (Catalogue) into which import will be made.
  • Item type. Fields set of the sixth point depends on it.
  • 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.
  • 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. This way you'll have less manual work to do and probability to miss something is reduced. Only standard select, checkbox and radio elements are supported.
  • The rows that were not in the file. For a 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.
  • This is a list of relations between CSV columns and item fields.

 
 
Import - step #3
On the third step an actual import process will start.
GcOk_200x0.png
 
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 (starting from 1 minute for 10000 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. Error messages are made like alerts for the ease of viewing error details.
 
 
 
Formatting examples of some fields
Different types of fields of items and  categories have different formatting methods. Below we'll examine special data types in CSV.
 
 
Boolean values (yes, no) - 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 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. Field that point to the relation with a different item should contain its alias. It's not possible to make a relation using ID. 
 
 
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. 
 
 
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

Unfortunately, currently import mechanism is unable to add select options dynamically from CSV. We'll add this ability in the future releases.
 
 
Joomla module and Widgetkit. Strict relation to a Joomla module ID or a widget ID.
 
 
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:
H496_200x0.png
 
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 (without quotes).
 
 
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).
  • Import values completely override price values. Be careful when you prepare CSV file.
  • Price works as a multiple field. That's why import file will use several cells for it. This improves convenience of editing import file.
  • Import of an old JBPrice is supported but only in simplified format.

 
 
Useful advice and other information

  • 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.
  • If you have any questions, feel free to make a new topic (different one for each question) on our forum.

Сообщение отредактировал Kess: 02 February 2014 - 23:02

  • 1





Темы с аналогичным тегами documentation, import, jbzoo 2.0+

Click to return to top of page in style!