From a9b0c5d7ffe9ccbb30875ae8e81ff09fdd615d0e Mon Sep 17 00:00:00 2001 From: "jeremy@jermolene.com" Date: Mon, 23 May 2022 09:14:02 +0100 Subject: [PATCH] Cherry-pick JSON docs improvements from #6522 --- .../tiddlers/concepts/DataTiddlers.tid | 25 ++----- .../tiddlers/concepts/DictionaryTiddlers.tid | 5 +- .../tiddlers/concepts/JSONTiddlers.tid | 7 +- .../JavaScript Object Notation.tid | 8 +-- .../tiddlers/features/JSON in TiddlyWiki.tid | 69 +++++++++++++++++++ .../howtos/Constructing JSON tiddlers.tid | 16 +++++ .../howtos/Modifying JSON tiddlers.tid | 18 +++++ .../Reading data from JSON tiddlers.tid | 25 +++++++ .../tiddlers/macros/JsonTiddlersMacro.tid | 6 +- .../tiddlers/macros/jsontiddler Macro.tid | 4 +- .../tiddlers/widgets/JSONTiddlerWidget.tid | 11 +-- 11 files changed, 152 insertions(+), 42 deletions(-) create mode 100644 editions/tw5.com/tiddlers/features/JSON in TiddlyWiki.tid create mode 100644 editions/tw5.com/tiddlers/howtos/Constructing JSON tiddlers.tid create mode 100644 editions/tw5.com/tiddlers/howtos/Modifying JSON tiddlers.tid create mode 100644 editions/tw5.com/tiddlers/howtos/Reading data from JSON tiddlers.tid diff --git a/editions/tw5.com/tiddlers/concepts/DataTiddlers.tid b/editions/tw5.com/tiddlers/concepts/DataTiddlers.tid index af1cda446..dc100a37e 100644 --- a/editions/tw5.com/tiddlers/concepts/DataTiddlers.tid +++ b/editions/tw5.com/tiddlers/concepts/DataTiddlers.tid @@ -1,7 +1,8 @@ -created: 201308291647 -modified: 201308291647 +created: 20130829164700000 +modified: 20220427171321793 tags: Concepts title: DataTiddlers +type: text/vnd.tiddlywiki A data tiddler is a miniature database contained within a tiddler. @@ -12,22 +13,4 @@ There are two standard formats: Other formats of tiddler can also be parsed to yield blocks of data that behave like data tiddlers. -Use a TextReference to look up the value of a named property. For example, if a [[DictionaryTiddler|DictionaryTiddlers]] called `MonthDays` contains: - -``` -oct:31 -nov:30 -dec:31 -``` - -... then `{{MonthDays##nov}}` will resolve to the value `30`. - -The same is true if `MonthDays` is a [[JSONTiddler|JSONTiddlers]] with the following content: - -``` -{"oct":31,"nov":30,"dec":31} -``` - -Note: //It is currently only possible to retrieve data from the immediate properties of the root object of a JSONTiddler.// - -The widgets ActionSetFieldWidget and ActionListopsWidget can manipulate named properties of data tiddlers by indicating the name of the property in the $index attribute. To create or modify a named property with ActionSetFieldWidget, provide a $value attribute. To delete a named property with ActionSetFieldWidget, omit the $value attribute. ActionListopsWidget assigns the named property the list constructed through its $filter and $subfilter attributes. +See [[JSON in TiddlyWiki]] for an overview. diff --git a/editions/tw5.com/tiddlers/concepts/DictionaryTiddlers.tid b/editions/tw5.com/tiddlers/concepts/DictionaryTiddlers.tid index 33a0a65cd..a1f1d6668 100644 --- a/editions/tw5.com/tiddlers/concepts/DictionaryTiddlers.tid +++ b/editions/tw5.com/tiddlers/concepts/DictionaryTiddlers.tid @@ -1,9 +1,10 @@ created: 20141228094500000 -modified: 20180305111822713 +modified: 20220427171020974 tags: Concepts title: DictionaryTiddlers +type: text/vnd.tiddlywiki -A dictionary tiddler is a [[data tiddler|DataTiddlers]] containing a simple list of `name: value` pairs. +A dictionary tiddler is a kind of [[data tiddler|DataTiddlers]] that contains a simple list of `name: value` pairs. Its [[ContentType]] is `application/x-tiddler-dictionary`. diff --git a/editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid b/editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid index 259b4a49f..caffd063c 100644 --- a/editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid +++ b/editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid @@ -1,10 +1,11 @@ created: 20141228094500000 -modified: 20150221152956000 +modified: 20220427171219408 tags: Concepts title: JSONTiddlers +type: text/vnd.tiddlywiki -A JSON tiddler is a [[data tiddler|DataTiddlers]] containing a [[JSON|JavaScript Object Notation]] structure in its `text` field. +A JSON tiddler is a [[data tiddler|DataTiddlers]] containing a [[JSON|JavaScript Object Notation]] structure in its `text` field. See [[JSON in TiddlyWiki]] for an overview. Its [[ContentType]] is `application/json`. -The [[history list|$:/HistoryList]] is a good example of a JSON tiddler. +The [[history list|$:/HistoryList]] is an of a JSON tiddler. diff --git a/editions/tw5.com/tiddlers/definitions/JavaScript Object Notation.tid b/editions/tw5.com/tiddlers/definitions/JavaScript Object Notation.tid index 91e2ff5ac..c0a9a6ea9 100644 --- a/editions/tw5.com/tiddlers/definitions/JavaScript Object Notation.tid +++ b/editions/tw5.com/tiddlers/definitions/JavaScript Object Notation.tid @@ -1,11 +1,7 @@ created: 20150221152904000 -modified: 20150221181720000 +modified: 20220427170920772 tags: Definitions title: JavaScript Object Notation type: text/vnd.tiddlywiki -<<.dlink-ex JSON "https://en.wikipedia.org/wiki/JSON">> is a standard plain-text format used for modelling hierarchical structures of objects that contain named fields. - -DataTiddlers can have JSON content. - -The <<.mlink jsontiddlers>> macro returns tiddler content in JSON format. +<<.dlink-ex JSON "https://en.wikipedia.org/wiki/JSON">> is a standard plain-text format used for modelling hierarchical structures of objects that contain named fields. See [[JSON in TiddlyWiki]] for an overview. diff --git a/editions/tw5.com/tiddlers/features/JSON in TiddlyWiki.tid b/editions/tw5.com/tiddlers/features/JSON in TiddlyWiki.tid new file mode 100644 index 000000000..2f2edd09f --- /dev/null +++ b/editions/tw5.com/tiddlers/features/JSON in TiddlyWiki.tid @@ -0,0 +1,69 @@ +title: JSON in TiddlyWiki +tags: Features +type: text/vnd.tiddlywiki +created: 20220427174702859 +modified: 20220427174702859 + +!! Introduction + +JSON (~JavaScript Object Notation) is a standardised text representation for data structures that is widely used for the storage and transfer of data. + +JSON is used in several different contexts in TiddlyWiki. For example: + +* Tiddlers are represented as JSON data within TiddlyWiki HTML files +* Groups of tiddlers can be [[exported|How to export tiddlers]] and [[imported|Importing Tiddlers]] as JSON files +* Plugin tiddlers store their constituent shadow tiddlers as JSON data +* The client-server configuration uses [[JSON messages|TiddlyWeb JSON tiddler format]] to communicate between the client and the server +* Arbitrary JSON data within DataTiddlers can be processed and manipulated using a set of filter operators and action widgets + +!! About JSON + +The technical description of JSON at the official website https://json.org/ is terse. Here we summarise the main features. + +JSON supports two basic data structures: + +''Arrays'' are lists of items. The items are identified by their numeric index (starting at zero) + +An example of an array is: + +```json +["one","two","three\"four"] +``` + +Note the following features of arrays: + +* The array is signified by square brackets surrounding the list of items +* Each item is a string in double quotes. Double quotes can be included within the strings by preceding them with a backslash (`\`) +* The items are separated by commas + +''Objects'' are collections of name/value pairs. Each item is a value that is identified by a unique name + +An example of an object is: + +```json +{ + "first": "This is the first value", + "second": "This is the second value", + "third": "This is the third value" +} +``` + +Note the following features of objects: + +* The object is signified by curly braces surrounding the list of name/value pairs +* Each name/value pair consists of the name in double quotes, a colon, and then the value +* The name/value pairs are separated by commas + +The examples above all show string values. JSON actually supports several different types of value. Any of these types can be used as a value: + +* String values, as shown above +* Numeric values, represented as signed decimals such as `1`, `3.14`. Exponential notation can also be used e.g. `-1E10` +* Boolean values, represented by the keywords `true` and `false` +* The special value `null`, which is often used to represent data that is missing or incomplete +* Objects and arrays are also values, allowing complex nested structures to be represented + +!! Working with Data Tiddlers + +* [[Reading data from JSON tiddlers]] +* [[Constructing JSON tiddlers]] +* [[Modifying JSON tiddlers]] diff --git a/editions/tw5.com/tiddlers/howtos/Constructing JSON tiddlers.tid b/editions/tw5.com/tiddlers/howtos/Constructing JSON tiddlers.tid new file mode 100644 index 000000000..58b36244c --- /dev/null +++ b/editions/tw5.com/tiddlers/howtos/Constructing JSON tiddlers.tid @@ -0,0 +1,16 @@ +title: Constructing JSON tiddlers +tags: [[JSON in TiddlyWiki]] [[Learning]] +created: 20220427174702859 +modified: 20220427174702859 + +See [[JSON in TiddlyWiki]] for an overview of using JSON in TiddlyWiki. + +JSON data is just plain text, and so there are an wide variety of techniques to generate it in wikitext. + +At a high level, we have several ways to generate JSON data in TiddlyWiki's own tiddler format: + +* JSONTiddlerWidget +* [[jsontiddler Macro]] +* [[jsontiddlers Macro]] + +When constructing JSON data manually, the [[jsonstringify Operator]] is needed to ensure that any special characters are properly escaped. diff --git a/editions/tw5.com/tiddlers/howtos/Modifying JSON tiddlers.tid b/editions/tw5.com/tiddlers/howtos/Modifying JSON tiddlers.tid new file mode 100644 index 000000000..947d3cdf5 --- /dev/null +++ b/editions/tw5.com/tiddlers/howtos/Modifying JSON tiddlers.tid @@ -0,0 +1,18 @@ +created: 20220427174702859 +modified: 20220427171707459 +tags: [[JSON in TiddlyWiki]] Learning +title: Modifying JSON tiddlers +type: text/vnd.tiddlywiki + +See [[JSON in TiddlyWiki]] for an overview of using JSON in TiddlyWiki. + +Note that + +!! Using ActionSetFieldWidget and ActionListopsWidget + +The widgets ActionSetFieldWidget and ActionListopsWidget can manipulate named properties of data tiddlers by indicating the name of the property in the $index attribute. + +* To create or modify a named property with ActionSetFieldWidget, provide a $value attribute +* To delete a named property with ActionSetFieldWidget, omit the $value attribute. + +ActionListopsWidget assigns the named property the list constructed through its $filter and $subfilter attributes. diff --git a/editions/tw5.com/tiddlers/howtos/Reading data from JSON tiddlers.tid b/editions/tw5.com/tiddlers/howtos/Reading data from JSON tiddlers.tid new file mode 100644 index 000000000..acf482789 --- /dev/null +++ b/editions/tw5.com/tiddlers/howtos/Reading data from JSON tiddlers.tid @@ -0,0 +1,25 @@ +created: 20220427174702859 +modified: 20220427171449102 +tags: [[JSON in TiddlyWiki]] Learning +title: Reading data from JSON tiddlers +type: text/vnd.tiddlywiki + +See [[JSON in TiddlyWiki]] for an overview of using JSON in TiddlyWiki. + +!! Text References for Accessing JSON Data + +[[Text references|TextReference]] are a simple shortcut syntax to look up the value of a named property. For example, if a [[DictionaryTiddler|DictionaryTiddlers]] called `MonthDays` contains: + +``` +oct:31 +nov:30 +dec:31 +``` + +... then `{{MonthDays##nov}}` will resolve to the value `30`. + +The same is true if `MonthDays` is a [[JSONTiddler|JSONTiddlers]] with the following content: + +``` +{"oct":31,"nov":30,"dec":31} +``` diff --git a/editions/tw5.com/tiddlers/macros/JsonTiddlersMacro.tid b/editions/tw5.com/tiddlers/macros/JsonTiddlersMacro.tid index 5005e9e9c..d25df4d25 100644 --- a/editions/tw5.com/tiddlers/macros/JsonTiddlersMacro.tid +++ b/editions/tw5.com/tiddlers/macros/JsonTiddlersMacro.tid @@ -1,11 +1,11 @@ +caption: jsontiddlers created: 20150221152226000 -modified: 20200204135513721 +modified: 20220427171155184 tags: Macros [[Core Macros]] title: jsontiddlers Macro type: text/vnd.tiddlywiki -caption: jsontiddlers -The <<.def jsontiddlers>> [[macro|Macros]] returns the fields of a [[selection of tiddlers|Title Selection]] in [[JSON|JavaScript Object Notation]] form. +The <<.def jsontiddlers>> [[macro|Macros]] returns the fields of a [[selection of tiddlers|Title Selection]] in [[JSON|JavaScript Object Notation]] form. See [[JSON in TiddlyWiki]] for an overview. An example can be seen in the [[template tiddler for JSON exports|$:/core/templates/exporters/JsonFile]]. diff --git a/editions/tw5.com/tiddlers/macros/jsontiddler Macro.tid b/editions/tw5.com/tiddlers/macros/jsontiddler Macro.tid index f3a0f67c2..9f9666581 100644 --- a/editions/tw5.com/tiddlers/macros/jsontiddler Macro.tid +++ b/editions/tw5.com/tiddlers/macros/jsontiddler Macro.tid @@ -1,11 +1,11 @@ caption: jsontiddler created: 20170317140130417 -modified: 20170317140226040 +modified: 20220427171228844 tags: Macros [[Core Macros]] title: jsontiddler Macro type: text/vnd.tiddlywiki -The <<.def jsontiddler>> [[macro|Macros]] returns the fields of a single tiddler in [[JSON|JavaScript Object Notation]] form. +The <<.def jsontiddler>> [[macro|Macros]] returns the fields of a single tiddler in [[JSON|JavaScript Object Notation]] form. See [[JSON in TiddlyWiki]] for an overview. !! Parameters diff --git a/editions/tw5.com/tiddlers/widgets/JSONTiddlerWidget.tid b/editions/tw5.com/tiddlers/widgets/JSONTiddlerWidget.tid index b09596ff9..3f922bfa2 100644 --- a/editions/tw5.com/tiddlers/widgets/JSONTiddlerWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/JSONTiddlerWidget.tid @@ -1,14 +1,15 @@ -title: JSONTiddlerWidget -created: 20210630100923398 -modified: 20210630100923398 -tags: Widgets caption: jsontiddler +created: 20210630100923398 +modified: 20220427171128693 +tags: Widgets +title: JSONTiddlerWidget +type: text/vnd.tiddlywiki ! Introduction The jsontiddler widget renders the fields of a tiddler to display as a JSON object. The fields of the tiddler can be customised or excluded. -The jsontiddler widget is used in system templates to generate JSON representations of tiddlers for saving. +The jsontiddler widget is used in system templates to generate JSON representations of tiddlers for saving. See [[JSON in TiddlyWiki]] for an overview. ! Content and Attributes