Merge pull request #14 from akeneo/doc

Added documentation

README.md

@@ -1,38 +1,25 @@
-Akeneo Excel Connector Bundle
-=============================
+# Akeneo Excel Connector Bundle
 
-This bundle contains utility classes used to create Excel connectors.
-It also provides a method to initiate the PIM with a single Excel file.
+This bundle adds support of Excel XSLX files as a source for initialization and importation of catalog structure for [Akeneo PIM](https://github.com/akeneo/pim-community-standard).
 
 [![Scrutinizer Quality Score](https://scrutinizer-ci.com/g/akeneo/ExcelConnectorBundle/badges/quality-score.png?s=9732bdac97b997021b1c925f923ecbf405a509d4)](https://scrutinizer-ci.com/g/akeneo/ExcelConnectorBundle/)
 
-Installing the bundle
----------------------
-From your application root:
+# Documentation
 
-    $ php composer.phar require --prefer-dist "akeneo/excel-connector-bundle"
+See [Resources/doc folder](./Resources/doc/Home.rst) for more details on how to set your catalog structure
+using the [init.xslx](./Resources/fixtures/minimal/init.xlsx) file.
 
-Register the bundle by adding the following lines inside the `app/AppKernel.php` file, just before the "return $bundles;" line:
+# Supported file
 
-    $bundles[] = new Akeneo\Bundle\SpreadsheetParserBundle\AkeneoSpreadsheetParserBundle();
-    $bundles[] = new Pim\Bundle\ExcelConnectorBundle\PimExcelConnectorBundle();
+Input file must follow [init.xslx](./Resources/fixtures/minimal/init.xlsx) structure.
+Note that the file must be opened with Excel. LibreOffice/OpenOffice are not in compliance with validations data 
+that are available in the spreadsheet.
 
+# Importation job
 
-Initializing the PIM with an Excel file
----------------------------------------
+This bundle allows you to import the [init.xslx](./Resources/fixtures/minimal/init.xlsx) file directly
+in the UI through Import > Import jobs.
 
-To initialize the PIM with an Excel file, use the following steps :
-
- * Copy the Resources/fixtures/minimal folder inside the Resources/fixtures folder of one of your bundles.
- * Edit the init.xlsx file to your needs
- * Define the following parameter in the DI files of one of your bundles
-
-    parameters:
-        pim_installer.fixture_loader.job_loader.config_file:       'PimExcelConnectorBundle/Resources/config/fixtures_jobs.yml'
-
- * Define the data used by the installer in the parameters.yml file:
-
-    installer_data: 'AcmeDemoBundle:minimal'
-
-The init.xlsx file can also be loaded by using the "Initialisation import" from the "Akeneo Excel Connector"
+# Dependencies
 
+This bundles uses [phpoffice/phpexcel](https://github.com/PHPOffice/PHPExcel) and [akeneo/spreadsheet-parser-bundle](https://github.com/akeneo/spreadsheet-parser).

Resources/config/batch_jobs.yml

@@ -22,7 +22,6 @@ connector:
                         reader:    pim_base_connector.reader.doctrine.product
                         processor: pim_excel_connector.processor.normalizer.product_csv
                         writer:    pim_excel_connector.writer.xlsx.product_family
-
         excel_2003_xml_product_export:
             title: pim_excel_connector.jobs.excel_2003_xml.product.export.title
             type: export

Resources/doc/Association-type-tab.rst

@@ -0,0 +1,36 @@
+Association type tab
+====================
+
+See `user guide`_ to know more about association types.
+
+Association type code
+---------------------
+
+Specify here a code for your association type. Association type code
+must be only composed of letters, numbers, spaces and underscores. No
+other character will be accepted.
+
+Example: ``X_SELL``, ``UPSELL``, ``SUBSTITUTION``, ``PACK``.
+
+Labels
+------
+
+These columns allows you to define localized label for your attribute.
+You will have to add one column per locale. Be sure they are grouped
+below the Labels section (line #1). Note that the 3rd line is hidden and
+you will have to show it in order to add new locales. The following example
+is showing this hidden line.
+
+**Example:**
+
++-------------------------------+---------------------------------------------+ 
+| Association type properties   | Labels                                      |
+|                               +--------------+--------------+---------------+
+|                               | en_US        | es_ES        | fr_FR         |
++===============================+==============+==============+===============+
+| Association type code         | label-en_US  | label-es_ES  | label-fr_FR   |
++-------------------------------+--------------+--------------+---------------+
+| X_SELL                        | Cross sell   | Venta cruzada| Vente croisée |
++-------------------------------+--------------+--------------+---------------+
+
+.. _user guide: http://www.akeneo.com/doc/user-guide/key-concepts/association/

Resources/doc/Attribute-groups.rst

@@ -0,0 +1,39 @@
+Attribute groups tab
+====================
+
+An attribute group is composed of attributes. Attributes groups are
+shown on the left menu of the product edit form.
+
+Group code
+----------
+
+Specify here a code for your attribute group. Attribute group code must
+be only composed of letters, numbers, spaces and underscores. No other
+character will be accepted.
+
+**Examples:** ``measures``, ``sizes`` and ``technical``.
+
+Position
+--------
+
+Position is an integer number used to define the order of the attribute
+group in the left panel of the product edit form.
+
+Labels
+------
+
+These columns allows you to define localized label for your attribute.
+You will have to add one column per locale. Be sure they are grouped
+below the Labels section (line #4).
+
+**Example:**
+
++-----------------------+---------------------------------------------+ 
+| Group properties      | Labels                                      |
+|                       +--------------+-------------+----------------+
+|                       | label-en_US  | label-es_ES |  label-fr_FR   |
++============+==========+==============+=============+================+
+| Group code | Position | en_US        |  es_ES      | fr_FR          |
++------------+----------+--------------+-------------+----------------+
+| measures   | 1        | Measures     | Medidas     | Mesures        |
++------------+----------+--------------+-------------+----------------+

Resources/doc/Attribute-types.rst

@@ -0,0 +1,9 @@
+Attribute types tab
+===================
+
+This tab is only defining human readable shortcuts for attribute types
+with a code and a label.
+
+If you are using the
+`CustomEntityBundle <https://github.com/akeneo/CustomEntityBundle>`__
+you will have to add your own attribute type here.

Resources/doc/Attributes.rst

@@ -0,0 +1,201 @@
+Attributes tab
+==============
+
+In this tab you can define every attribute depending wether they belong
+to one or more families. If the attribute is only part of one family,
+consider defining it directly in the corresponding family tab.
+
+See `family tab
+section <https://github.com/akeneo/ExcelConnectorBundle/wiki/Families>`__
+to know how to do this.
+
+For more details about the keys concept of attribute, see `attribute in
+the user
+guide <http://www.akeneo.com/doc/user-guide/key-concepts/attributes/>`__.
+
+General properties
+------------------
+
+Attribute code
+~~~~~~~~~~~~~~
+
+Attribute code must be only composed of letters, numbers, spaces and
+underscores. No other character will be accepted.
+
+Label columns
+~~~~~~~~~~~~~
+
+These columns allows you to define localized label for your attribute.
+You will have to add one column per locale. Be sure there are grouped
+below the **Labels** section (line #4) like this:
+
++----------------+-----------------------------------------+ 
+| Attribute code | Labels                                  |
+|                +-------------+-------------+-------------+
+|                | en_US       | en_GB       | fr_FR       |
++================+=============+=============+=============+
+| code           | label-en_US | label-en_GB | label-fr_FR |
++----------------+-------------+-------------+-------------+
+| color          | Color       | Colour      | Couleur     |
++----------------+-------------+-------------+-------------+
+
+**Note** : labels must be under 255 characters.
+
+Attribute type
+~~~~~~~~~~~~~~
+
+Attribute type can be: ``Identifier``, ``Text``, ``Text area``,
+``Multiple select``, ``Simple select``, ``Price collection``,
+``Number``, ``Boolean``, ``Date``, ``File``, ``Image`` and ``Metric``.
+
+These type are definded in the hidden `attribute type
+tab <https://github.com/akeneo/ExcelConnectorBundle/wiki/Attribute-types>`__
+attribute\_type. If you are using the
+`CustomEntityBundle <https://github.com/akeneo/CustomEntityBundle>`__,
+this is where you will have to add your new attribute type.
+
+Attribute group
+~~~~~~~~~~~~~~~
+
+Select here the associated attribute group code. Attributes codes are
+defined in the `attribute
+groups <https://github.com/akeneo/ExcelConnectorBundle/wiki/Attribute-groups>`__
+tab.
+
+Sort order
+~~~~~~~~~~
+
+The sort order is an integer defining the display order in the attribute
+group on the product edit form.
+
+Is unique
+~~~~~~~~~
+
+Choose if the attribute must have unique values.
+
+Is localizable
+~~~~~~~~~~~~~~
+
+Choose if the attribute is localizable or not.
+
+Specific to locales
+~~~~~~~~~~~~~~~~~~~
+
+Define here the list of comma-separated locales.
+
+Is scopable
+~~~~~~~~~~~
+
+Choose if the attribute is scopable or not.
+
+Minimum input length
+~~~~~~~~~~~~~~~~~~~~
+
+Determines how many characters should be typed for select attributes
+before an option is presented. This should be used for attributes which
+have a large number of options
+
+Useable as grid filter
+~~~~~~~~~~~~~~~~~~~~~~
+
+Choose if the attribute is useabe as grid filter or not.
+
+Properties for text attributes
+------------------------------
+
+Max characters
+~~~~~~~~~~~~~~
+
+Max characters is an integer defining how many characters maximum can be
+entered in a text field.
+
+Validation rule
+~~~~~~~~~~~~~~~
+
+Validation rule can be ``email``, ``url`` or ``regexp``.
+
+Validation regexp
+~~~~~~~~~~~~~~~~~
+
+If validation rule is *regexp*, use this column to define the regular
+expression that will be used for validation.
+
+Rich text
+~~~~~~~~~
+
+Choose if the text field will be using a `TinyMCE WYSIWYG
+editor <http://www.tinymce.com/>`__, allowing rich text possibilities.
+
+Properties for number attributes
+--------------------------------
+
+Minimum number
+~~~~~~~~~~~~~~
+
+Specify here the minimum number.
+
+Maximum number
+~~~~~~~~~~~~~~
+
+Specify here the maximum number.
+
+Decimals allowed
+~~~~~~~~~~~~~~~~
+
+Specify here if the numbers can only be integers or not.
+
+Negative allowed
+~~~~~~~~~~~~~~~~
+
+Specify here if negative numbers are allowed.
+
+Properties for date attributes
+------------------------------
+
+Minimum date
+~~~~~~~~~~~~
+
+Specify here the minimum date users can input.
+
+Maximum date
+~~~~~~~~~~~~
+
+Specify here the maximum date users can input.
+
+Properties for metric attributes
+--------------------------------
+
+Metric family
+~~~~~~~~~~~~~
+
+Choose here the metric family. Available options are: ``Area``,
+``Binary``, ``Frequency``, ``Length``, ``Power``, ``Speed``,
+``Temperature``, ``Volume``, ``Weight``.
+
+Metric families are defined in the hidden `metric
+types <https://github.com/akeneo/ExcelConnectorBundle/wiki/Metric-types>`__
+tab.
+
+Default metric unit
+~~~~~~~~~~~~~~~~~~~
+
+Choose here the default metric unit.
+
+Metric units are defined in the hidden `metric
+units <https://github.com/akeneo/ExcelConnectorBundle/wiki/Metric-units>`__
+tab.
+
+Properties for file attributes
+------------------------------
+
+Max file size
+~~~~~~~~~~~~~
+
+Define here the maximum file size in MB.
+
+Allowed extensions
+~~~~~~~~~~~~~~~~~~
+
+Insert the allowed extensions, separated by a comma.
+
+For example : ``jpg``, ``jpeg``, ``png`` or ``pdf``.

Resources/doc/Categories-tab.rst

@@ -0,0 +1,23 @@
+Categories tab
+==============
+
+Category code
+-------------
+
+Category code must be only composed of letters, numbers, spaces and
+underscores. No other character will be accepted.
+
+Parent category code
+--------------------
+
+Specify here the parent category code. Leave it empty if the category is
+a root of a category tree.
+
+Labels colums
+-------------
+
+These columns allows you to define localized label for your attribute.
+You will have to add one column per locale. Be sure there are grouped
+below the Labels section (line #1).
+
+**Note:** labels must be under 255 characters.