Merge 6971f256a3 into 1d48909012

Fixes #8146

editions/dev/tiddlers/new/Data Storage.tid

@@ -1,10 +1,19 @@
 created: 20140708085814626
-modified: 20210525165526997
+modified: 20240311154305433
 tags: doc
 title: Data Storage
+type: text/vnd.tiddlywiki
 
 ~TiddlyWiki has two approaches to saving the user data (tiddlers) depending on whether you are using the single file version, or are using the node.js server.
 
-~TiddlyWiki on node.js saves each tiddler in a separate text file. For details on the file formats supported for tiddlers on node.js, see [[Tiddler Files|https://tiddlywiki.com/#TiddlerFiles]].
+!! Client Server Configuration
+
+~TiddlyWiki on node.js saves each tiddler in a separate text file. For details on the file formats supported for tiddlers on node.js.
+
+Also see: [[Tiddler Files|https://tiddlywiki.com/#TiddlerFiles]]
+
+!! Single File Wiki
 
 The single file version of ~TiddlyWiki saves the tiddlers within the HTML file. See [[Data Storage in Single File TiddlyWiki]]
+
+Also see: [[SystemTag: $:/tags/InjectCustomTiddlers]]

editions/dev/tiddlers/new/SystemTag_ $__tags_InjectCustomTiddlers.tid

@@ -0,0 +1,77 @@
+created: 20240311152329217
+modified: 20240311154116728
+tags: [[Data Storage]]
+title: SystemTag: $:/tags/InjectCustomTiddlers
+type: text/vnd.tiddlywiki
+
+The [[system tag|http://localhost:8080/#SystemTags]] `$:/tags/InjectCustomTiddlers` marks JSON serialized tiddlers to be injected [[into a custom store section|$:/core/templates/store.injected.template.html]] in the [[generated HTML|$:/core/templates/tiddlywiki5.html]] file.
+
+Note that the wiki must be saved and reloaded in order for the tiddlers to be seen. 
+
+!! Example Template Code
+
+This example template injects 4 tiddlers into the custom store. 
+
+```
+title: $:/core/templates/store.injected.timestamps.template
+caption: Inject last-saved and server-created timestamps
+tags: $:/tags/InjectCustomTiddlers
+
+<!-- This template will be injected into the html file when the wiki is saved. It is activated by $:/core/templates/store.injected.template.html -->
+\whitespace trim
+\procedure readableFormat() [UTC]YYYY-0MM-0DD 0hh:0mm:0ss.0XXX UTC TZD
+
+<!-- It's needed to use variables, to have the absolute same timestamp for all tiddlers -->
+<$let
+	timestamp={{{ [<now format:[UTC]YYYY0MM0DD0hh0mm0ss0XXX>] }}}
+	timeReadable={{{ [<timestamp>format:date<readableFormat>] }}}
+>
+	<% if [{$:/info/browser}match[yes]] %>
+		`{"title": "$:/info/last-saved/timestamp", "created":"`<<timestamp>>`", "modified":"`<<timestamp>>`", "text":"`<<timestamp>>`"}`
+		<$text text=<<join>>/>
+		`{"title": "$:/info/last-saved/date",  "created":"`<<timestamp>>`", "modified":"`<<timestamp>>`", "text":"`<<timeReadable>>`"}`
+	<% elseif [{$:/info/node}match[yes]] %>
+		`{"title": "$:/info/server-created-wiki/timestamp", "created":"`<<timestamp>>`", "modified":"`<<timestamp>>`", "text":"`<<timestamp>>`"}`
+		<$text text=<<join>>/>
+		`{"title": "$:/info/server-created-wiki/date",  "created":"`<<timestamp>>`", "modified":"`<<timestamp>>`", "text":"`<<timeReadable>>`"}`
+	<% endif %>
+</$let>
+```
+
+!! Last Saved -- Single File Wiki
+
+With the template above, the following tiddlers will be "injected" into the HTML file when the wiki is saved. Tagged template tiddlers are used to create the info tiddlers. Those tiddlers will be overwritten with the next automatic or manual save action.
+
+`$:/info/last-saved/*` will  not be created on a server if used with a client-server configuration. They will be created, if a "snapshot" is saved to the disk.
+
+|! Title |! Description |
+|$:/info/last-saved/timestamp |<<.from-version "5.3.4">> This tiddler will be created when a single file wiki is saved. It uses ~TiddlyWiki DateFormat |
+|$:/info/last-saved/date |<<.from-version "5.3.4">> Shows the same last-saved timestamp in human readable form. Eg: "2024-01-30 15:36:04.430 UTC +01:00"<br>using the following format: `[UTC]YYYY-0MM-0DD 0hh:0mm:0ss.0XXX UTC TZD` |
+
+!! Client Server Configuration
+
+<<.warning """If a client server configuration is used, the TW template is used to create the wiki file on the server. So the timestamps saved to the "server-created" info tiddlers are generated by the server. Depending on the server "local time" this timestamp ''can be different'' to the current "user time". Whenever the wiki file is created, the values will be set. `server-created-*` tiddlers will ''not'' be deleted if saved as a single file. The information may have some value""">>
+
+|! Title |! Description |
+|$:/info/server-created-wiki/timestamp |<<.from-version "5.3.4">> This tiddler will be created when the server creates a wiki to be transferred to the client, ''ore'' if as single-file wiki is created by the server using the `--build index` command. It uses ~TiddlyWiki DateFormat |
+|$:/info/server-created-wiki/date |<<.from-version "5.3.4">> Shows the same timestamp in human readable form |
+
+!! Additional information
+
+By default ~TiddlyWiki does not save the full URL information to the file, due to privacy concerns. Eg: `$:/info/last-saved/full/url` can contain private information. Users are free to include the following code into their wiki, if they decide to do so. 
+
+<details><summary>Show code to add the full path to an info tiddler</summary>
+<$codeblock code="""title: inject-full-path
+tags: $:/tags/InjectCustomTiddlers
+
+<!-- This template will be injected into the html file when the wiki is saved. It is activated by $:/core/templates/store.info.template.html -->
+\whitespace trim
+
+\function timestamp() [<now format:[UTC]YYYY0MM0DD0hh0mm0ss0XXX>]
+
+<% if [{$:/info/browser}match[yes]] %>
+	<$text text=<<join>>/>
+	`{"title": "$:/info/last-saved/full/url",  "created":"`<<timestamp>>`", "modified":"`<<timestamp>>`", "text":"`{{$:/info/url/full}}`"}`
+<% endif %>
+"""/>
+</details>

editions/tw5.com/tiddlers/concepts/TiddlerFields.tid

@@ -1,11 +1,11 @@
 created: 20130825213300000
-modified: 20220109101407050
+modified: 20240416103247799
 tags: Concepts
 title: TiddlerFields
 type: text/vnd.tiddlywiki
 
 \define lingo-base() $:/language/Docs/Fields/
-~TiddlerFields are name:value pairs that make up a [[tiddler|Tiddlers]]. Field names must be lowercase letters, digits or the characters `-` (dash), `_` (underscore) and `.` (period).
+~TiddlerFields are name:value pairs that make up a [[tiddler|Tiddlers]]. Field names may contain any combination of characters (prior to [[v5.2.0|Release 5.2.0]], fields were constrained to be lowercase letters, digits or the characters `-` (dash), `_` (underscore) and `.` (period)).
 
 The standard fields are:
 

editions/tw5.com/tiddlers/webserver/Using the external JavaScript template.tid

@@ -1,5 +1,5 @@
 created: 20180905075846391
-modified: 20230319130830880
+modified: 20240413045138914
 tags: [[WebServer Guides]]
 title: Using the external JavaScript template
 type: text/vnd.tiddlywiki
@@ -20,7 +20,7 @@ The remaining inefficiency when working in the client server configuration is th
 
 ! Using the external ~JavaScript template with the client-server configuration
 
-The mechanism is activated by setting the [[root-tiddler|WebServer Parameter: root-tiddler]] parameter to `$:/core/save/all-external-js`. This template externalises ~TiddlyWiki's core ~JavaScript into a separate file. For example, the following command will start your server with caching enabled. It will transfer the wiki with two GET requests, and the core can be cached by the browser.
+The mechanism is activated by setting the [[root-tiddler|WebServer Parameter: root-tiddler]] parameter to `$:/core/save/all-external-js`. This template externalises ~TiddlyWiki's core ~JavaScript into a separate file. For example, the following command will [[start your server with caching enabled|WebServer Parameter: use-browser-cache]]. It will transfer the wiki with two GET requests, and the core can be cached by the browser.
 
 ```
 tiddlywiki YOUR_WIKI_FOLDER --listen 'root-tiddler=$:/core/save/all-external-js' use-browser-cache=yes

editions/tw5.com/tiddlers/webserver/Using the integrated static file server.tid

@@ -1,5 +1,5 @@
 created: 20180703095630828
-modified: 20180703100445719
+modified: 20240413045124764
 tags: [[WebServer Guides]]
 title: Using the integrated static file server
 type: text/vnd.tiddlywiki
@@ -13,4 +13,19 @@ Static files can be referenced directly:
 * `[ext[./files/a-big-document.pdf]]` - to make a link to a PDF
 * `[img[./files/a-big-image.png]]` - to embed an image
 
-Alternatively, the ''_canonical_uri'' field can be used to reference the files as [[external tiddlers|ExternalImages]].
+Alternatively, the ''_canonical_uri'' field can be used to reference the files as [[external tiddlers|ExternalImages]].
+
+If [[WebServer Parameter: use-browser-cache]] is used, these files will be cached by the client's browser to save on bandwidth. In this case, the `cache busting strategy` can be used to make sure the client always has the latest updated files.
+
+
+<<<
+https://javascript.plainenglish.io/what-is-cache-busting-55366b3ac022
+
+!! Cache Busting
+
+There are a couple different ways of changing the names of files so that they will load when they change. One way is to use version numbers and have them somewhere in the file name when loading. You could have a subdirectory for every version, `v1/index.js` `v2/index.css` . You could also have the version in queries in the URLs, `index.js?v1` , `index.css?v2` .
+
+Another way is to change the name of the file, `index.v1.js` , `index.v2.css` . These ways are not as manageable because this can become very hard once you have a ton of files that are being changed.
+
+A more popular and manageable way is to keep hashes inside the file names. Hashes, if you don’t know, are fixed length character representations of any content and they are irreversible, meaning you can get the hash from the file but you can’t get the file from the hash. Hashes are perfect for this, because when a file changes its hash will change, so if we keep the hash inside the filename `index.[someHashHere].js` browsers will detect it and load it instead of an old file.
+<<<

editions/tw5.com/tiddlers/webserver/WebServer Parameter_ use-browse-cache.tid

@@ -0,0 +1,25 @@
+caption: use-browse-cache
+created: 20240413042652008
+modified: 20240413050841387
+tags: [[WebServer Parameters]]
+title: WebServer Parameter: use-browser-cache
+type: text/vnd.tiddlywiki
+
+The [[web server configuration parameter|WebServer Parameters]] ''use-browser-cache=yes'' activates 200 OK browser caching via the `Cache-Control` header and a smart a Etag header:
+
+* The server javascript creates an MD5 `hash` object.
+* Adds the data of the current `request:response` (for example: json text or an image binary) to the hash object.
+* Adds the current `headers` of the response to the hash object.
+* If the response data has an `encoding` value, adds the encoding to the hash object.
+* Calculates the final MD5 hash string as a `contentDigest` javascript variable, and saves it as an `Etag: "<<contentDigest>>"` header.
+
+If the incoming request contains a header named `if-none-match`, then the server will check the generated Etag against all values.
+
+If any `if-none-match` value DOES match the current Etag, the server will send a `304 NOT MODIFIED` response with the current response headers, instead of the data with a `200 OK` response.
+
+This saves bandwidth, as the client can be sure they have already received the exact data and has it in their current cache.
+
+If ''use-browser-cache=no'' (or any other value including null), then the server will return a `Cache-Control: no-store` header by default.
+
+If any customer server route module defines custom `Cache-Control` header behavior, then the server will pass that header through instead of the default.
+

editions/tw5.com/tiddlers/webserver/WebServer.tid

@@ -1,5 +1,5 @@
 created: 20180626150526207
-modified: 20181216181934282
+modified: 20240413043741157
 tags: ListenCommand ServerCommand Features
 title: WebServer
 type: text/vnd.tiddlywiki

licenses/cla-individual.md

@@ -564,4 +564,6 @@ Ed Holsinger, @eschlon, 2024/02/08
 
 Kim I. McKinley, @PotOfCoffee2Go, 2024/03/16
 
-@Jinix6, 2024/03/31
+@Jinix6, 2024/03/31
+
+Anders Jarmund, @andjar, 2024/04/05