The Snippet Set File Format
TypeMetal stores its HTML snippet sets in a simple, open, fairly compact, JSON-based file format. The format is described here and on a dedicated page at coherencelabs.com, to enable other applications, tools, and scripts to work with TypeMetal snippet sets if they choose.
Top-Level Structure
The top-level object in a TypeMetal snippet set file is a JSON object (dictionary).
The first key-value pairs in this top-level object specify properties (metadata) that apply to the snippet set as a whole. They are followed by the snippet set’s snippet groups.
A typical snippet set file begins like this:
{
"comment" : "This is a TypeMetal HTML 'Snippet Set' file. Its format is documented at https://coherencelabs.com/typemetal-snippet-set-file-format/",
"title" : "TypeMetal Help Snippets",
"usageDescription" : "Use these snippets to compose TypeMetal's Mac OS X app Help.",
"providerDescription" : "Coherence Labs, LLC",
"infoURLString" : "https://coherencelabs.com",
"documentTypeForValidation" : "HTML 5",The “comment” property has the same string value in every snippet set file. It’s designed to help identify the file’s format to anyone who may encounter a snippet set file.
The “title”, “usageDescription”, “providerDescription”, and “infoURLString” properties are all string-valued. Their values give the snippet set a name, summarize its purpose, identify its provider, and provide a URL where one can go to read more about the snippet set and its intended usage, respectively.
The “documentTypeForValidation” property is also string-valued. It specifies the primary HTML document type for which the snippet set is intended, and against which it will show its snippets’ validation status when opened for editing in TypeMetal. For snippet sets written by or intended for use with TypeMetal 1.0, the value of “documentTypeForValidation” must be one of the following strings:
HTML 5XHTML 1.1XHTML 1.0 StrictXHTML 1.0 TransitionalHTML 4.01 StrictHTML 4.01 Transitional
Allowed Elements
The above snippet set properties are followed by an “allowedBodyElements” property whose value — an array of lowercase strings, sorted alphabetically — lists the HTML elements, selected from among those that may appear within an HTML document’s <body>, that the snippet set permits. For [a particularly restrictive] example:
"allowedBodyElements" : [
"a",
"br",
"em",
"p",
"strong"
],Lastly, the snippet set lists its snippet groups, and snippets they contain, as the value of a “groups” property in the snippet set file’s top-level object.
Groups
The value of the “groups” property is an array. Each element in that array is a JSON object (dictionary), that describes a snippet group and its contents. The order of the elements is significant — it matches the order in which the user has arranged the groups.
A “title” property gives the group’s title (as a string). A “snippets” property lists the group’s snippets in order, as an array of JSON objects.
Snippets
Each element in a snippet group’s “snippets” array is a JSON object (dictionary), that describes a single snippet. Every snippet has a “title” (a string). Depending on its complexity, the snippet is then described in one of two ways:
Simple Snippets
If a snippet consists of only a single HTML element that wraps a {content} token, and that has, at most, “class” and or “id” attributes, it may be expressed in a snippet set file as a “simple” snippet. A “tag” property specifies the HTML element’s name (as a string). If the snippet’s element has a “class” attribute, it’s specified using a “class” property. This leads to a very compact JSON expression of the snippet:
{
"title" : "Menu Item",
"tag" : "strong",
"class" : "menu-item"
},Arbitrarily Complex Snippets
Snippet content that can’t be expressed so simply as the example above are instead written to the snippet set file as an “html” property, whose string value contains the snippet’s content as HTML source code. Special characters in the snippet’s content are escaped as necessary, according to JSON’s string syntax rules.
An example of the JSON defining an arbitrary snippet:
{
"title" : "Figure",
"html" : "<figure><figcaption>{content}</figcaption></figure>"
},See (and direct your friends to) coherencelabs.com for the latest published snippet set file format specification.