.. include:: ../../substitutions.rst

..
   _The purpose of this quick start is to provide a page without too much anchor to other pages.
   _It should be a tutorial, like mainstream
   _External anchors makes the reading more difficult for new comers.
   _We try to avoid text duplication

Quick start
===========

.. contents::
   :depth: 3

This is **quick** start guide to help you how to publish your first dataset on Lizmap with a few knowledge.

Installing the Lizmap plugin on QGIS Desktop
--------------------------------------------

To publish a QGIS project in Lizmap Web Client, you need a Lizmap configuration file, with the extension :file:`.qgs.cfg`.
This file is **automatically** generated by the Lizmap plugin in QGIS Desktop.

.. include:: ../shared/lizmap_plugin_installation.rst

.. image:: /images/introduction-install-lizmap.jpg
   :align: center
   :width: 60%
   :alt: Lizmap plugin installation in the QGIS plugin manager

Preparing your file organization
--------------------------------

Lizmap Web Client must have the same files and directories architecture on the server than on your local computer.

.. tip::
    It's **important** to keep in mind that QGIS server will **open** your project with the **same file paths** as on
    your QGIS desktop. All your data must be within a folder which can be transferred.

.. tip::
    ``custom_repository`` is a folder representing a common theme. The folder will contain **one or many** QGIS projects,
    belonging to this theme. The name of the theme displayed on the web interface will be configured **later**.
    You should use a machine name.

    You are **free** to rename this folder with a different name, representing your **own** theme.

    In this folder, we will store all projects related to :guilabel:`Urbanisme and land-use` during this tutorial.

We are going to create a folder structure on to make it easy to transfer **on the server later**:

#. On your computer, create a local ``lizmap`` folder
#. Create in the ``lizmap`` folder a ``media`` folder
#. Create in the ``lizmap`` folder a ``custom_repository`` folder
#. Create in the ``lizmap/custom_repository`` folder a ``media`` folder
#. Create in the ``lizmap/custom_repository`` folder a ``data`` folder
#. Copy in the folder ``lizmap/custom_repository/data`` the geographic data to publish (FlatGeoBuf, GeoJSON, SHP, others files)

You should have this tree structure on your computer:

.. code-block:: text

   lizmap/
   +- media/
   +- custom_repository/
      +- media/
      +- data/
         +- geo-data.fgb
         +- your-geo-data.shp
         +- your-geo-data.shx
         +- your-geo-data.dbf
         +- your-geo-data.prj

.. tip::
    You can change names of these directories except for ``media``, which is a special keyword for Lizmap.
    Read **later** the chapter about :ref:`media`.

Preparing your QGIS project
----------------------------

#. In QGIS desktop, load data from the folder ``lizmap/custom_repository/data``
#. Save the QGIS project in ``lizmap/custom_repository`` with the :file:`.qgs` extension. For instance :file:`my-first-lizmap.qgs`.
#. Prepare the data rendering:

    * layer order
    * groups in the legend
    * symbology
    * labels, etc

#. In :menuselection:`Project Properties --> QGIS Server --> Service Capabilities`, fill some metadata :

    * :guilabel:`Title`, the main title which will be displayed in the landing page. Use a human title with space and accents.
    * :guilabel:`Abstract`, a fully written paragraph for the description. HTML is supported.
    * :guilabel:`Keywords`, some keywords separated by a comma. This will be used by the search bar.

You should have this tree structure on your computer:

.. code-block:: text

   lizmap/
   +- media/
   +- custom_repository/
      +- media/
      +- data/
         +- your-geo-data.shp
         +- your-geo-data.shx
         +- your-geo-data.dbf
         +- your-geo-data.prj
         +- other-geo-data.fgb
      +- my-first-lizmap.qgs
      +- my-first-lizmap.qgs.cfg

.. image:: /images/file-tree-tutorial.jpg
   :align: center
   :alt: The file tree with this tutorial

Generate the Lizmap configuration file
--------------------------------------

#. Click the :guilabel:`Lizmap` |lizmap_plugin_svg| button
#. Click on the :guilabel:`Layers` tab
#. For each layer:

    #. Set a custom human title for your layer, which will be display in the legend
    #. Be default, layers are published but not visible in Lizmap Web Client when we open the project online.
       Click on :guilabel:`Toggled` to make the layer visible by default.

#. Click on :guilabel:`Ok`

Next to :file:`my-first-lizmap.qgs`, you must find now a new file :file:`my-first-lizmap.qgs.cfg`.

Upload your files to your Lizmap server
---------------------------------------

When your map is ready, you need to upload all files and folder to the server.

.. tip::
    With the help of your system administrator or the Lizmap provider, you **must check**:

    * how to transfer files on the server
    * the folder on the server used for hosting **Lizmap repositories**

Example of an instance hosted on |lizmap_cloud| |lizmap_cloud_svg|, you should have this tree structure on the server,
into the  :file:`qgis` folder:

.. code-block:: text

   cog/
   qgis/
   +- media/
   +- custom_repository/
      +- media/
      +- data/
         +- your-geo-data.shp
         +- your-geo-data.shx
         +- your-geo-data.dbf
         +- your-geo-data.prj
         +- other-geo-data.fgb
      +- my-first-lizmap.qgs
      +- my-first-lizmap.qgs.cfg
   web/

Enable your folder to be a published repository
-----------------------------------------------

Be default, the newly created folder :file:`custom_repository` located **on the server** in not publicly published on
the Lizmap landing page.

You must **enable** the remote folder, to be recognised as a **Lizmap repository**.

#. Go the administration interface of Lizmap in your web browser
#. Click on :guilabel:`Map Management` and then click on :guilabel:`Create repository`
#. Fill in the form:

   #. Fill the :guilabel:`Local folder path` with the :file:`custom_repository` path.

        * Either it can be a dropdown menu if a root repository is configured by the administrator (*recommended solution*)
        * Or it can be a text input. You need to fill a absolute path to the folder

   #. Update the :guilabel:`Label` with the name to be displayed on the landing page, for instance ``Urbanisme and land-use``,
      accents and space recommended.
   #. Update the :guilabel:`ID`, it's an internal ID for Lizmap. It's mainly visible in the URL of the project.
      This identifier can not be edited later.
   #. Click on all the permission boxes you want to change. For beginners, we suggest you to let the ones checked by default.
   #. Click on :guilabel:`Save`

Your folder :file:`custom_repository` should be now recognised as a valid **Lizmap repository**.

**Visit** your landing page and you should **see** your project and you can now **display** the QGIS project online.

Well done.

.. tip::
    The folder :file:`custom_repository` can contain as many as you want QGIS project files with their corresponding
    :file:`.qgs.cfg` file. All projects will be listed **horizontally** on the landing page.

.. tip::
    If you create another folder next to :file:`custom_repository`, like :file:`forestry` with a published name
    ``Forestry``, your folder will be listed **vertically**.

.. tip::
    In your administration page, visit the :guilabel:`QGIS projects` page to have an overview of all your Lizmap repositories
    and metadata about QGIS projects.

Going further
-------------

This the end of the quick start guide, we encourage you reading deeper the documentation about other topics,
such as:

* :ref:`thumbnail`
* :ref:`editing`
* :ref:`printing`

Example of Lizmap repositories
------------------------------

.. include:: ../shared/lizmap_repository.rst