Merge pull request #952 from chughes-lincoln/how-to-updates-v2

How to updates v2

Author: klassenjs

docs/howto/addlayer/add-a-layer.rst

@@ -55,6 +55,5 @@ Add Firestations to the catalog
 Using identify with Firestatations
 ----------------------------------
 
-The:doc:`./add-identify` guide
-features the firestations layer. And describes adding identify and how
-identify works.
+The :doc:`/howto/identify/add-identify` guide 
+describes how identify works and how to add it (using the firestations layer as an example).

docs/howto/identify/add-identify.rst

@@ -121,7 +121,7 @@ The Firestations layer
 
 This section references the ``firestations`` source and
 ``fire_stations`` layer. For more information on setting those up in
-your local demo, read the:doc:`./add-a-layer`
+your local demo, read the :doc:`/howto/addlayer/add-a-layer`
 guide.
 
 Adding identify to Firestations
@@ -165,3 +165,98 @@ Adding identify to Firestations
 -  This example uses GeoMoose's template system. GeoMoose has a rich
    template system provided by Mark.up. :ref:`More information on GeoMoose
    templates here. <templates>`
+
+Adding identify to Raster Data
+-------------------------------
+
+Identify can also be set up for raster data. For example, if you have DEM,
+you can set it up to allow users to identify elevation.
+
+This example assumes you're connecting to a GeoTiff in a mapfile. Optionally,
+you can also connect via WMS, either in a mapfile, or in the ``mapbook.xml``.
+
+See below for an example configuration of the mapfile. Note that the
+``TEMPLATE 'dummy'`` and the ``ows/gml_include_items 'all'`` lines are necessary
+for results to be returned. ``TOLERANCE 0`` is also needed to prevent too
+many results from being returned.
+
+::
+
+    LAYER
+        NAME "ExampleDEM"
+        DATA "./pathToDEM.tif"
+        STATUS ON
+        TYPE RASTER
+
+        PROJECTION
+            "init=epsg:3857"
+        END
+
+        METADATA
+            'wms_title' 'Example_DEM'
+            'ows_include_items' 'all'
+            'gml_include_items' 'all'
+            'ows_exclude_items' 'SHAPE_area,SHAPE_len'
+            'gml_exclude_items' 'SHAPE_area,SHAPE_len'
+        END
+
+        TOLERANCE 0
+        TOLERANCEUNITS METERS
+
+        TEMPLATE 'dummy'
+
+    END
+
+Once the mapfile is configured you can connect to the data in the ``mapbook.xml``. Make sure
+to adjust the mapfile and layer names to match your mapfile. You will also need to change the 
+field name value to match the value in your DEM. You can use ``template name="identify" auto="true"/>``
+to automatically generate the template.
+
+.. code:: xml
+
+        <map-source name="DEM_Identify" type="mapserver">
+            <file>./pathToDEMMapfile</file>
+            <layer name="ExampleDEM" status="on">
+
+                <template name="identify"><![CDATA[
+                    <div class="identify-result">
+                        <div class="item"><label>Elevation:</label>{{ properties.DEMFieldName|fix>1 }}</div>
+                    </div>
+
+                ]]></template>
+
+            </layer>
+
+            <param name="FORMAT" value="image/png"/>
+            <param name="TRANSPARENT" value="TRUE"/>
+            <param name="cross-origin" value="anonymous"/>
+        </map-source>
+
+Optionally, you can also connect to a WMS instead of a mapfile. The main things to
+be aware of when connecting via WMS are making sure that the WMS is configured to 
+allow identify, and making sure that the WMS is configured to allow connections
+from other servers (i.e. Cross-origin-resource-sharing or CORS).
+
+.. code:: xml
+
+        <map-source name="DEM_Identify" type="wms">
+            <url>https://location/of/DEM?</url>
+            <layer name="ExampleDEM" status="on">
+
+                <template name="identify"><![CDATA[
+                    <div class="identify-result">
+                        <div class="item"><label>Elevation:</label>{{ properties.item name=value_0|fix>1 }}</div>
+                    </div>
+
+                ]]></template>
+
+            </layer>
+
+            <param name="FORMAT" value="image/png"/>
+            <param name="TRANSPARENT" value="TRUE"/>
+            <param name="cross-origin" value="anonymous"/>
+        </map-source>
+
+
+
+

docs/howto/images/catalog-legend-overlap.png

@@ -6,6 +6,7 @@ How-Tos
 .. toctree::
     :maxdepth: 3
     :glob:
+    :titlesonly:
 
 
 

docs/howto/index.rst

@@ -1,23 +1,13 @@
 How-to add a Grid to Search and Identify
 ========================================
 
-Add show grid to the service configuration
-------------------------------------------
-
-::
-
-        app.registerService('search', SearchService, {
-            showGrid: true,
-            ...
-        });
-
-Add template links in the mapbook.
+Add template links in the mapbook
 ----------------------------------
 
 -  For search the templates are named ``search-grid-columns`` and
-   ``search-row``.
+   ``search-grid-row``.
 -  For identify the templates are named ``identify-grid-columns`` and
-   ``identify-row``.
+   ``identify-grid-row``.
 
 The search example is shown below:
 
@@ -26,24 +16,47 @@ The search example is shown below:
         <template name="search-grid-columns" src="./templates/parcel-columns.json" />
         <template name="search-grid-row" src="./templates/parcel-row.html" />
 
-Re-using templates in other services
-------------------------------------
+Add a search alias to the service configuration
+------------------------------------------------
 
-It can be useful to use the same templates for different services. For example,
-if the same data should be returned for two different types of search templates.
+Adding a search alias allows the ``search-grid-columns`` and ``search-grid-row``
+templates to be used for search services that aren't named search, while still 
+allowing you to point to different template files for the individual services.
 
-To add the grid results, using the ``search`` templates to ``single-search`` make
+To add an alias, allowing you to use the ``search`` templates for ``single-search``, make
 the following changes to ``app.js``:
 
 ::
 
     app.registerService('single-search', SearchService, {
         ...
+        // this tells GeoMoose to use "search" templates instead of "single-search"
+        alias: 'search'
+    });
+
+Further customize the search service
+------------------------------------------
+
+You can also change some of the default search options, like overwriting the title,
+zooming to results, or having the grid be minimized by default.
+
+::
+
+        app.registerService('single-search', SearchService, {
+        ...
+        // this overwrites the service title
+        title: 'Simple Search'
+        // this overwrites the results title
+        resultsTitle: 'Simple Search Results'
+        // this tells the service to zoom to the results by default
         zoomToResults: true,
         // this will enable the grid
         showGrid: true,
         // this tells GeoMoose to use "search" templates instead of "single-search"
-        alias: 'search'
+        alias: 'search',
+        // this tells the service that the grid results should be minimized by default
+        gridMinimized: true
     });
 
+You can find more examples of how to customize your results at :doc:`customize-results`.
 

docs/howto/results/add-grid-to-search-and-identify.rst

@@ -11,7 +11,7 @@ Add a supported vector map-source
 
 This how-to references the ``firestations`` source and ``fire_stations``
 layer. For more information on setting those up in your local demo, read
-the:doc:`./add-a-layer` guide. This example
+the :doc:`/howto/addlayer/add-a-layer` guide. This example
 creates a WFS-source for the Firestations layer.
 
 Add the following to ``mapbook.xml``:

docs/howto/search/add-search.rst

@@ -0,0 +1,30 @@
+How-to avoid catalog legend overlap
+====================================
+
+If your catalog has very long legends, or many legends open at once in a 
+single group, the legends can overlap with layers beneath them, similar
+to this example:
+
+.. figure:: /howto/images/catalog-legend-overlap.png
+   :alt: Catalog Legend Overlap
+
+   Catalog Legend Overlap
+
+
+
+If this happens, it can be avoided by changing the height of the
+children element in the site's ``site.css`` file, from the default
+height of 2000px, to whatever value is needed.
+
+Change site.css
+------------------------------------------
+
+.. code:: css
+
+    .group.gm-expand .children {
+        max-height: 3000px;
+    }
+
+
+
+

docs/howto/tabs/avoid-catalog-legend-overlap.rst

@@ -0,0 +1,40 @@
+How-to hide the catalog tab
+============================
+
+Sometimes administrators of a site may want the catalog tab to be minimized by 
+default. This can be useful for both small screens and for embedding your
+map in other websites. This can easily be done by making a simple edit to the
+``index.html`` file.
+
+Change index.html
+------------------------------------------
+
+In ``index.html``, find the body tag and add a tabs-closed class to it.
+
+Default site configuration with the catalog tab open by default:
+
+.. code:: html
+
+    <body>
+        <div id="main">
+            <div id="header">
+                <img height="50" src="logo.png">
+                <div id="toolbar"></div>
+            </div>
+            ...
+
+Site configuration with the catalog tab minimized. Note that there is a 
+space before tabs-closed (without the space the catalog tab is minimized
+by default, but you can't unminimize it):
+
+.. code:: html
+
+    <body class=" tabs-closed">
+        <div id="main">
+            <div id="header">
+                <img height="50" src="logo.png">
+                <div id="toolbar"></div>
+            </div>
+            ...
+
+