mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-23 18:17:20 +00:00
Fixed docs to work with new wikitext parser
Which turns out to be entirely a matter of inserting additional blank lines, which has the beneficial effect of making the wikitext a lot more readable
This commit is contained in:
parent
17c77fb3b8
commit
5f6be2b5c7
@ -3,73 +3,109 @@ modifier: JeremyRuston
|
||||
tags: feature
|
||||
|
||||
TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on tiddlers, TiddlerFiles and TiddlyWikiFiles. For example, this loads the tiddlers from a TiddlyWiki HTML file and then saves one of them in HTML:
|
||||
|
||||
{{{
|
||||
node core/boot.js --verbose --load mywiki.html --savetiddler ReadMe ./readme.html
|
||||
}}}
|
||||
!!Usage
|
||||
|
||||
Running `boot.js` from the command line boots the TiddlyWiki kernel, loads the core plugins and establishes an empty wiki store. It then sequentially processes the command line arguments from left to right. The arguments are separated with spaces. The commands are identified by the prefix `--`.
|
||||
|
||||
{{{
|
||||
node core/boot.js [--<option> [<arg>[,<arg>]]]
|
||||
}}}
|
||||
|
||||
!!Commands
|
||||
|
||||
The following commands are available.
|
||||
|
||||
!!! load
|
||||
|
||||
Load tiddlers from 2.x.x TiddlyWiki files (`.html`), `.tiddler`, `.tid`, `.json` or other files
|
||||
|
||||
{{{
|
||||
--load <filepath>
|
||||
}}}
|
||||
|
||||
!!! savetiddler
|
||||
|
||||
Save an individual tiddler as a specified MIME type, defaults to `text/html`
|
||||
|
||||
{{{
|
||||
--savetiddler <title> <filename> [<type>]
|
||||
}}}
|
||||
|
||||
!!! wikitest
|
||||
|
||||
Run wikification tests against the tiddlers in the given directory. Include the `save` flag to save the test result files as the new targets.
|
||||
|
||||
{{{
|
||||
--wikitest <dir> [save]
|
||||
}}}
|
||||
|
||||
`--wikitest` looks for `*.tid` files in the specified folder. It then wikifies the tiddlers to both "text/plain" and "text/html" format and checks the results against the content of the `*.html` and `*.txt` files in the same directory.
|
||||
|
||||
!!! server
|
||||
|
||||
The server is very simple. At the root, it serves a rendering of a specified tiddler. Away from the root, it serves individual tiddlers encoded in JSON, and supports the basic HTTP operations for `GET`, `PUT` and `DELETE`.
|
||||
|
||||
{{{
|
||||
--server <port> <roottiddler> <rendertype> <servetype>
|
||||
}}}
|
||||
|
||||
For example:
|
||||
|
||||
{{{
|
||||
--server 8080 $:/core/tiddlywiki5.template.html text/plain text/html
|
||||
}}}
|
||||
|
||||
The parameters are:
|
||||
|
||||
{{{
|
||||
--server <port> <roottiddler> <rendertype> <servetype>
|
||||
}}}
|
||||
|
||||
* ''port'' - port number to serve from (defaults to "8080")
|
||||
* ''roottiddler'' - the tiddler to serve at the root (defaults to "$:/core/tiddlywiki5.template.html")
|
||||
* ''rendertype'' - the content type to which the root tiddler should be rendered (defaults to "text/plain")
|
||||
* ''servetype'' - the content type with which the root tiddler should be served (defaults to "text/html")
|
||||
|
||||
!!! dump tiddlers
|
||||
|
||||
Dump the titles of the tiddlers in the wiki store
|
||||
|
||||
{{{
|
||||
--dump tiddlers
|
||||
}}}
|
||||
|
||||
!!! dump tiddler
|
||||
|
||||
Dump the fields of an individual tiddler
|
||||
|
||||
{{{
|
||||
--dump tiddler <title>
|
||||
}}}
|
||||
|
||||
!!! dump shadows
|
||||
|
||||
Dump the titles of the shadow tiddlers in the wiki store
|
||||
|
||||
{{{
|
||||
--dump shadows
|
||||
}}}
|
||||
|
||||
!!! dump config
|
||||
|
||||
Dump the current core configuration
|
||||
|
||||
{{{
|
||||
--dump config
|
||||
}}}
|
||||
|
||||
!!! verbose
|
||||
|
||||
Triggers verbose output, useful for debugging
|
||||
|
||||
{{{
|
||||
--verbose
|
||||
}}}
|
||||
|
@ -2,38 +2,59 @@ title: ImageTests
|
||||
tags: demo
|
||||
|
||||
This tiddler demonstrates different ways of displaying images
|
||||
|
||||
{{{
|
||||
<<tiddler [[Motovun Jack.jpg]]>>
|
||||
}}}
|
||||
|
||||
Appears as:
|
||||
|
||||
<<tiddler [[Motovun Jack.jpg]]>>
|
||||
|
||||
{{{
|
||||
<<image [[Motovun Jack.jpg]] text:"A kitten">>
|
||||
}}}
|
||||
|
||||
Appears as:
|
||||
|
||||
<<image [[Motovun Jack.jpg]] text:"A kitten">>
|
||||
|
||||
{{{
|
||||
[img[Motovun Jack.jpg]]
|
||||
}}}
|
||||
|
||||
Appears as:
|
||||
|
||||
[img[Motovun Jack.jpg]]
|
||||
|
||||
{{{
|
||||
[img[tooltip|Motovun Jack.jpg]]
|
||||
}}}
|
||||
|
||||
Appears as:
|
||||
|
||||
[img[tooltip|Motovun Jack.jpg]]
|
||||
|
||||
{{{
|
||||
[img[tooltip|Motovun Jack.jpg][http://google.com/]]
|
||||
}}}
|
||||
|
||||
Appears as:
|
||||
|
||||
[img[tooltip|Motovun Jack.jpg][http://google.com/]]
|
||||
|
||||
{{{
|
||||
<<tiddler [[Tiddler Fishes.svg]]>>
|
||||
}}}
|
||||
|
||||
Appears as:
|
||||
|
||||
<<tiddler [[Tiddler Fishes.svg]]>>
|
||||
|
||||
{{{
|
||||
[img[Tiddler Fishes.svg]]
|
||||
}}}
|
||||
|
||||
Appears as:
|
||||
|
||||
[img[Tiddler Fishes.svg]]
|
||||
|
@ -10,14 +10,18 @@ You can download a static copy of the tiddlers that are currently displayed in t
|
||||
|
||||
{{alert alert-error{
|
||||
Try out the prototype touch features:
|
||||
|
||||
* The zooming chooser appears by swiping into the left edge of the screen (or hover the mouse over the extreme left edge of the browser window)
|
||||
* The zooming navigator appears by swiping in from the right edge of the screen (not accessible by mouse)
|
||||
}}}
|
||||
|
||||
Learning more about TiddlyWiki5:
|
||||
|
||||
* WaysToUseTiddlyWiki discusses the various configurations in which TiddlyWiki5 can be used
|
||||
* Some very rough UserInterfaceSketches showing where it is heading
|
||||
|
||||
Some useful tiddlers for feature testing:
|
||||
|
||||
* HelloThere
|
||||
* TestingNewWikiText shows off the embryonic new wiki text engine
|
||||
* ImageTests showing different ways of embedding images
|
||||
@ -29,6 +33,7 @@ Some useful tiddlers for feature testing:
|
||||
* ShadowTiddlers, including ViewTemplate, EditTemplate and PageTemplate
|
||||
|
||||
Technical documentation includes:
|
||||
|
||||
* [[Testing]] regimen
|
||||
* Details of the CommandLineInterface
|
||||
* Overview of TiddlyWikiArchitecture
|
||||
@ -37,4 +42,4 @@ Technical documentation includes:
|
||||
* A discussion of potential NewWikiTextFeatures
|
||||
|
||||
All tiddlers:
|
||||
<<list all>>
|
||||
<<list all>>
|
||||
|
@ -2,6 +2,7 @@ title: PluginMechanism
|
||||
tags: internals
|
||||
|
||||
!Introduction
|
||||
|
||||
TiddlyWiki5 is based on a 500 line boot kernel that runs on node.js or in the browser, and everything else is plugins.
|
||||
|
||||
The kernel boots just enough of the TiddlyWiki environment to allow it to load tiddlers as plugins and execute them (a barebones tiddler class, a barebones wiki store class, some utilities etc.). Plugin modules are written like `node.js` modules; you can use `require()` to invoke sub components and to control load order.
|
||||
@ -12,11 +13,13 @@ the `modified` and `created` fields.
|
||||
Some plugins have further sub-plugins: the wikitext parser, for instance, accepts rules as individual plugins.
|
||||
|
||||
!Plugins and Modules
|
||||
|
||||
In TiddlyWiki5, a plugin is a bundle of related tiddlers that are distributed together as a single unit. Plugins can include tiddlers which are JavaScript modules.
|
||||
|
||||
The file `core/boot.js` is a barebones TiddlyWiki kernel that is just sufficient to load the core plugin modules and trigger a startup plugin module to load up the rest of the application.
|
||||
|
||||
The kernel includes:
|
||||
|
||||
* Eight short shared utility functions
|
||||
* Three methods implementing the plugin module mechanism
|
||||
* The `$tw.Tiddler` class (and three field definition plugins)
|
||||
@ -40,6 +43,7 @@ The boot kernel sets up the `$tw` global variable that is used to store all the
|
||||
!Core
|
||||
|
||||
The 'core' is the boot kernel plus the set of plugin modules that it loads. It contains plugins of the following types:
|
||||
|
||||
* `tiddlerfield` - defines the characteristics of tiddler fields of a particular name
|
||||
* `tiddlerdeserializer` - methods to extract tiddlers from text representations or the DOM
|
||||
* `startup` - functions to be called by the kernel after booting
|
||||
@ -57,8 +61,8 @@ The 'core' is the boot kernel plus the set of plugin modules that it loads. It c
|
||||
* `command` - individual commands for the `$tw.Commander` class
|
||||
|
||||
TiddlyWiki5 makes extensive use of JavaScript inheritance:
|
||||
|
||||
* Tree nodes defined in `$:/core/treenodes/` all inherit from `$:/core/treenodes/node.js`
|
||||
* Macros defined in `$:/core/macros/` all inherit from `$:/core/treenodes/macro.js`
|
||||
|
||||
`tiddlywiki.plugin` files
|
||||
|
||||
|
@ -2,14 +2,23 @@ title: ReadMe
|
||||
tags: introduction
|
||||
|
||||
!Welcome to TiddlyWiki5
|
||||
|
||||
<<tiddler HelloThere>>
|
||||
|
||||
!Usage
|
||||
|
||||
<<tiddler CommandLineInterface>>
|
||||
|
||||
!Architecture
|
||||
|
||||
<<tiddler TiddlyWikiArchitecture>>
|
||||
|
||||
!Plugin Mechanism
|
||||
|
||||
<<tiddler PluginMechanism>>
|
||||
|
||||
!Planned WikiText Features
|
||||
|
||||
<<tiddler NewWikiTextFeatures>>
|
||||
|
||||
//This `readme` file was automatically generated by TiddlyWiki5//
|
||||
|
@ -2,16 +2,21 @@ title: SliderTests
|
||||
tags: demo
|
||||
|
||||
The status of this slider is stored in the tiddler JackSlider:
|
||||
|
||||
<<slider JackSlider "Motovun Jack.jpg" "TiddlyWiki Kitten »" "See the kitten">>
|
||||
|
||||
And here's another slider that is also keyed to JackSlider:
|
||||
|
||||
<<slider JackSlider Introduction "HelloThere »">>
|
||||
|
||||
And here's another slider that contains a video, with the state stored in VideoSlider (currently <<tiddler VideoSlider>>):
|
||||
|
||||
<<slider VideoSlider VideoTests "VideoTests »">>
|
||||
|
||||
And here's a MiniSlider that works with text, rather than a separate tiddler.
|
||||
|
||||
<<slider state:MiniSlider label:"Click me! »" content:"This is the //content// of the slider. The state is stored in MiniSlider">>
|
||||
|
||||
And here's a slider that doesn't use a state tiddler:
|
||||
|
||||
<<slider label:"Click me! »" content:"This is the //content// of the slider. The state is not retained.">>
|
||||
|
@ -3,23 +3,29 @@ modifier: JeremyRuston
|
||||
tags: internals
|
||||
|
||||
Tiddlers can be stored in text files in several different formats. Files containing single tiddlers can also have an auxiliary `.meta` file formatted as a sequence of name:value pairs:
|
||||
|
||||
{{{
|
||||
title: TheTitle
|
||||
modifier: someone
|
||||
}}}
|
||||
|
||||
!! ~TiddlyWeb-style .tid files
|
||||
|
||||
These files consist of a sequence of lines containing name:value pairs, a blank line and then the text of the tiddler. For example:
|
||||
|
||||
{{{
|
||||
title: MyTiddler
|
||||
modifier: Jeremy
|
||||
|
||||
This is the text of my tiddler.
|
||||
}}}
|
||||
|
||||
//The MIME type `application/x-tiddler` is used internally for these files//
|
||||
|
||||
!! TiddlyWiki `<DIV>` .tiddler files
|
||||
|
||||
Modern `*.tiddler` files look like this:
|
||||
|
||||
{{{
|
||||
<div title="AnotherExampleStyleSheet" modifier="blaine" created="201102111106" modified="201102111310" tags="examples" creator="psd">
|
||||
<pre>Note that there is an embedded <pre> tag, and line feeds are not escaped.
|
||||
@ -27,19 +33,23 @@ Modern `*.tiddler` files look like this:
|
||||
And, weirdly, there is no HTML encoding of the body.</pre>
|
||||
</div>
|
||||
}}}
|
||||
|
||||
These `*.tiddler` files are therefore not quite the same as the tiddlers found inside a TiddlyWiki HTML file, where the body is HTML encoded in the expected way.
|
||||
|
||||
Older `*.tiddler` files more closely matched the store format used by TiddlyWiki at the time:
|
||||
|
||||
{{{
|
||||
<div tiddler="AnotherExampleStyleSheet" modifier="JeremyRuston" modified="200508181432" created="200508181432" tags="examples">This is an old-school .tiddler file, without an embedded <pre> tag.\nNote how the body is "HTML encoded" and new lines are escaped to \\n</div>
|
||||
}}}
|
||||
|
||||
//The MIME type `application/x-tiddler-html-div` is used internally for these files//
|
||||
|
||||
!! ~TiddlyWeb-style JSON files
|
||||
|
||||
These files are a straightforward array of hashmaps of name:value fields. Currently only these known fields are processed: `title`, `text`, `created`, `creator`, `modified`, `modifier`, `type` and `tags`.
|
||||
|
||||
|
||||
//The MIME type `application/json` is used internally for these files//
|
||||
|
||||
!! TiddlyWiki HTML files
|
||||
|
||||
TiddlyWiki HTML files contain a collection of tiddlers encoded in `<DIV>` format.
|
||||
|
@ -24,6 +24,7 @@ The mechanism is easiest to understand by first presenting some example filter s
|
||||
A filter string consists of one or more filter operations, each comprising one or more filter operators with associated operands.
|
||||
|
||||
The operators look like `[operator[operand]]`, where `operator` is one of:
|
||||
|
||||
* ''title'': selects the tiddler with the title given in the operand
|
||||
* ''is'': tests whether a tiddler is a member of the system defined set named in the operand (see below)
|
||||
* ''has'': tests whether a tiddler has a specified field
|
||||
@ -37,9 +38,11 @@ An operator can be negated with by preceding it with `!`, for example `[!tag[Tom
|
||||
The operator defaults to `title` if omitted, so `[[HelloThere]]` is equivalent to `[title[HelloThere]]`. If there are no spaces in the title, then the double square brackets can also be omitted: `HelloThere`.
|
||||
|
||||
The operands available with the `is` operator are:
|
||||
|
||||
* ''tiddler'': selects all ordinary (non-shadow) tiddlers
|
||||
|
||||
Operators are combined into logically ANDed expressions by bashing them together and merging the square brackets:
|
||||
|
||||
{{{
|
||||
[tag[one]] [tag[two]] ---> [tag[one]tag[two]]
|
||||
}}}
|
||||
@ -49,6 +52,7 @@ Operations can be preceded with `-` to negate their action, removing the selecte
|
||||
Operations can be preceded with `+` in order to make them apply to all of the current results, rather than the original source. For example, `[tag[Jeremy]] [tag[Tommy]] +[sort[title]]` selects the tiddlers tagged `Tommy` or `Jeremy`, and sorts them by the `title` field.
|
||||
|
||||
Filters are processed with the following elements:
|
||||
|
||||
* a string of filter operations, each made up of one or more filter operators
|
||||
* the incoming source tiddlers
|
||||
* the overall result stack
|
||||
|
@ -11,16 +11,22 @@ The most important transformations are from `text/x-tiddlywiki` wikitext into `t
|
||||
The key feature of wikitext is the ability to include one tiddler within another (usually referred to as //transclusion//). For example, one could have a tiddler called //Disclaimer// that contains the boilerplate of a legal disclaimer, and then include it within lots of different tiddlers with the macro call `<<tiddler Disclaimer>>`. This simple feature brings great power in terms of encapsulating and reusing content, and evolving a clean, usable implementation architecture to support it efficiently is a key objective of the TiddlyWiki5 design.
|
||||
|
||||
It turns out that the transclusion capability combined with the selective refreshing mechanism provides a good foundation for building TiddlyWiki's user interface itself. Consider, for example, the StoryMacro in its simplest form:
|
||||
|
||||
{{{
|
||||
<<story story:MyStoryTiddler>>
|
||||
}}}
|
||||
|
||||
The story macro looks for a list of tiddler titles in the tiddler `MyStoryTiddler`, and displays them in sequence. The subtle part is that subsequently, if `MyStoryTiddler` changes, the `<<story>>` macro is selectively re-rendered. So, to navigate to a new tiddler, code merely needs to add the name of the tiddler and a line break to the top of `MyStoryTiddler`:
|
||||
|
||||
{{{
|
||||
var storyTiddler = store.getTiddler("MyStoryTiddler");
|
||||
store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + "\n" + storyTiddler.text}));
|
||||
}}}
|
||||
|
||||
The mechanisms that allow all of this to work are fairly intricate. The sections below progressively build the key architectural concepts of TiddlyWiki5 in a way that should provide a good basis for exploring the code directly.
|
||||
|
||||
!! Tiddlers
|
||||
|
||||
Tiddlers are an immutable dictionary of name:value pairs called fields.
|
||||
|
||||
The only field that is required is the {{{title}}} field, but useful tiddlers also have a {{{text}}} field, and some or all of the standard fields {{{modified}}}, {{{modifier}}}, {{{created}}}, {{{creator}}}, {{{tags}}} and {{{type}}}.
|
||||
@ -28,26 +34,35 @@ The only field that is required is the {{{title}}} field, but useful tiddlers al
|
||||
Hardcoded in the system is the knowledge that the `tags` field is a string array, and that the `modified` and `created` fields are JavaScript `Date` objects. All other fields are strings.
|
||||
|
||||
The {{{type}}} field identifies the representation of the tiddler text with a MIME type.
|
||||
|
||||
!! ~WikiStore
|
||||
|
||||
Groups of uniquely titled tiddlers are contained in WikiStore objects.
|
||||
|
||||
The WikiStore also manages the plugin modules used for macros, and operations like serializing, deserializing, parsing and rendering tiddlers.
|
||||
|
||||
Each WikiStore is connected to another shadow store that is used to provide default content. Under usual circumstances, when an attempt is made to retrieve a tiddler that doesn't exist in the store, the search continues into its shadow store (and so on, if the shadow store itself has a shadow store).
|
||||
|
||||
!! ~WikiStore Events
|
||||
|
||||
Clients can register event handlers with the WikiStore object. Event handlers can be registered to be triggered for modifications to any tiddler in the store, or with a filter to only be invoked when a particular tiddler or set of tiddlers changes.
|
||||
|
||||
Whenever a change is made to a tiddler, the wikistore registers a `nexttick` handler (if it hasn't already done so). The `nexttick` handler looks back at all the tiddler changes, and dispatches any matching event handlers.
|
||||
|
||||
!! Parsing and Rendering
|
||||
|
||||
TiddlyWiki parses the content of tiddlers to build an internal tree representation that is used for several purposes:
|
||||
|
||||
* Rendering a tiddler to other formats (e.g. converting wikitext to HTML)
|
||||
* Detecting outgoing links from a tiddler, and from them...
|
||||
* ...computing incoming links to a tiddler
|
||||
* Detecting tiddlers that are orphans with no incoming links
|
||||
* Detecting tiddlers that are referred to but missing
|
||||
|
||||
The parse tree is built when needed, and then cached by the WikiStore until the tiddler changes.
|
||||
|
||||
TiddlyWiki5 uses multiple parsers:
|
||||
|
||||
* Wikitext ({{{text/x-tiddlywiki}}}) in `js/WikiTextParser.js`
|
||||
* JavaScript ({{{text/javascript}}}) in `js/JavaScriptParser.js`
|
||||
* Images ({{{image/png}}} and {{{image/jpg}}}) in `js/ImageParser.js`
|
||||
@ -55,41 +70,55 @@ TiddlyWiki5 uses multiple parsers:
|
||||
Additional parsers are planned:
|
||||
* CSS ({{{text/css}}})
|
||||
* Recipe ({{{text/x-tiddlywiki-recipe}}})
|
||||
|
||||
One global instance of each parser is instantiated in `js/App.js` and registered with the main WikiStore object.
|
||||
|
||||
The parsers are all used the same way:
|
||||
|
||||
$$$.js
|
||||
var parseTree = parser.parse(type,text) // Parses the text and returns a parse tree object
|
||||
$$$
|
||||
|
||||
The parse tree object exposes the following fields:
|
||||
|
||||
$$$.js
|
||||
var renderer = parseTree.compile(type); // Compiles the parse tree into a renderer for the specified MIME type
|
||||
console.log(parseTree.toString(type)); // Returns a readable string representation of the parse tree (either `text/html` or `text/plain`)
|
||||
var dependencies = parseTree.dependencies; // Gets the dependencies of the parse tree (see below)
|
||||
$$$
|
||||
|
||||
The dependencies are returned as an object like this:
|
||||
|
||||
{{{
|
||||
{
|
||||
tiddlers: {"tiddlertitle1": true, "tiddlertitle2": false},
|
||||
dependentAll: false
|
||||
}
|
||||
}}}
|
||||
|
||||
The `tiddlers` field is a hashmap of the title of each tiddler that is linked or included in the current one. The value is `true` if the tiddler is a //'fat'// dependency (ie the text is included in some way) or `false` if the tiddler is a //`skinny`// dependency.
|
||||
|
||||
The `dependentAll` field is used to indicate that the tiddler contains a macro that scans the entire pool of tiddlers (for example the `<<list>>` macro), and is potentially dependent on any of them. The effect is that the tiddler should be rerendered whenever any other tiddler changes.
|
||||
|
||||
!! Rendering
|
||||
|
||||
The `parseTree.compile(type)` method returns a renderer object that contains a JavaScript function that generates the new representation of the original parsed text.
|
||||
|
||||
The renderer is invoked as follows:
|
||||
|
||||
$$$.js
|
||||
var renderer = parseTree.compile("text/html");
|
||||
var html = renderer.render(tiddler,store);
|
||||
$$$
|
||||
|
||||
The `tiddler` parameter to the `render` method identifies the tiddler that is acting as the context for this rendering -- for example, it provides the fields displayed by the `<<view>>` macro. The `store` parameter is used to resolve any references to other tiddlers.
|
||||
|
||||
!! Rerendering
|
||||
|
||||
When rendering to the HTML/SVG DOM in the browser, TiddlyWiki5 also allows a previous rendering to be selectively updated in response to changes in dependent tiddlers. At the moment, only the WikiTextRenderer supports rerendering.
|
||||
|
||||
The rerender method on the renderer is called as follows:
|
||||
|
||||
{{{
|
||||
var node = document.getElementById("myNode");
|
||||
var renderer = parseTree.compile("text/html");
|
||||
@ -97,13 +126,14 @@ myNode.innerHTML = renderer.render(tiddler,store);
|
||||
// And then, later:
|
||||
renderer.rerender(node,changes,tiddler,store,renderStep);
|
||||
}}}
|
||||
|
||||
The parameters to `rerender()` are:
|
||||
|
||||
|!Name |!Description |
|
||||
|node |A reference to the DOM node containing the rendering to be rerendered |
|
||||
|changes |A hashmap of `{title: "created|modified|deleted"}` indicating which tiddlers have changed since the original rendering |
|
||||
|tiddler |The tiddler providing the rendering context |
|
||||
|store |The store to use for resolving references to other tiddlers |
|
||||
|renderStep |See below |
|
||||
|
||||
Currently, the only macro that supports rerendering is the `<<story>>` macro; all other macros are rerendered by calling the ordinary `render()` method again. The reason that the `<<story>>` macro goes to the trouble of having a `rerender()` method is so that it can be carefully selective about not disturbing tiddlers in the DOM that aren't affected by the change. If there were, for instance, a video playing in one of the open tiddlers it would be reset to the beginning if the tiddler were rerendered.
|
||||
|
||||
|
||||
|
@ -2,17 +2,19 @@ title: TypedBlockTests
|
||||
tags: demo
|
||||
|
||||
WikiText can include blocks of text that are rendered with an explicit MIME type like this:
|
||||
|
||||
{{{
|
||||
$$$application/javascript
|
||||
//This is some JavaScript
|
||||
return 2 + "one";
|
||||
var thing = 2 + "one";
|
||||
$$$
|
||||
}}}
|
||||
|
||||
This renders as:
|
||||
|
||||
$$$application/javascript
|
||||
//This is some JavaScript
|
||||
return 2 + "one";
|
||||
var thing = 2 + "one";
|
||||
$$$
|
||||
|
||||
It is also possible to abbreviate the MIME type to a file extension. For example:
|
||||
@ -34,23 +36,29 @@ $$$.svg
|
||||
$$$
|
||||
|
||||
And, finally, a JSON example:
|
||||
|
||||
{{{
|
||||
$$$.json
|
||||
{"teapot": "brown","inside":["milk","sugar",23]}
|
||||
$$$
|
||||
}}}
|
||||
|
||||
Which renders as:
|
||||
|
||||
$$$.json
|
||||
{"teapot": "brown","inside":["milk","sugar",23]}
|
||||
$$$
|
||||
|
||||
Unknown types render as plain text:
|
||||
|
||||
{{{
|
||||
$$$text/unknown
|
||||
Some plain text, which will not be //formatted//.
|
||||
$$$
|
||||
}}}
|
||||
|
||||
Which renders as:
|
||||
|
||||
$$$text/unknown
|
||||
Some plain text, which will not be //formatted//.
|
||||
$$$
|
||||
|
@ -2,13 +2,16 @@ title: UserInterfaceSketches
|
||||
modifier: JeremyRuston
|
||||
|
||||
!Introduction
|
||||
|
||||
At its core, TiddlyWiki is a representation transformation engine with a cunning line in selective live updating. The engine could be used to build many different user interface experiences. The role of the core UI is not to be all things to everyone, it is just to provide a beautiful and compelling interactive experience for the activities that experience has shown to be popular.
|
||||
|
||||
!Principles
|
||||
|
||||
* The best UI is transparent: just the content, no chrome unless you need it
|
||||
* Design for touch and mobile first, keyboard and mouse second, and play well with screenreaders
|
||||
|
||||
!Sketches
|
||||
|
||||
The basic idea is to preserve the page itself for the content, styled and arranged as the user wants. The interactive features necessary to use the application are overlaid when needed, and then get out of the way:
|
||||
|
||||
[img[Main Screen Sketch.jpg]]
|
||||
@ -16,6 +19,7 @@ The basic idea is to preserve the page itself for the content, styled and arrang
|
||||
Swiping in from the left of the screen reveals the primary navigation chooser, an explorable fisheye menu that gives you access to all your tiddlers, categorised and linked to make them easy to find.
|
||||
|
||||
The sketch below shows the main screen layout along with the contents of the //view switcher//. This allows the user to select between different ways of looking at tiddlers:
|
||||
|
||||
* As a packed mosaic of images and text (like the jQuery Masonry plugin)
|
||||
* As a row of stacks for Kanban type sorting activities
|
||||
* As a lines-n-boxes diagram, with a plugin mechanism for laying them out
|
||||
@ -30,6 +34,7 @@ The sketch below shows the main screen layout along with the contents of the //v
|
||||
[img[View Switcher Sketch.jpg]]
|
||||
|
||||
!Command Line
|
||||
|
||||
The idea of the command line is to give people an environment that makes it easy to interactively process tiddlers, performing one-off imports and exports of data, or batch operations on many tiddlers at once. It was somewhat inspired by [[this wonderful experiment on reimagining the command line terminal|http://acko.net/blog/on-termkit/]].
|
||||
|
||||
[img[Command Line Sketch.jpg]]
|
||||
|
@ -2,6 +2,7 @@ title: WaysToUseTiddlyWiki
|
||||
tags: feature
|
||||
|
||||
!Introduction
|
||||
|
||||
TiddlyWiki5 will be deployable in a wide variety of different arrangements to suit different needs. The archetypal configurations are listed below along with a measure of how much complexity is involved in setting up each one -- once set up properly, the TiddlyWiki user experience should be consistent regardless of configuration.
|
||||
|
||||
|!Name |!Description |!Barriers |
|
||||
@ -13,12 +14,15 @@ TiddlyWiki5 will be deployable in a wide variety of different arrangements to su
|
||||
|CustomBrowser |Building a custom web browser around TiddlyWiki to let it work optimally on a particular platform |Very High: you need to be a pretty experienced software developer |
|
||||
|
||||
!SelfContained Configuration
|
||||
|
||||
This is the familiar form of TiddlyWiki: a single HTML file that runs in the browser containing both the application logic and your data. On many browsers you can edit your content and save your changes without any special add-ins. Even without the ability to save changes, this configuration offers compelling advantages as a content distribution medium by allowing you distribute a fully interactive web experience with just a dumb, reliable static web server.
|
||||
|
||||
The SelfContained configuration performs well on the web. By packing all the required JavaScript, CSS and HTML into a single file we avoid the latency that comes from traditional websites bringing in external resources as they load in the browser.
|
||||
|
||||
!ExplodedFolder Configuration
|
||||
|
||||
This form lays out your data and the components of TiddlyWiki as separate files:
|
||||
|
||||
{{{
|
||||
folder/
|
||||
index.html
|
||||
@ -28,23 +32,29 @@ folder/
|
||||
MyTiddler2.jpg
|
||||
MyTiddler3.svg
|
||||
}}}
|
||||
|
||||
You can just open the `index.html` in the browser. The content tiddlers are lazily loaded as required, with the HTML file acting as a literal index, listing the titles and other metadata about each tiddler. In some browsers you will be able to make changes to the data through the browser too.
|
||||
|
||||
The key advantage of this configuration is that it plays well with existing desktop PC file tools, including source code control systems like Git and Subversion.
|
||||
|
||||
!LocalHelperApp Configuration
|
||||
|
||||
This configuration uses node.js to enable TiddlyWiki5 to run as a local web server. This means that you interact with it from your browser, typically going to a URL like `127.0.0.1:8080`.
|
||||
|
||||
On most operating systems, installing node.js is a single step operation - see http://nodejs.org/ for details. Once installed, running TiddlyWiki requires a simple command line that you can type in the terminal or assign to a shortcut:
|
||||
|
||||
{{{
|
||||
node tiddlywiki myfolder/index.html
|
||||
}}}
|
||||
|
||||
In this configuration, TiddlyWiki5 can store data in either a single SelfContained file, or in the ExplodedFolder layout.
|
||||
|
||||
!PrivateServerApp Configuration
|
||||
|
||||
TiddlyWiki5 can also be run under node.js on an Internet server hosted by a cloud provider such as Amazon or Joyent. In this configuration, your data is stored on a private computer in the cloud, and you access it securely using a browser. In this way you will be able to access your data from any device, including mobile devices.
|
||||
|
||||
!Component Configuration
|
||||
|
||||
Although TiddlyWiki5 can work as an HTTP server, it is not designed for large, high traffic installations. Instead, the representation transformation engine at the heart of TiddlyWiki5 can be used as a component within more elaborate HTTP servers to enable them to offer TiddlyWiki's flexible WikiText features.
|
||||
|
||||
Work is underway to use TiddlyWiki5 within TiddlyWeb and TiddlySpace:
|
||||
@ -52,7 +62,9 @@ Work is underway to use TiddlyWiki5 within TiddlyWeb and TiddlySpace:
|
||||
https://github.com/cdent/tw5ikifier
|
||||
|
||||
!CustomBrowser Configuration
|
||||
|
||||
Many mobile platforms lack direct support in the browser to enable TiddlyWiki to save changes locally. One way around this is to use an online flavour of TiddlyWiki. A relatively straightforward option on many platforms is to write a custom application that embeds TiddlyWiki within a web browser control. For example, see these applications that work in this way with classic TiddlyWiki on iOS and Android:
|
||||
|
||||
* [[AndTidWiki|https://market.android.com/details?id=de.mgsimon.android.andtidwiki]] for Android Devices
|
||||
* [[TWMobile|http://itunes.apple.com/gb/app/twmobile/id381945222?mt=8]] for iPad
|
||||
* [[TWEdit|http://itunes.apple.com/gb/app/twedit/id409607956?mt=8]] for iPhone, iPad and iPod Touch
|
||||
|
Loading…
Reference in New Issue
Block a user