move default HTML templates to root

Author: tomkralidis

default-sample.yml

@@ -43,6 +43,9 @@ server:
     #spatial_ranking: true
     #workers=2
     #timeout=30
+    # templates:
+      # path: /path/to/Jinja2/templates
+      # static: /path/to/static/folder # css/js/img
 
 logging:
     level: ERROR

docs/html-templating.rst

@@ -0,0 +1,41 @@
+.. _html-templating:
+
+HTML Templating
+===============
+
+pycsw 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 pycsw configuration has ``server.templates`` commented out and defaults to the pycsw ``pycsw/templates`` and ``pycsw/static`` folder. To point to a different set of template configuration, you can edit your configuration as follows:
+
+.. code-block:: yaml
+
+  server:
+    templates:
+      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 pycsw.
+
+Your templates folder should mimic the same file names and structure of the default pycsw templates. Otherwise, you will need to modify ``api.py`` accordingly.
+
+Note that you need only copy and edit the templates you are interested in updating.  For example,
+if you are only interested in updating the ``landing_page.html`` template, then create your own version
+of only that same file.  When pycsw detects that a custom HTML template is being used,
+it will look for the custom template in ``server.templates.path``.  If it does not exist, pycsw
+will render the default HTML template for the given endpoint/request.
+
+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/index.rst

@@ -37,6 +37,7 @@ pycsw |release| Documentation
    repositories
    outputschemas
    xslt
+   html-templating
    geonode
    hhypermap
    odc

pycsw/ogc/api/util.py

@@ -52,7 +52,7 @@
 
 DATETIME_FORMAT = '%Y-%m-%dT%H:%M:%S.%fZ'
 
-TEMPLATES = f'{os.path.dirname(os.path.realpath(__file__))}{os.sep}templates'
+TEMPLATES = f'{os.path.dirname(os.path.realpath(__file__))}{os.sep}..{os.sep}..{os.sep}templates'  # noqa
 
 STATIC = f'{TEMPLATES}/static'