Create blog post for GML dictionary (and other components) rendering

_posts/2024-08-21-command-gml-dictionary.adoc

@@ -0,0 +1,250 @@
+---
+layout: post
+title: "Rendering GML Dictionary objects"
+date: 2024-08-21
+categories: documentation
+
+authors:
+  - name: Kwan Koon Wa
+    email: kw.kwan@ribose.com
+    use_picture: assets
+    social_links:
+    - https://github.com/kwkwan
+
+excerpt: >-
+  Render GML Dictionary files using the new command `lutaml_gml_dictionary`.
+---
+
+== Introduction
+
+New Metanorma work for the https://www.mlit.go.jp[MLIT]
+https://www.mlit.go.jp/plateau/[Project PLATEAU] yielded a new
+command now generally available to all Metanorma users.
+
+The `lutaml_gml_dictionary` is a command for rendering the
+https://www.ogc.org/standard/gml/[Geography Markup Language (GML)] Dictionary
+object type.
+
+
+== Geography Markup Language (GML)
+
+Geography Markup Language (GML) is an XML-based language developed by the Open
+Geospatial Consortium (OGC) used for describing geographic features and their
+attributes, providing a standard way to represent and exchange geographic data
+between different systems.
+
+The latest version, GML 3.2, has been standardized as https://www.iso.org/standard/32554.html[ISO 19136:2007, Geographic information — Geography Markup Language (GML)]
+
+GML's `Dictionary` is a GML object type that provides a mechanism for defining
+terms and their meanings in a GML application schema. It is used to define
+terms and their meanings in a GML application schema, providing a mechanism for
+defining terms and their meanings in a GML application schema.
+
+== Data encoding samples
+
+In the following examples we will refer to GML dictionary files from the Japan
+"i-Urban Revitalization" ("i-UR") project
+https://www.chisou.go.jp/tiiki/toshisaisei/itoshisaisei/iur/index.html[i-UR XML library 3.1].
+
+.Snippet of a GML dictionary from i-UR 3.1 `Building_class.xml`
+[example]
+====
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<gml:Dictionary xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:gml="http://www.opengis.net/gml" xsi:schemaLocation="http://www.opengis.net/gml http://schemas.opengis.net/gml/3.1.1/profiles/SimpleDictionary/1.0.0/gmlSimpleDictionaryProfile.xsd" gml:id="cl_c9fa7a39-966f-4ee4-8102-91fb15ad2dd3">
+  <gml:name>Building_class</gml:name>
+  <gml:dictionaryEntry>
+    <gml:Definition gml:id="Building_class_1">
+      <gml:description>普通建物</gml:description>
+      <gml:name>3001</gml:name>
+    </gml:Definition>
+  </gml:dictionaryEntry>
+  <gml:dictionaryEntry>
+    <gml:Definition gml:id="Building_class_2">
+      <gml:description>堅ろう建物</gml:description>
+      <gml:name>3002</gml:name>
+    </gml:Definition>
+  </gml:dictionaryEntry>
+  <gml:dictionaryEntry>
+    <gml:Definition gml:id="Building_class_3">
+      <gml:description>普通無壁舎</gml:description>
+      <gml:name>3003</gml:name>
+    </gml:Definition>
+  </gml:dictionaryEntry>
+  <gml:dictionaryEntry>
+    <gml:Definition gml:id="Building_class_4">
+      <gml:description>堅ろう無壁舎</gml:description>
+      <gml:name>3004</gml:name>
+    </gml:Definition>
+  </gml:dictionaryEntry>
+  <gml:dictionaryEntry>
+    <gml:Definition gml:id="Building_class_5">
+      <gml:description>分類しない建物</gml:description>
+      <gml:name>3000</gml:name>
+    </gml:Definition>
+  </gml:dictionaryEntry>
+</gml:Dictionary>
+----
+====
+
+
+== Command
+
+The `lutaml_gml_dictionary` command allows you to iterate this dictionary and
+pass it to a Liquid template for rendering.
+
+The Liquid template can be specified as a block or as a file path to an external
+file.
+
+To render the GML Dictionary, you can use `lutaml_gml_dictionary` by specifying
+the path of the GML Dictionary file and the liquid template.
+
+Syntax:
+
+.Using `lutaml_gml_dictionary` with external template
+[source,adoc]
+-----
+lutaml_gml_dictionary::{path-to-dictionary}[template={path-to-template},context={context-var}]
+-----
+
+The command accepts the options listed below:
+
+`{path-to-dictionary}`:: specifies the path of XML file of the
+GML Dictionary.
++
+.Rendering the GML Dictionary from `Building_class.xml`
+[example]
+====
+[source,adoc]
+----
+lutaml_gml_dictionary::/path/to/Building_class.xml[...]
+----
+====
+
+`{path-to-template}`:: specifies the liquid template.
++
+.Rendering the GML Dictionary using an external Liquid template
+[example]
+====
+[source,adoc]
+----
+lutaml_gml_dictionary::/path/to/Building_class.xml[template="/path/to/template.liquid",...]
+----
+====
+
+`context={dict}`:: define the context in the template. The context is used to access
+the `Liquid::Drop` object inside Liquid template.
++
+.Rendering the GML Dictionary with the context object set to `dict`
+[example]
+====
+[source,adoc]
+----
+lutaml_gml_dictionary::/path/to/Building_class.xml[template="/path/to/template.liquid",context=dict]
+----
+====
+
+Alternatively, it can be specified as a block.
+
+Syntax:
+
+.Using `lutaml_gml_dictionary` with supplied block as template
+[source,adoc]
+----
+[lutaml_gml_dictionary,"{path-to-dictionary}",context={context-var}]
+--
+// content of Liquid template
+--
+----
+
+
+.Using `lutaml_gml_dictionary` with a file path to the Liquid template
+[example]
+====
+[source,adoc]
+----
+[lutaml_gml_dictionary,"/path/to/dictionary.xml",context=dict]
+--
+{% capture link %}https://www.test.com/{{ dict.file_name }}{% endcapture %}
+[cols="3a,22a"]
+|===
+| File Name | {{ dict.file_name }}
+h| URL | {{ link }}
+
+h| Code h| Description
+{% for entry in dict.dictionary_entry %}
+| {{ entry.name }} | {{ entry.description }}
+{% endfor %}
+|===
+--
+----
+====
+
+
+== Liquid template and context object
+
+Internally, the GML Dictionary object is passed into the Liquid template using a
+`Liquid::Drop` model named `GmlDictionaryDrop`.
+
+`GmlDictionaryDrop` has the following attributes:
+
+`name`:: Name of the GML Dictionary
+`file_name`:: File name of the GML Dictionary file
+`dictionary_entry`:: Array of `dictionaryEntry` objects
+`name`::: Name of the `dictionaryEntry` object (`name`)
+`description`::: Description of the `dictionaryEntry` object (`description`)
+
+.`GmlDictionaryDrop` object of `Building_class.xml`
+[example]
+====
+The `GmlDictionaryDrop` object of the `Building_class.xml` file will provide:
+
+* The `name` of the GML Dictionary is `Building_class`.
+* The `file_name` of the GML Dictionary is `Building_class.xml`.
+* It has five dictionary entries:
+** The `name` and `description` of the first `dictionary_entry` are `3001` and
+`普通建物`.
+====
+
+Here's an example of a Liquid template file to show the GML Dictionary in a table.
+
+.Liquid template that renders the GML Dictionary into a table
+[example]
+====
+This template:
+
+[source,liquid]
+-----
+[cols="3a,22a"]
+|===
+| Name | {{ dict.file_name }}
+h| Code h| Description
+{% for entry in dict.dictionary_entry %}
+| {{ entry.name }} | {{ entry.description }}
+{% endfor %}
+|===
+-----
+
+Renders the GML Dictionary into the following table:
+
+[cols="3a,22a"]
+|===
+| Name | Building_class.xml
+h| Code h| Description
+| 3001 | 普通建物
+| 3002 | 堅ろう建物
+| 3003 | 普通無壁舎
+| 3004 | 堅ろう無壁舎
+| 3000 | 分類しない建物
+|===
+
+====
+
+
+== Conclusion
+
+Questions or suggestions, please feel free to file an issue at
+the https://github.com/metanorma/metanorma-plugin-lutaml[metanorma-plugin-lutaml]
+repository at GitHub!