From 90ab772c7cd0bc5f70597b3846da36440fc8e2d6 Mon Sep 17 00:00:00 2001 From: Kevin Ngai Date: Tue, 29 Sep 2020 19:44:00 +0000 Subject: [PATCH] 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 | 6 +++++- docs/source/html-templating.rst | 36 +++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + pygeoapi-config.yml | 3 +++ pygeoapi/flask_app.py | 10 ++++++--- pygeoapi/starlette_app.py | 12 +++++++---- pygeoapi/util.py | 8 +++++++- 7 files changed, 67 insertions(+), 9 deletions(-) create mode 100644 docs/source/html-templating.rst diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index c2cca17..a94a5e8 100644 --- a/docs/source/configuration.rst +++ b/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: 'Wikimedia maps | Map data © OpenStreetMap contributors' @@ -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 ------- diff --git a/docs/source/html-templating.rst b/docs/source/html-templating.rst new file mode 100644 index 0000000..547bd59 --- /dev/null +++ b/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 + + + + + + + + + +.. _`Jinja`: https://palletsprojects.com/p/jinja/ +.. _`Jinja documentation`: https://jinja.palletsprojects.com +.. _`Flask`: https://palletsprojects.com/p/flask/ +.. _`Flask documentation`: https://flask.palletsprojects.com \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 00c95fc..09dfce1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -28,6 +28,7 @@ pygeoapi |release| documentation openapi data-publishing/index plugins + html-templating development ogc-compliance contributing diff --git a/pygeoapi-config.yml b/pygeoapi-config.yml index ba57286..c534075 100644 --- a/pygeoapi-config.yml +++ b/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: 'Wikimedia maps | Map data © OpenStreetMap contributors' diff --git a/pygeoapi/flask_app.py b/pygeoapi/flask_app.py index fd7e0a4..5a2ec9e 100644 --- a/pygeoapi/flask_app.py +++ b/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 diff --git a/pygeoapi/starlette_app.py b/pygeoapi/starlette_app.py index ef0bdc0..d2e63f1 100644 --- a/pygeoapi/starlette_app.py +++ b/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 diff --git a/pygeoapi/util.py b/pygeoapi/util.py index b7bd85a..6191a92 100644 --- a/pygeoapi/util.py +++ b/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)