Introduction
A Carafe Bundle is a JSON document that encapsulates everything needed to develop, share, and deploy JavaScript in a FileMaker WebViewer.
A Carafe Bundle has a formal schema which can be validated using JSON Schema, a vocabulary that allows us to annotate and validate JSON documents.
The formal schema allows all the Carafe tooling (and any other tooling that understand JsonSchema such as many code editors) to validate Bundles.
Over time as the format of Bundles changes, having a schema definition will allow code editors and other tooling to properly handle different schemas of Bundles over time without confusion and/or backward compatibility breaks.
Details
The current JsonSchema Bundle schema canonical id is https://carafe.fm/schema/draft-01/bundle.schema.json
In plain English, the core properties of a Bundle are as follows:
-
html
- A template which contains merge fields which match the top level property names defined in
config
. - Typically, in addition to HTML and merge fields, this template will contain JavaScript, CSS.
- When merged properly, the resulting valid HTML document provides some display or interactivity as designed.
- A template which contains merge fields which match the top level property names defined in
-
config
-
An Object with properties describing rules for each of the merge fields in
html
.isData
false
- SHOULD NOT be included in the
data
Object. - MUST be merged at compile time.
- MUST NOT be merged by a deployed FileMaker script at runtime.
- SHOULD NOT be included in the
true
- MUST be included in the
data
Object with sample data. - MUST be merged by a FileMaker script at run time.
- MUST be included in the
value
- MUST NOT be empty when
isData
isfalse
- MUST NOT be empty when
help
- MAY be included to clarify the purpose of the property.
category
- MAY be included to group the property in tooling which recognizes it.
label
- MAY be included to label the property in tooling which recognizes it.
sort
- MAY be included to sort the property in tooling which recognizes it.
type
- MAY be use of the following values for compatibility with WidgetStudio, but not enforced by the validator. See Config Example below for usage examples.
booleanCheck
json array
json object
number
text
CSS Snippet
HTML Snippet
JS Snippet
color
padding
textAlign
verticalAlign
fmpFileName
fmpScriptName
dropdown
popup
- MAY be use of the following values for compatibility with WidgetStudio, but not enforced by the validator. See Config Example below for usage examples.
possibleValues
- MAY be included with
dropdown
orpopup
properties in tooling which recognizes it.
- MAY be included with
- Additional miscellaneous keys
- MAY be included to support tooling which recognize them.
-
Config sub-schema canonical id is
https://carafe.fm/schema/draft-01/config.schema.json
-
-
data
- A Object with properties containing sample data for each of the merge fields which are specified as requiring example data, and which MUST BE merged by FileMaker at run time.
- Data sub-schema canonical id is
https://carafe.fm/schema/draft-01/data.schema.json
-
meta
-
Several additional properties which define details about how to merge and deploy the three core properties, as well as information about creator, version, description, etc.
bookend
- A string used as a delimiter for the merge fields. The default bookend is a pair of underscore characters, but can be defined as needed so as not to collide with code in the html template.
about
- REQUIRED explanation about how to implement. May contain simple HTML markup.
description
- REQUIRED text description of the purpose of the bundle.
id
- REQUIRED GUID/UUID
creator
category
name
version
- REQUIRED string attribution and identification properties
hashLoad
offlineCompatibile
windowsTested
- REQUIRED loosely typed Boolean properties as defined in
https://carafe.fm/schema/draft-01/bundle.schema.json#/definitions/boolean
- REQUIRED loosely typed Boolean properties as defined in
bridgeAPIMethods
- REQUIRED JSON Object containing zero or more bridge method definitions. See schema and/or example below for more details.
-
references
- REQUIRED JSON Array containing zero or more URIs to developer references.
-
Any additional meta properties added to a Bundle are valid but will ignored by Carafe
- Meta sub-schema canonical id is
https://carafe.fm/schema/draft-01/meta.schema.json
- Meta sub-schema canonical id is
-
-
preview
previewName
- Contains a Base64 encoded jpg image and the filename for it.
Config Example
This is a complex example showing many examples of config properties as might be generated by other tooling and still be valid Carafe config schema draft-01.
{
"$schema" : "https://carafe.fm/schema/draft-01/config.schema.json#",
"booleanVar": {
"category": "General Inputs",
"help": "Optional help text. Values should be string keywords \"true\" or \"false\"",
"isData": false,
"label": "Boolean",
"sort": "1",
"type": "booleanCheck",
"value": "false"
},
"colorVar": {
"category": "Style",
"help": "Optional help text.",
"isData": false,
"label": "Color",
"sort": "1",
"type": "color",
"value": "rgba(121,121,121,1)"
},
"cssSnippetVar": {
"category": "Snippets",
"help": "Optional help text.",
"isData": false,
"label": "CSS",
"sort": "2",
"type": "CSS Snippet",
"value": ".selector: { height: 100%; }"
},
"dropdownVar": {
"category": "General Inputs",
"help": "Optional help text. Enumerated list which expects other values.",
"isData": false,
"label": "Dropdown",
"possibleValues": [
"Baz",
"Bat"
],
"sort": "4",
"type": "dropdown",
"value": "Baz"
},
"fmpFileNameVar": {
"calculation": "Get(FileName)",
"category": "FileMaker",
"help": "Optional help text.",
"isData": false,
"label": "FMP File Name",
"sort": "1",
"type": "fmpFileName",
"value": "Carafe"
},
"fmpScriptNameVar": {
"category": "FileMaker",
"help": "Optional help text.",
"isData": false,
"label": "FMP Script Name",
"lengthSafeParam": true,
"parameterData": {
"theKey": "This is the explainer of theKey"
},
"sort": "2",
"type": "fmpScriptName",
"value": "My Script"
},
"htmlSnippetVar": {
"category": "Snippets",
"help": "Optional help text.",
"isData": false,
"label": "HTML Snippet",
"sort": "1",
"type": "HTML Snippet",
"value": "<h1>Some HTML</h1>"
},
"jsSnippetVar": {
"category": "Snippets",
"help": "Optional help text.",
"isData": false,
"label": "JS Snippet",
"sort": "3",
"type": "JS Snippet",
"value": "alert('jsSnippetVar ran.');"
},
"jsonArrayVar": {
"category": "JSON",
"help": "Optional help text.",
"isData": true,
"label": "JSON Array",
"sort": "1",
"type": "json array"
},
"jsonObjectVar": {
"category": "JSON",
"help": "Optional help text.",
"isData": true,
"label": "JSON Object",
"sort": "2",
"type": "json object"
},
"numberVar": {
"category": "General Inputs",
"help": "Optional help text.",
"isData": false,
"label": "Number",
"sort": "2",
"type": "number",
"value": 3.14
},
"paddingVar": {
"category": "Style",
"help": "Optional help text.",
"isData": false,
"label": "Padding",
"sort": "2",
"type": "padding",
"value": "1px 2px 3px 4px"
},
"popupVar": {
"category": "General Inputs",
"help": "Optional help text. Enumerated list which expects only enumerated values.",
"isData": false,
"label": "Popup",
"possibleValues": [
"Foo",
"Bar"
],
"sort": "5",
"type": "popup",
"value": "Foo"
},
"textAlignVar": {
"category": "Style",
"help": "Optional help text.",
"isData": false,
"label": "Text Align",
"sort": "3",
"type": "textAlign",
"value": "left"
},
"textVar": {
"category": "General Inputs",
"help": "Optional help text.",
"isData": true,
"label": "Text",
"sort": "3",
"type": "text"
},
"verticalAlignVar": {
"category": "Style",
"help": "Optional help text.",
"isData": false,
"label": "Vertical Align",
"sort": "4",
"type": "verticalAlign",
"value": "top"
}
}
Meta bridgeAPIMethods Example
This is an example showing how the meta property might be generated by other tooling and still be valid Carafe meta schema draft-01.
// snip
"bridgeAPIMethods": {
"exampleBridgeMethodName": {
"callback": false,
"description": "Bridge method with no callback"
},
"exampleBridgeMethodWithCallbackName": {
"callback": true,
"description": "Bridge method with callback modified"
}
},
// snip
Compatibility
Carafe tooling does not require Bundles to declare a schema. It will duck-type any bundle that does not declare a schema and attempt to validate it anyway.
Contributing
It is our intent by defining a schema for Bundles to facilitate stronger interoperability of tools. We encourage community dialog about what the schema definition should be. In draft-01 we have kept the constraints quite loose in an attempt to facilitate maximum interoperability.
Discussion and contributions encouraged in the Carafe Bundler project on GitHub