[docs] Update User Guide

docs/user-guide/annotations.md

@@ -1,49 +1,140 @@
 # Adding Annotations
 ********************
 
-Starting from a new map or an already existing map:
+[Mapstore](https://mapstore2.geo-solutions.it/mapstore/#/) lets you enrich the map with special features which expose additional information, mark particular position on the map and so on.
+Those features make up the so called **Annotations** layers.
 
-* **Click** on the *Burger menu* button <img src="../img/burger.jpg" style="max-width:25px;" /> from the main menu bar.
+Starting from a new map or an already existing one:
+
+* **Click** on the *Burger menu* button <img src="../img/burger.jpg" style="max-width:30px;" /> from the main menu bar.
 * **Click** on the *Annotations* option from the list <img src="../img/annotation-option.jpg" style="max-width:100px;"/>.
 
-The annotation page will open.
+The annotation panel will open.
+
+<img src="../img/annotation_tool.png" style="max-width:600px;" />
+
+Creating a New Annotation
+-------------------------
+
+In order to add a new annotation:
+
+* **Click** on <img src="../img/+++.jpg" style="max-width:30px;" />, a new form will appear.
+
+* **Type** a *Title* (required) and a *Description* (optional).
+
+    <img src="../img/annotation_form_filled.png" style="max-width:500px;" />
+
+* **Click** on <img src="../img/annotation-draw.jpg" style="max-width:30px;" /> to define the annotation geometry and position. You have to select the annotation type first, then to draw it on the map.
+
+    <img src="../img/annotations_types.png" style="max-width:500px;" />
+
+* **Select**, for example, the *Polygon* type.
+
+* **Click** on the map to define the polygon vertices.
+
+    <img src="../img/polygon_annotation_drawing.gif" />
+
+    You can also insert new vertices, or edit existing ones, through the coordinates editor using `Decimal` or `Aeronautical` formats.
+
+    <img src="../img/coordinates_format_switcher.png" style="max-width:600px;" />
+
+    New vertices can be also added using the <img src="../img/++.jpg" style="max-width:30px;" /> button and typing the `latitude` and `longitude` values (see the picture below).
+
+    <img src="../img/add_vertex_button.png" style="max-width:450px;" />
+
+    Invalid vertices are notified with a red exclamation point icon.
+
+    <img src="../img/invalid_vertex.png" style="max-width:600px;" />
+
+* **Click** the *Change Style* <img src="../img/change_style_icon.png" style="max-width:30px;" /> button (optional) to manage the annotation style (see the next paragraph).
+
+* **Click** on *Save* <img src="../img/save_button.png" style="max-width:30px;" />.
+
+* **Click** on *Save* <img src="../img/save_button.png" style="max-width:30px;" /> on the main form.
+
+The annotations layer will be added to the TOC and the annotation will be visible in the annotations list as in the figure below.
+
+<img src="../img/tijuana_annotation.png" />
+
+Styling Annotations
+-------------------
+
+Based on which type of annotation was chosen, [MapStore](https://mapstore2.geo-solutions.it/mapstore/#/) allows you to customize the annotation style through a powerful editor. It is accessible from the <img src="../img/annotation-draw.jpg" style="max-width:30px;" /> button of the annotation toolbar.
+
+<img src="../img/annotations_toolbar.png" style="max-width:500px;"/>
+
+***Marker***
+
+MapStore provides two types of *Marker* annotations, so you have to choose what type do you prefer using the *Type* combo box (*Marker* is the default):
+
+<img src="../img/marker_type_selection.png" style="max-width:500px;"/>
+
+* *Marker* types can be customized through the following editor:
+
+    <img src="../img/marker_style_editor.png" style="max-width:600px;"/>
+
+    Choose the `Shape`, `Color` and `Icon` that best fit your needs.
+
+* *Symbol* types can  have different `Shape` and `Size`, a `Fill color` with a customizable `Opacity` level (%), a `Stroke` of different types (continuous, dashed, etc) and customizable `Color`, `Opacity` and `Width`.
+
+    <img src="../img/symbol_style_editor.png" style="max-width:600px;"/>
+
+***Polyline***
+
+*Polyline* annotations can be styled using the following editor:
+
+<img src="../img/polyline_style_editor.png" style="max-width:500px;"/>
+
+You can customize the `Stroke` in order to consider the `Line/Dash` type (continuous, dashed, dotted, etc), `Color`, `Opacity` and `Width`.
+You can also have styled *Start/End Points*: enable the *StartPoint Style*/*EndPoint Style* panel using the corresponding check box, the editor will be the same used for *Marker/Symbol* annotations.
+
+***Polygon***
+
+With polygonal annotations changing the style means choose the `Shape` and the size the `Size` of the polygon, its `Fill color` (with custom `Opacity`), the type of the `Stroke` (continuous, dashed, dotted, etc), its `Color`, `Opacity` and `Width`.
+See the example below to better understand these options.
+
+<img src="../img/polygon_style_editor.png" style="max-width:500px;"/>
 
-<p align = "center" ><img src="../img/annotation-page.jpg" style="max-width:500px;" /></p>
+***Text***
 
-* **Click** on <img src="../img/annotation-new.jpg" style="max-width:40px;" /> to add a new annotation.
+*Text* annotations are a bit different from the geometric ones. They display a formatted text on a given point of the map.  
+The style editor lets you customize the text `Font` (`Family`, `Size`, `Style`, `Weight`) and the `Alignment` (`left`, `center` or `right`).
+It also treat the text as a geometric entity, so you can choose a `Fill color` and its `Opacity`, the `Stroke` type, its `Color`, `Opacity` and `Width`. Take a look at the following example.
 
-You will be addressed to a new page where you can draw on the map and edit the annotation properties.
+<img src="../img/text_annotation_editor.png" style="max-width:500px;"/>
 
-<p align = "center" ><img src="../img/annotation-edit.jpg" style="max-width:500px;" /></p>
+***Circle***
 
-* **Click** on <img src="../img/annotation-draw.jpg" style="max-width:25px;" /> to draw the annotation on the map.
+Circle annotations can have custom `Fill color` (with custom `Opacity`), `Stroke` type (continuous, dashed, dotted, etc) with custom `Color`, `Opacity` and `Width`. The *Center* can be also customized through the same editor described for *Marker* annotations.
+See the example below.
 
-* **Click** on the map to draw it. **Enter** a title and a description then click on save.
+<img src="../img/circle_style_editor.png" style="max-width:500px;"/>
 
-<p align = "center" ><img src="../img/annotation-geosolutions.jpg" style="max-width:500px;" /></p>
+Click on <img src="../img/apply_button.png" style="max-width:30px;" /> to apply the style.
 
-The annotation will be added to the TOC and to the annotations list as in the figure below.
+Managing Annotations
+--------------------
 
-<img src="../img/annotation-geosolutions-1.jpg" style="max-width:700px;" />
+You can manage anytime your annotations through the *Annotation Toolbar*. Click on some annotation to display it.
 
-Editing an Annotation
-------------------
+<img src="../img/annotation_toolbar.png" style="max-width:500px;"/>
 
-From the annotations list on the right:
+* You can edit you annotations by clicking the <img src="../img/edit_button.png" style="max-width:30px;" /> button, it allows you to change the geometry and/or the information related to the annotations. See the gif below to better understand how:
 
-* **Click** on the annotation you want to edit. You will be addressed to a new page.
+    <img src="../img/editing_annotations.gif" />
 
-<p align = "center" ><img src="../img/annotation-geosolutions-edit.jpg" style="max-width:500px;" /></p>
+* The <img src="../img/zoom_button.png" style="max-width:30px;" /> button allow the map to zoom on the annotation.
 
-* **Click** on *Edit*. You will be addressed to the main annotations page.
+* To delete the annotation use the <img src="../img/delete_button.png" style="max-width:30px;" /> button.
 
-<p align = "center" ><img src="../img/annotation-geosolutions.jpg" style="max-width:500px;" /></p>
+* Annotations can be also download in `json` format and reused in other maps. Using <img src="../img/download_annotation_button.png" style="max-width:30px;" /> button you will be able to export your annotation in the `Annotation.json` file and download it.
 
-* **Click** on <img src="../img/annotation-geosolutions-edit-1.jpg" style="max-width:20px;" /> button to change the marker style.
+    <img src="../img/download_annotation.png" />
 
+From the main panel of the *Annotations* tool you can also download/upload annotations to/from a `json` file.
 
-<p align = "center" ><img src="../img/annotation-marker.jpg" style="max-width:500px;" /></p>
+<img src="../img/annotations_main_panel.png" style="max-width:500px;" />
 
-* **Save** the edits.
+* **Click** on <img src="../img/download_annotation_button.png" style="max-width:30px;" > to *download* a file with all the existing annotations.
 
-<p align = "center" ><img src="../img/annotation-marker-1.jpg" style="max-width:500px;" /></p>
+* **Click** on <img src="../img/upload_annotation_button.png" style="max-width:30px;" > to *upload* annotations from a valid `json` file.

docs/user-guide/catalog.md

@@ -17,17 +17,21 @@ Starting from a new map or an already existing map:
 
 The Catalog page will open showing a list of services, a search box to search the layers by name and a list of the retrieved layers ready to be added to the map.
 
-<p align = "center" ><img src="../img/catalog-page.jpg" style="max-width:500px;" /></p>
+<p align = "center" ><img src="../img/catalog_panel.png" style="max-width:500px;" /></p>
 
-* **Select** from the list *Demo WMS Service* for example.
+An example:
 
-<p align = "center" ><img src="../img/service-list.jpg" style="max-width:500px;" /></p>
+* **Select** *GeoSolutions GeoServer WMS* from the list.
 
-* **Type** a text in the search box, e.g. black, then click on the search button.
+<p align = "center" ><img src="../img/service_list.png" style="max-width:500px;" /></p>
 
-<p align = "center" ><img src="../img/catalog-search.jpg" style="max-width:500px;" /></p>
+* **Type** a text in the search box, e.g. "us", then click on the search button (or press `ENTER`).
 
-* **Add** the layer to the map clicking on <img src="../img/add-to-map.jpg" style="max-width:80px;" />.
+<p align = "center" ><img src="../img/catalog_search.png" style="max-width:500px;" /></p>
+
+* **Add** the layer to the map clicking on <img src="../img/add_to_map_button.png" style="max-width:30px;" />.
+
+    <img src="../img/added_layer.png" />
 
 Adding and Editing a Service
 ----------------------------
@@ -36,16 +40,84 @@ As mentioned before, [MapStore](https://mapstore2.geo-solutions.it/mapstore/#/)
 
 * **Click** on the <img src="../img/+.jpg" style="max-width:80px;" /> button to add a new service.
 
-<p align = "center" ><img src="../img/new-service.jpg" style="max-width:500px;" /></p>
+<p align = "center" ><img src="../img/new_service.png" style="max-width:500px;" /></p>
 
-* **Type** the URL name, e.g. http://tms.comune.fi.it/geowebcache/service/wms, and the Title.
+* **Type** the URL name, e.g. `http://tms.comune.fi.it/geowebcache/service/wms`, and the Title.
 * **Select** the Type of the service.
 * **Save** the service created.
 
-<p align = "center" ><img src="../img/new-service-firenze.jpg" style="max-width:500px;" /></p>
+    <p align = "center" ><img src="../img/new_service_firenze.png" style="max-width:500px;" /></p>
+
+    Tick the `Search on service selection` checkbox if you want to trigger a search at the same time you select the service, tick the `Show preview` one to see the resulting layers previews near their title.
 
 A list of layers will be loaded from the portal ready to be added to your map.
 
-<p align = "center" ><img src="../img/catalog-firenze.jpg" style="max-width:500px;" /></p>
+<p align = "center" ><img src="../img/catalog_firenze.png" style="max-width:500px;" /></p>
+
+!!! note
+    For those layers which have long descriptions or long metadata information, the content is truncated in order to fit the *Layer Card* size. It is possible to expand the card using the <img src="../img/expand_card_icon.png" style="max-width:30px;" /> button:
+
+    <p align = "center" ><img src="../img/expand_card.gif" style="max-width:350px;" /></p>
+
+In order to edit a service, **Click** on the edit button <img src="../img/edit-service.jpg" style="max-width:80px;" /> and apply your changes.
+
+Custom Metadata Template
+------------------------
+
+The *Catalog* tool of [MapStore](https://mapstore2.geo-solutions.it/mapstore/#/) allows you to customize what metadata to show and how they appear. About that, a **Metadata Template** is provided from the *Advanced Settings* panel of the service:
+
+<p align = "center" ><img src="../img/metadata_template.png" style="max-width:500px;" /></p>
+
+Tick that checkbox to get access to this functionality.
+
+!!! warning
+    The *Metadata Template* function is available for **CSW Services** only.
+
+The *Metadata Template* panel makes available a **Text Editor** through which you can expose the available metadata information within a custom text. [MapStore](https://mapstore2.geo-solutions.it/mapstore/#/) suggests you how to correctly retrieve the properties values (**`${ property_name }`**) and what properties are available (see the tooltip content in the picture below).
+
+<p align = "center" ><img src="../img/metadata_template_panel.png" style="max-width:500px;" /></p>
+
+An example:
+
+* **Type** the following template in the text editor
+
+```
+title: ${title}
+-------------------
+description: ${description}
+-------------------
+abstract: ${abstract}
+-------------------
+boundingBox: ${boundingBox}
+-------------------
+contributor: ${contributor}
+-------------------
+creator: ${creator}
+-------------------
+format: ${format}
+-------------------
+identifier: ${identifier}
+-------------------
+references: ${references}
+-------------------
+rights: ${rights}
+-------------------
+source: ${source}
+-------------------
+subject: ${subject}
+-------------------
+temporal: ${temporal}
+-------------------
+type: ${type}
+-------------------
+uri: ${uri}
+```
+
+* **Click** on *Save*
+
+* This should be the results for the `test.point` layer:
+
+    <p align = "center" ><img src="../img/metadata_template_example.gif" /></p>
 
-In order to edit a service, **Click** on the edit button <img src="../img/edit-service.jpg" style="max-width:80px;" /> and apply your changes.
+!!! warning
+    If some metadata is absent the `source Not Available` text will be shown.

docs/user-guide/filtering-layers.md

@@ -0,0 +1,104 @@
+# Filtering Layers
+******************
+
+When using vector layers it might be useful to work with a subset of features.
+About that, [MapStore](https://mapstore2.geo-solutions.it/mapstore/#/) let you set up a **Layer Filter** that acts directly on a layer coming from GeoServer and filter its content upfront.  
+The map will immediately update when a filter is created and all other tools will take it into consideration when used. More over, the filter is saved into the map context so if you save it the filter will apply when you open the map next time.
+
+Creating a new Layer Filter
+---------------------------
+
+As we said  in [this](toc.md#managing-layers) section, is it possible to set up a *Layer Filter* from the <img src="../img/filter-layer.png" style="max-width:30px;"/> button of the TOC toolbar. Select a vector layer and click on it to see the toolbar.
+
+<img src="../img/filter_layer_button.png" />
+
+The following steps show you how to filter that layer:
+
+* **Click** on the <img src="../img/filter-layer.png" style="max-width:30px;"/> button to open the *Query Builder*.
+
+    <img src="../img/query_builder.png" />
+
+* **Set up** a filter. In this example we will draw a region of interest on the map to perform a spatial query:
+
+    * **Select** a *Filter Type* (a `Rectangle` for example), you can choose between these spatial objects:
+
+        * *Viewport*
+        * *Rectangle*
+        * *Circle*
+        * *Polygon*
+
+    * **Select** a *Geometric Operation* (`Intersect` could be fine), you can choose between these operations:
+
+        * *Intersect*
+        * *Is contained*
+        * *Contains*
+
+        <img src="../img/filter_set_up.png" />
+
+        A message suggest you to *draw the region of interest on the map*, so do it to complete the filter creation.
+
+    * **Draw** a rectangle on the map
+
+        <img src="../img/rectangle_filter.png" />
+
+* **Click** the *Apply* <img src="../img/apply_button.png" style="max-width:30px;"/> button of the Query Builder toolbar, the map updates immediately.
+
+    <img src="../img/applied_filter.png" />
+
+* **Click** on *Save* <img src="../img/save_button.png" style="max-width:30px;"/> button to make it persistent. It means the filter will take effect whenever using the layer even if the *Query Builder* is closed.
+
+A filter icon <img src="../img/filter-layer.png" style="max-width:30px;"/> is shown in the [TOC](toc.md) right next to the layer title to notify that the layer is filtered. The *Filter Icon* is toggleable to temporarily disable the filter anytime.
+
+<img src="../img/enable_layer_filter.gif" />
+
+### Layer Filter Persistence
+
+Once the filter has been saved the filter becomes **persistent** along with the other layer options and inside the map object on map save.
+
+If you try to retrieve the features information through a click on the map, the filter you have created is applied to the content you get:
+
+<img src="../img/get_filtered_features_info.gif" />
+
+The layer [Attributes Table](attributes-table.md) also takes the filter into account:
+
+<img src="../img/filtered_features_grid.png" />
+
+Any additional filter you define using the [Advanced Filtering](attributes-table.md#advanced-filtering) tool or the *Quick Filter* will overlap the layer filter.  
+*Layer Filter* will go in *`AND`* with *Advanced Filtering*:
+
+<img src="../img/filtered_advanced_filtering.gif" />
+
+*Layer Filter* will go in *`AND`* with *Quick Filter*:
+
+<img src="../img/filtered_quick_filter.gif" />
+
+When saving a map the *Layer Filter* is saved along with it, so if you reload the map the filter will still be active.
+
+Modifying a Layer Filter
+------------------------
+
+If you want to change the *Layer Filter* configuration you have to click the *Filter Layer* button <img src="../img/filter-layer.png" style="max-width:30px;"/> in the [TOC](toc.md) toolbar so that the *Query Builder* opens.
+
+* **Modify** the existing filter (adding new conditions for example)
+
+* **Click** on *Apply* <img src="../img/apply_button.png" style="max-width:30px;"/> so that the map updates
+
+* **Click** on *Save* <img src="../img/save_button.png" style="max-width:30px;"/> to make the filter persistent
+
+<img src="../img/modify_layer_filter.gif" />
+
+The *Query Builder* toolbar makes also available the *Undo* button <img src="../img/undo_button.png" style="max-width:30px;"/> to discard applied changes to the filter since the last save (so it is disabled if no changes are made after the last save).
+
+Removing a Layer Filter
+-----------------------
+
+When opening the *Query Builder* of a filtered layer, the filter is already configured.  
+The *Reset* button <img src="../img/reset_button.png" style="max-width:30px;"/> is the only one enabled and it allows you to clear the filter (it restores an empty filter):
+
+* **Click** on *Reset* <img src="../img/reset_button.png" style="max-width:30px;"/>, an empty filter will be configured and the map updates immediately.
+
+* **Click** on *Save* <img src="../img/save_button.png" style="max-width:30px;"/> to make the state persistent or **Click** *Undo* <img src="../img/undo_button.png" style="max-width:30px;"/> to restore the previous saved filter.
+
+An example in the following gif:
+
+<img src="../img/remove_layer_filter.gif" />