############################## Creating HTML Export Templates ############################## The HTML export templates are used to allow search results in Arches to be exported as a set of html files containing formatted report styled documents. They are designed to be be read offline by embedding a small CSS framework called Milligram, along with some additional elements. The templates must be written by a developer and added to the Arches project template folder. There can only be one HTML export template for each model in the application. Template Location ================= The templates should be saved to a folder in ``/path/to/project_workspace/project_name/project_name/templates/html_export``. The templates must have the name format of ``.htm``, with the value being the model's UUID. **example**: ``076f9381-7b00-11e9-8d6b-80000b44d1d9.htm`` Templating Language =================== The templates are using the native Django templating engine, information of which can be found here: https://docs.djangoproject.com/en/stable/ref/templates/language/ Resources Context Data ====================== When the export process loads the template ready for it to be rendered, it will be passed a ``resources`` context object that contains the data for the resources to be written. This list is then iterated to build each record. The structure of each resources object is as below: .. code-block:: JSON { "displaydescription": " Excavation by Department Of Greater London Archaeology, April to May 1990, found a large 'soft spot' which was either a quarry ditch or was dug for dumping waste. Also uncovered features of 20th century date relating to a building called Green Acres.", "displayname": "Open Area Excavation at Lichfield Gardens", "graph_id": "b9e0701e-5463-11e9-b5f5-000d3ab1e588", "legacyid": "06eb7a47-baf7-4c79-aeab-2ffabe2502ea", "map_popup": "", "resource": { "...": "..." }, "resourceinstanceid": "06eb7a47-baf7-4c79-aeab-2ffabe2502ea" } Some id and display information is directly accessible from the object, such as the ``displayname`` and ``displaydescription``. The rest of the resource data is contained in the ``resource`` dictionary as a "disambiguated" version of the resource. The dict uses the branch/card/node names as the keys, with the ``@display_value`` key containing the presentation value for that node. There are other values included in the dicts that can be used to add richer functionality if needed. .. note:: This structure closely matches the JSON produced when looking at a resource when specifying the ``format=json&v=beta`` .. code-block:: bash curl http://localhost:8000/resources/?format=json&v=beta Ensure that you use the ``v=beta`` parameter as the functionality is using this version of the data formatting. .. code-block:: javascript "resource": { "Descriptions": [{ "Description": { "@display_value": "Amendment date:none" }, "Description Language": { "Description Language Metatype": null }, "Description Type": { "@display_value": "Notes", "Description Metatype": null, "concept_id": "f1cbae8f-0090-47dc-8252-ee533a2deb29", "language_id": "en", "value": "Notes", "valueid": "daa4cddc-8636-4842-b836-eb2e10aabe18", "valuetype_id": "prefLabel" } } ], "Designation and Protection Assignment": [], "Heritage Area Names": [], "Location Data": {}, "System Reference Numbers": {} } Custom Template Filters ======================= The resources context data sent to the templates has an incompatibility with the standard Django dot notation for accessing values. Usually you would access a dictionary value using ``dict.key``, but the resource dictionary uses keys with spaces that can't be parsed ``resource_data.Activity Names``. The other difficulty is that the resource dictionary may not contain the key you are looking for if no tiles for that data exists. Therefore, you need to check for the existence of the key before you access it. To solve this, two new template filters were added to ``arches/arches/templatetags/template_tags.py``: **has_key** You can use `has_key` as part of an `if` tag to check if there is a key in the object. If you try to access the object without checking then it may error should the key not be present. .. code-block:: HTML {% if asset_names|has_key:"Asset Name Use Type" %} {# you can access without error asset_names["Asset Name Use Type"] #} {% endif %} **val_from_key** This function allows you to retrieve a value from a key that is not Django templating compliant. These can be chained to access nested dictionaries (careful that you a sure the nested dictionary exists). .. code-block:: HTML

{{ asset_names|val_from_key:"Asset Name"|val_from_key:"@display_value" }}

**json_to_obj** This function can be used in the rare instance where the value is JSON and you need to convert that to a dict or list in order to access the values. .. code-block:: HTML Document Link **example** combining ``has_key`` and ``val_from_key``. .. code-block:: HTML {% if asset_names|has_key:"Asset Name Use Type" %}

{{ asset_names|val_from_key:"Asset Name"|val_from_key:"@display_value" }}

{% endif %} **example** of using chained filters to access nested values .. code-block:: HTML Primary Reference Number: {{ resource_data|val_from_key:"System Reference Numbers"|val_from_key:"PrimaryReferenceNumber"|val_from_key:"Primary Reference Number"|val_from_key:"@display_value" }} **example** transforming a url dataype value into a dict for use within a data table call .. code-block:: HTML
{% with exref|val_from_key:"URL"|val_from_key:"@display_value"|json_to_obj as URL_Dict %} {% if URL_Dict|has_key:"url" and URL_Dict|has_key:"url_label" %} {{ URL_Dict|val_from_key:'url_label' }} {% else %}
{% endif %} {% endwith %}
Basic Template ============== The basic template below will provide the CSS framework, add the custom template tags (used to add custom functions to the template engine), and the initial resource loop within which to start your document. .. code-block:: HTML {% load template_tags %} --ADD DOCUMENT TITLE--

--ADD MAIN HEADER TITLE--

{% for resource in resources %}

{{ resource.displayname }}

{{ resource.displaydesicription }}

{% with resource_data=resource.resource %} ... build template {% endwith %} {% endfor %}
Below show examples of how you can fetch specific data out of the resource object to build a section of the document. .. code-block:: HTML {% with resource_data=resource.resource %}
{% if resource_data|has_key:"Heritage Asset Names" %} {% for n in resource_data|val_from_key:"Heritage Asset Names" %} {% if n|has_key:"Asset Name Use Type" %} {% if n|val_from_key:"Asset Name Use Type"|val_from_key:"@display_value" == "Primary" %}

{{ n|val_from_key:"Asset Name"|val_from_key:"@display_value" }}

{% endif %} {% endif %} {% endfor %} {% endif%}

Primary Reference Number: {{ resource_data|val_from_key:"System Reference Numbers"|val_from_key:"PrimaryReferenceNumber"|val_from_key:"Primary Reference Number"|val_from_key:"@display_value" }}

{% endwith %} Advanced Template Example ========================= Below is an example that includes sections that build tables and group elements together. .. note:: Use ``
`` blocks around tables and other iterated sections to force the styling to keep things on the same page where possible when printing. .. code-block:: HTML {% load template_tags %} Report

Heritage Assets

{% for resource in resources %} {% with resource_data=resource.resource %}
{% if resource_data|has_key:"Heritage Asset Names" %} {% for n in resource_data|val_from_key:"Heritage Asset Names" %} {% if n|has_key:"Asset Name Use Type" %} {% if n|val_from_key:"Asset Name Use Type"|val_from_key:"@display_value" == "Primary" %}

{{ n|val_from_key:"Asset Name"|val_from_key:"@display_value" }}

{% endif %} {% endif %} {% endfor %} {% endif%}

Primary Reference Number: {{ resource_data|val_from_key:"System Reference Numbers"|val_from_key:"PrimaryReferenceNumber"|val_from_key:"Primary Reference Number"|val_from_key:"@display_value" }}
ResourceID: {{ resource_data.resourceinstanceid }}

{% if resource_data|has_key:"Location Data" %}

OSGB Reference

{% if resource_data|val_from_key:"Location Data"|has_key:"National Grid References" %} {{ resource_data|val_from_key:"Location Data"|val_from_key:"National Grid References"|val_from_key:"National Grid Reference"|val_from_key:"@display_value" }} {% endif %}

Named Location

{% if resource_data|val_from_key:"Location Data"|has_key:"Addresses" %} {% for address in resource_data|val_from_key:"Location Data"|val_from_key:"Addresses"|val_from_key:"@display_value" %} {% if address|has_key:"Address Status" %} {% if address|val_from_key:"Address Status"|val_from_key:"@display_value" == "Primary" %} {{ address|val_from_key:"Full Address"|val_from_key:"@display_value" }} {% endif %} {% endif %} {% endfor %} {% endif %}

Localities/Administrative Areas

{% if resource_data|val_from_key:"Location Data"|has_key:"Localities/Administrative Areas" %} {% for area in resource_data|val_from_key:"Location Data"|val_from_key:"Localities/Administrative Areas" %} {{ area|val_from_key:"Area Type"|val_from_key:"@value" }}: {{ area|val_from_key:"Area Names"|val_from_key:"Area Name"|val_from_key:"@display_value" }} {% endfor %} {% endif %}

{% endif %}
{% if resource_data|has_key:"Descriptions" %}
{% for desc in resource_data|val_from_key:"Descriptions" %}

{{ desc|val_from_key:"Description Type"|val_from_key:"@display_value" }}

{{ desc|val_from_key:"Description"|val_from_key:"@display_value" }}

{% endfor %}
{% endif %} {% if resource_data|has_key:"External Cross References" %}

External Cross References

Number
Description
Source
{% for src in resource_data|val_from_key:"External Cross References" %}
{{ src|val_from_key:"External Cross Reference Number"|val_from_key:"@display_value" }}
{% if src|has_key:"External Cross Reference Notes" %} {{ src|val_from_key:"External Cross Reference Notes"|val_from_key:"External Cross Reference Description"|val_from_key:"@display_value" }} {% endif %}
{{ src|val_from_key:"External Cross Reference Source"|val_from_key:"@display_value" }}
{% endfor %}
{% endif %}
{% endwith%} {% endfor %}