Add templates config yml split into path and static (#523)

- updated configuration.rst doc for templates config
- added docs on HTML templating; dedicated page
- typo fix in configuration.rst
- added debug logging for templates path
- added static config in starlette_app.py
- flake8 fixes

docs/source/configuration.rst

@@ -44,6 +44,9 @@ The ``server`` section provides directives on binding and high level tuning.
     cors: true  # boolean on whether server should support CORS
     pretty_print: true  # whether JSON responses should be pretty-printed
     limit: 10  # server limit on number of items to return
+    template: # optional configuration to specify a different set of templates for HTML pages. Recommend using absolute paths. Omit this to use the default provided templates
+      path: /path/to/jinja2/templates/folder # path to templates folder containing the jinja2 template HTML files
+      static: /path/to/static/folder # path to static folder containing css, js, images and other static files referenced by the template
     map:  # leaflet map setup for HTML pages
         url: https://maps.wikimedia.org/osm-intl/{z}/{x}/{y}.png
         attribution: '<a href="https://wikimediafoundation.org/wiki/Maps_Terms_of_Use">Wikimedia maps</a> | Map data &copy; <a href="https://openstreetmap.org/copyright">OpenStreetMap contributors</a>'
@@ -80,7 +83,7 @@ The ``metadata`` section provides settings for overall service metadata and desc
               - geospatial
               - data
               - api
-          keywords_type: theme  # keyword type as per the ISO 19115 MD_KeywordTypeCode codelist). Accepted values are discipline, temporal, place, theme, stratum
+          keywords_type: theme  # keyword type as per the ISO 19115 MD_KeywordTypeCode codelist. Accepted values are discipline, temporal, place, theme, stratum
           terms_of_service: https://creativecommons.org/licenses/by/4.0/  # terms of service
           url: http://example.org  # informative URL about the service
       license:  # licensing details
@@ -270,6 +273,7 @@ implementation of JSON-LD structured data is available for any data provider but
 ``@context``.  Relationships between items can be expressed but is dependent on such relationships being expressed
 by the dataset provider, not pygeoapi.
 
+
 Summary
 -------
 

docs/source/html-templating.rst

@@ -0,0 +1,36 @@
+.. _html-templating:
+
+HTML Templating
+===============
+
+pygeoapi uses `Jinja`_ as its templating engine to render HTML and `Flask`_ to provide route paths of the API that returns HTTP responses. For complete details on how to use these modules, refer to the `Jinja documentation`_ and the `Flask documentation`_.
+
+The default pygeoapi configuration has ``server.template`` commented out and defaults to the pygeoapi ``pygeoapi/templates`` and ``pygeoapi/static`` folder. To point to a different set of template configuration, you can edit your configuration:
+
+.. code-block:: yaml
+
+  server:
+    template:
+      path: /path/to/jinja2/templates/folder # jinja2 template HTML files
+      static: /path/to/static/folder # css, js, images and other static files referenced by the template
+
+**Note:** the URL path to your static folder will always be ``/static`` in your deployed web instance of pygeoapi.
+
+Your templates folder should mimic the same file names and structure of the default pygeoapi templates. Otherwise, you will need to modify ``api.py`` accordingly.
+
+Linking to a static file in your HTML templates can be done using Jinja syntax and the exposed ``config['server']['url']``:
+
+.. code-block:: html
+
+  <!-- CSS example -->
+  <link rel="stylesheet" href="{{ config['server']['url'] }}/static/css/default.css">
+  <!-- JS example -->
+  <script src="{{ config['server']['url'] }}/static/js/main.js"></script>
+  <!-- Image example with metadata -->
+  <img src="{{ config['server']['url'] }}/static/img/logo.png" title="{{ config['metadata']['identification']['title'] }}" />
+
+
+.. _`Jinja`: https://palletsprojects.com/p/jinja/
+.. _`Jinja documentation`: https://jinja.palletsprojects.com
+.. _`Flask`: https://palletsprojects.com/p/flask/
+.. _`Flask documentation`: https://flask.palletsprojects.com

docs/source/index.rst

@@ -28,6 +28,7 @@ pygeoapi |release| documentation
    openapi
    data-publishing/index
    plugins
+   html-templating
    development
    ogc-compliance
    contributing

pygeoapi-config.yml

@@ -38,6 +38,9 @@ server:
     # cors: true
     pretty_print: true
     limit: 10
+    # templates:
+      # path: /path/to/Jinja2/templates
+      # static: /path/to/static/folder # css/js/img
     map:
         url: https://maps.wikimedia.org/osm-intl/{z}/{x}/{y}.png
         attribution: '<a href="https://wikimediafoundation.org/wiki/Maps_Terms_of_Use">Wikimedia maps</a> | Map data &copy; <a href="https://openstreetmap.org/copyright">OpenStreetMap contributors</a>'

pygeoapi/flask_app.py

@@ -39,9 +39,6 @@ from flask import Flask, Blueprint, make_response, request, send_from_directory
 from pygeoapi.api import API
 from pygeoapi.util import get_mimetype, yaml_load
 
-APP = Flask(__name__)
-APP.url_map.strict_slashes = False
-
 routes = Blueprint('pygeoapi', __name__)
 
 CONFIG = None
@@ -52,6 +49,13 @@ if 'PYGEOAPI_CONFIG' not in os.environ:
 with open(os.environ.get('PYGEOAPI_CONFIG'), encoding='utf8') as fh:
     CONFIG = yaml_load(fh)
 
+STATIC_FOLDER = 'static'
+if 'templates' in CONFIG['server']:
+    STATIC_FOLDER = CONFIG['server']['templates'].get('static', 'static')
+
+APP = Flask(__name__, static_folder=STATIC_FOLDER, static_url_path='/static')
+APP.url_map.strict_slashes = False
+
 # CORS: optionally enable from config.
 if CONFIG['server'].get('cors', False):
     from flask_cors import CORS

pygeoapi/starlette_app.py

@@ -44,10 +44,6 @@ import uvicorn
 from pygeoapi.api import API
 from pygeoapi.util import yaml_load
 
-app = Starlette()
-app.mount('/static', StaticFiles(
-    directory='{}{}static'.format(os.path.dirname(os.path.realpath(__file__)),
-                                  os.sep)))
 CONFIG = None
 
 if 'PYGEOAPI_CONFIG' not in os.environ:
@@ -56,6 +52,14 @@ if 'PYGEOAPI_CONFIG' not in os.environ:
 with open(os.environ.get('PYGEOAPI_CONFIG'), encoding='utf8') as fh:
     CONFIG = yaml_load(fh)
 
+STATIC_DIR = '{}{}static'.format(os.path.dirname(os.path.realpath(__file__)),
+                                 os.sep)
+if 'templates' in CONFIG['server']:
+    STATIC_DIR = CONFIG['server']['templates'].get('static', STATIC_DIR)
+
+app = Starlette()
+app.mount('/static', StaticFiles(directory=STATIC_DIR))
+
 # CORS: optionally enable from config.
 if CONFIG['server'].get('cors', False):
     from starlette.middleware.cors import CORSMiddleware

pygeoapi/util.py

@@ -227,7 +227,13 @@ def render_j2_template(config, template, data):
     :returns: string of rendered template
     """
 
-    env = Environment(loader=FileSystemLoader(TEMPLATES))
+    try:
+        templates_path = config['server']['templates']['path']
+        env = Environment(loader=FileSystemLoader(templates_path))
+        LOGGER.debug('using custom templates: {}'.format(templates_path))
+    except (KeyError, TypeError):
+        env = Environment(loader=FileSystemLoader(TEMPLATES))
+        LOGGER.debug('using default templates: {}'.format(TEMPLATES))
 
     env.filters['to_json'] = to_json
     env.globals.update(to_json=to_json)