Configuration
=============

* Create new extension:

``./zaz.py -new -t ~/projects -n MyGreatExtension``


* Move to new folder:

``cd ~/projects/MyGreatExtension``


* Edit file ``conf.py``

``vim conf.py``


Parameters
----------

**Configure correctly this options, before you start code your extension.**

Only modify this options.


Type extension
^^^^^^^^^^^^^^

**TYPE_EXTENSION**

The type extension that you want develop.

* Integer
    * 1 = Normal extension
    * 2 = New components
    * 3 = Calc addin

Example:

.. code-block:: python

    TYPE_EXTENSION = 1


Version
^^^^^^^

**VERSION**

* String
    * The current version of extension, look: `Semantic Versioning`_

Example:

.. code-block:: python

    VERSION = '0.1.0'


Name
^^^^

**NAME**

* String
    * Your extension name, not used spaces.

Example:

.. code-block:: python

    NAME = 'MyGreatExtension'


ID extension
^^^^^^^^^^^^

The internal name for extension.

**ID**

    * String
        * Should be unique, used URL inverse

Example:

.. code-block:: python

    ID = 'org.yourname.extensionname'


Locales
^^^^^^^

If your extension will be multi-language (recommended)

**USE_LOCALES**

    * Bool

Example:

.. code-block:: python

    USE_LOCALES = True


Domain for locales
^^^^^^^^^^^^^^^^^^

The base name for generate files POT

**DOMAIN**

    * String

Example:

.. code-block:: python

    DOMAIN = 'base'


Path pyGetText
^^^^^^^^^^^^^^

Absolute path for tool `pygettext.py` for generate POT.

**PATH_PYGETTEXT**

    * String

Example:

.. code-block:: python

    PATH_PYGETTEXT = '/usr/lib/python3.9/Tools/i18n/pygettext.py'


Author
^^^^^^

Your information like author, one or more languages. This information is displayed in the extension manager.

**PUBLISHER**

    * Dictionary

Example:

.. code-block:: python

    PUBLISHER = {
        'en': {'text': 'Your name', 'link': 'https://your.page'},
        'es': {'text': 'Tu nombre', 'link': 'https://elmau.net'},
    }


Extension icon
^^^^^^^^^^^^^^

Path relative or absolute to extension logo. Show in extension manager.

**ICON**

    * String

Example:

.. code-block:: python

    ICON='images/logo.png'


License
^^^^^^^

The license for your extension, please, used free license.

**LICENSE**

    * String

Example:

.. code-block:: python

    LICENSE_EN = f"""This file is part of {NAME}.

        {NAME} is free software: you can redistribute it and/or modify
        it under the terms of the GNU General Public License as published by
        the Free Software Foundation, either version 3 of the License, or
        (at your option) any later version.

        {NAME} is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        GNU General Public License for more details.

        You should have received a copy of the GNU General Public License
        along with {NAME}.  If not, see <https://www.gnu.org/licenses/>.
    """
    LICENSE_ES = LICENSE_EN


Information
^^^^^^^^^^^

Information of extension: Display name, description and license to displayed when install.

**INFO**

    * Dictionary

Example:

.. code-block:: python

    INFO = {
        'en': {
            'display_name': 'Test Macro',
            'description': 'My great extension',
            'license': LICENSE_EN,
        },
        'es': {
            'display_name': 'Macro de Prueba',
            'description': 'Mi gran extensión',
            'license': LICENSE_ES,
        },
    }


Parent menu
^^^^^^^^^^^

Only for normal extension (`TYPE_EXTENSION = 1`), where add extension menu, only two possible values: **AddonMenu** or **OfficeMenuBar**

**PARENT**

    * String
        * **AddonMenu**: Show in menu Tools->Add-Ons
        * **OfficeMenuBar**: Show in LibreOffice menu

Example:

.. code-block:: python

    PARENT = 'OfficeMenuBar'


Main menu
^^^^^^^^^

Only for normal extension (`TYPE_EXTENSION = 1`) and only if parent menu is `OfficeMenuBar`. Can be multi language.

**MENU_MAIN**

    * Dictionary

Example:

.. code-block:: python

    MENU_MAIN = {
        'en': 'My Extension',
        'es': 'Mi Extensión',
    }




.. _Semantic Versioning: https://semver.org/