diff --git a/readme.md b/readme.md index bd131bf1a6..88ef23e126 100644 --- a/readme.md +++ b/readme.md @@ -1,5 +1,5 @@ -

Welcome to TiddlyWiki5

Welcome to TiddlyWiki5, a reboot of TiddlyWiki, the venerable, reusable non-linear personal web notebook first released in 2004. It is a complete interactive wiki that can run from a single HTML file in the browser or as a powerful node.js application.

TiddlyWiki offers a radically improved way of managing your data compared to traditional documents and emails. The fundamental idea is that information is more useful and reusable if we cut up into the smallest semantically meaningful chunks and use links, tags and macros to model the structured relationships between them. TiddlyWiki aims to provide a fluid interface for working with tiddlers, allowing them to be aggregated and composed into longer narratives.

TiddlyWiki5 is at an incomplete early alpha stage, and is not yet ready for general use. But it's the best possible time to get involved and support its future development. You can:

Usage

Architecture

Overview

The heart of TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated ContentType, the engine can produce a rendering of the tiddler in a new ContentType. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.

The most important transformations are from text/x-tiddlywiki wikitext into text/html or text/plain but the engine is used throughout the system for other transformations, such as converting images for display in HTML, sanitising fragments of JavaScript, and processing CSS.

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.

Plugin Mechanism

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.

There are several different types of plugins: parsers, serializers, deserializers, macros etc. It goes much further than you might expect. For example, individual tiddler fields are plugins, too: there's a plugin that knows how to handle the tags field, and another that knows how to handle the special behaviour of +

Welcome to TiddlyWiki5

Welcome to TiddlyWiki5, a reboot of TiddlyWiki, the venerable, reusable non-linear personal web notebook first released in 2004. It is a complete interactive wiki that can run from a single HTML file in the browser or as a powerful node.js application.

TiddlyWiki offers a radically improved way of managing your data compared to traditional documents and emails. The fundamental idea is that information is more useful and reusable if we cut up into the smallest semantically meaningful chunks and use links, tags and macros to model the structured relationships between them. TiddlyWiki aims to provide a fluid interface for working with tiddlers, allowing them to be aggregated and composed into longer narratives.

TiddlyWiki5 is at an incomplete early alpha stage, and is not yet ready for general use. But it's the best possible time to get involved and support its future development. You can:

Usage

Architecture

Overview

The heart of TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated ContentType, the engine can produce a rendering of the tiddler in a new ContentType. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.

The most important transformations are from text/x-tiddlywiki wikitext into text/html or text/plain but the engine is used throughout the system for other transformations, such as converting images for display in HTML, sanitising fragments of JavaScript, and processing CSS.

You can explore this mechanism by opening the JavaScript console in your browser. Typing this command will replace the text of the tiddler HelloThere with new content:

$tw.wiki.addTiddler({title: "HelloThere", text: "This is some new content"});

If the tiddler HelloThere is visible then you'll see it instantly change to reflect the new content. If you create a tiddler that doesn't currently exist then you'll see any displayed links to it instantly change from italicised to normal:

$tw.wiki.addTiddler({title: "TiddlyWiki5", text: "This tiddler now exists"});

The power of this mechanism also drives the interactive features of TiddlyWiki. For example, try typing the following into the JavaScript console:

$tw.wiki.addTiddler({title: "ViewDropDownState", text: "(50,50,200,200)"});

You should see the view dropdown appear in the middle of the screen. The underlying mechanism is that the creation of the tiddler with this title triggers the display of the popup at the specified location.

If you're interested in understanding more about the internal operation of TiddlyWiki, it is recommended that you review the Docs and read the code – start with the boot kernel $:/core/boot.js. +

Plugin Mechanism

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.

There are several different types of plugins: parsers, serializers, deserializers, macros etc. It goes much further than you might expect. For example, individual tiddler fields are plugins, too: there's a plugin that knows how to handle the tags field, and another that knows how to handle the special behaviour of 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:

Each module is an ordinary node.js-style module, using the require() function to access other modules and the exports global to return JavaScript values. The boot kernel smooths over the differences between node.js and the browser, allowing the same plugin modules to execute in both environments.

In the browser, core/boot.js is packed into a template HTML file that contains the following elements in order:

On the server, core/boot.js is executed directly. It uses the node.js local file API to load plugins directly from the file system in the core/modules directory. The code loading is performed synchronously for brevity (and because the system is in any case inherently blocked until plugins are loaded).

The boot kernel sets up the $tw global variable that is used to store all the state data of the system.

Core

The 'core' is the boot kernel plus the set of plugin modules that it loads. It contains plugins of the following types:

TiddlyWiki5 makes extensive use of JavaScript inheritance:

tiddlywiki.plugin files

This readme file was automatically generated by TiddlyWiki5

\ No newline at end of file diff --git a/tw5.com/tiddlers/TiddlyWikiArchitecture.tid b/tw5.com/tiddlers/TiddlyWikiArchitecture.tid index 8724c891cb..b2194c3130 100644 --- a/tw5.com/tiddlers/TiddlyWikiArchitecture.tid +++ b/tw5.com/tiddlers/TiddlyWikiArchitecture.tid @@ -2,27 +2,30 @@ title: TiddlyWikiArchitecture modifier: JeremyRuston tags: docs internals -!! Overview +! Overview The heart of TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated ContentType, the engine can produce a rendering of the tiddler in a new ContentType. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents. The most important transformations are from `text/x-tiddlywiki` wikitext into `text/html` or `text/plain` but the engine is used throughout the system for other transformations, such as converting images for display in HTML, sanitising fragments of JavaScript, and processing CSS. -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 `<>`. 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: +You can explore this mechanism by opening the JavaScript console in your browser. Typing this command will replace the text of the tiddler `HelloThere` with new content: {{{ -<> +$tw.wiki.addTiddler({title: "HelloThere", text: "This is some new content"}); }}} -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 `<>` 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`: +If the tiddler `HelloThere` is visible then you'll see it instantly change to reflect the new content. If you create a tiddler that doesn't currently exist then you'll see any displayed links to it instantly change from italicised to normal: {{{ -var storyTiddler = store.getTiddler("MyStoryTiddler"); -store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + "\n" + storyTiddler.text})); +$tw.wiki.addTiddler({title: "TiddlyWiki5", text: "This tiddler now exists"}); }}} -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. +The power of this mechanism also drives the interactive features of TiddlyWiki. For example, try typing the following into the JavaScript console: +{{{ +$tw.wiki.addTiddler({title: "ViewDropDownState", text: "(50,50,200,200)"}); +}}} +You should see the view dropdown appear in the middle of the screen. The underlying mechanism is that the creation of the tiddler with this title triggers the display of the popup at the specified location. + +If you're interested in understanding more about the internal operation of TiddlyWiki, it is recommended that you review the [[Docs]] and read the code -- start with the boot kernel [[$:/core/boot.js]]. diff --git a/tw5.com/tiddlers/concepts/TiddlerFilters.tid b/tw5.com/tiddlers/concepts/TiddlerFilters.tid index d75088a91a..93bea9d092 100644 --- a/tw5.com/tiddlers/concepts/TiddlerFilters.tid +++ b/tw5.com/tiddlers/concepts/TiddlerFilters.tid @@ -5,23 +5,21 @@ TiddlyWiki has a special syntax for expressing filters. They can be used to sele The mechanism is easiest to understand by first presenting some example filter strings: -|!Filter |!Results | -|`HelloThere` |The single tiddler titled `HelloThere` (if it exists) | -|`[[A Title With Several Words]]` |The single tiddler titled `A Title With Several Words` (if it exists) | -|`[title[MyTiddler]]` |The single tiddler titled `MyTiddler` (if it exists) | -|`HelloThere Introduction` |The tiddlers titled `HelloThere` and `Introduction` (if they exist) | -|`[tag[important]]` |Any tiddlers with the tag `important` | -|`[!tag[important]]` |Any tiddlers not with the tag `important` | -|`[tag[important]sort[title]]` |Any tiddlers with the tag `important` sorted by title | -|`[tag[important]!sort[title]]` |Any tiddlers with the tag `important` reverse sorted by title | -|`[[one][two][three]tag[tom]]` |Any of the tiddlers called `one`, `two` or `three` that exist and are tagged with `tom` | -|`[[one][two][three]] [tag[tom]]` |Any of the tiddlers called `one`, `two` or `three` that exist, along with all of the source tiddlers that are tagged with `tom` | -|`[tag[tom]] [tag[harry]] -[[one][two][three]]` |All tiddlers tagged either `tom` or `harry`, but excluding `one`, `two` and `three` | +* `HelloThere` - the single tiddler titled `HelloThere` (if it exists) +* `[[A Title With Several Words]]` - the single tiddler titled `A Title With Several Words` (if it exists) +* `[title[MyTiddler]]` - the single tiddler titled `MyTiddler` (if it exists) +* `HelloThere Introduction` - The tiddlers titled `HelloThere` and `Introduction` (if they exist) +* `[tag[important]]` - any tiddlers with the tag `important` +* `[!tag[important]]` - any tiddlers not with the tag `important` +* `[tag[important]sort[title]]` - any tiddlers with the tag `important` sorted by title +* `[tag[important]!sort[title]]` - any tiddlers with the tag `important` reverse sorted by title +* `[[one][two][three]tag[tom]]` - any of the tiddlers called `one`, `two` or `three` that exist and are tagged with tom` +* `[[one][two][three]] [tag[tom]]` - any of the tiddlers called `one`, `two` or `three` that exist, along with all of the source tiddlers that are tagged with `tom` +* `[tag[tom]] [tag[harry]] -[[one][two][three]]` - all tiddlers tagged either `tom` or `harry`, but excluding `one`, two` and `three` +* `[[MyTiddler]tags[]]` - all tiddlers being used as tags on the tiddler `MyTiddler` +* `[[MyTiddler]tagging[]]` - all tiddlers being tagged with `MyTiddler` -{{{ -[[one]] [[two]] [tag[three]] -[[four]] +[sort[title]] -[tag[important]] -[[one][two]] -[[three]] +[sort[-modified]limit[20]] -}}} +! Explanation A filter string consists of one or more filter operations, each comprising one or more filter operators with associated operands. @@ -31,9 +29,13 @@ The operators look like `[operator[operand]]`, where `operator` is one of: * ''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 * ''sort'': sorts the tiddlers by a given field +* ''sort-case-sensitive'': sorts the tiddlers by a given field with case sensitivity (ie, "a" and "A" are sorted differently) +* ''prefix'': tests whether a tiddlers title starts with a particular prefix * ''limit'': limits the number of subresults * ''tag'': tests whether a given tag is (`[tag[mytag]]`) or is not (`[!tag[mytag]]`) present on the tiddler * ''{field}'': tests whether a tiddler field has a specified value (`[modifier[Jeremy]]`) or not (`[!modifier[Jeremy]]`) +* ''tags'': selects the tags on the currently selected tiddlers +* ''tagging'': selects the tiddlers tagged with the currently selected tiddlers An operator can be negated with by preceding it with `!`, for example `[!tag[Tommy]]` selects the tiddlers that are not tagged with `Tommy`. diff --git a/tw5.com/tiddlers/concepts/Tiddlers.tid b/tw5.com/tiddlers/concepts/Tiddlers.tid index caab705601..c942521b78 100644 --- a/tw5.com/tiddlers/concepts/Tiddlers.tid +++ b/tw5.com/tiddlers/concepts/Tiddlers.tid @@ -1,10 +1,14 @@ title: Tiddlers tags: docs concepts -Tiddlers are an immutable dictionary of name:value pairs called fields. +Tiddlers are the smallest unit of information in TiddlyWiki. -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}}}. +Internally, 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 listed below. The behaviour and type of each field is determined by special TiddlerFieldModules. -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 ContentType. \ No newline at end of file +* `title` - The unique title of the tiddler +* `modified` - The date of the last modification to the tiddler +* `modifier` - The name of the last person to modify the tiddler +* `created` - The date the tiddler was created +* `creator` - The name of the person who created the tiddler +* `tags` - A list of tags applied to the tiddler +* `type` - The ContentType that should used to interpret the content of the tiddler diff --git a/tw5.com/tiddlers/concepts/WikiText.tid b/tw5.com/tiddlers/concepts/WikiText.tid index abb3e676e2..d959e01992 100644 --- a/tw5.com/tiddlers/concepts/WikiText.tid +++ b/tw5.com/tiddlers/concepts/WikiText.tid @@ -203,6 +203,20 @@ Renders as: --- +! Images + +To display an image stored in a tiddler: + +{{{ +[img[Motovun Jack.jpg]] +}}} + +Displays as: + +[img[Motovun Jack.jpg]] + +See ImageWikiText for more details. + ! HTML in WikiText HTML tags can be used directly in WikiText. For example: @@ -234,3 +248,43 @@ Headings are specified with one or more leading `!` characters: !!! This is a level 3 heading }}} + +! Other WikiText features + +!! Typed Blocks + +You can incorporate text of a different type within blocks of WikiText. For example: + +{{{ +$$$.js +return 2 + "string"; +$$$ +}}} + +Renders as: + +$$$.js +return 2 + "string"; +$$$ + +See TypedBlockWikiText for more details + +!! Style Blocks + +You can apply HTML attributes to blocks of content with this syntax: + +{{{ +@@color:#f00; +@@text-decoration:underline; +This is in red! +@@ +}}} + +Generates the results: + +@@color:#f00; +@@text-decoration:underline; +This is in red! +@@ + +See StyleBlockWikiText for more details. \ No newline at end of file