mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2025-09-09 06:16:06 +00:00
Merge the dev material back into the main tw5.com wiki
It was getting a pain to manage the content in separate places, and I suspect confusing for end users. I think the best time to move the dev content out is when we’ve established the community wiki for TW5, which is a much more natural home for it. In the meantime, a feature that I’m interested in exploring is the ability to hide tiddlers from the UI based on tag. Then the tw5.com wiki could disable all tiddlers tagged ‘dev’ until explicitly overridden by the user.
This commit is contained in:
Jermolene
@@ -1,21 +0,0 @@
|
||||
title: Building classic TiddlyWiki with TiddlyWiki5
|
||||
|
||||
TiddlyWiki5 can be used to build older 2.x.x versions of TiddlyWiki from their constituent components. Doing so involves these additional features over and above those used for building TiddlyWiki5:
|
||||
|
||||
* The `tiddlywiki2/loadrecipe` plugin, containing a deserializer module which allows tiddlers to be loaded from TiddlyWiki 2.x.x `.recipe` files
|
||||
* The `tiddlywiki2/stripcomments` plugin, containing a new viewer format for the `<$view>` widget that strips single line JavaScript comments starting `//#`
|
||||
* The `stripTitlePrefix='yes'` attribute of the `<$fields>` widget, which removes prefixes wrapped in curly braces from the `title` attribute
|
||||
** For example, `{tiddler}HelloThere` would be transformed to `HelloThere`
|
||||
|
||||
! Usage
|
||||
|
||||
TiddlyWikiClassic is built from the command line by running TiddlyWiki5 under Node.js. A typical usage would be:
|
||||
|
||||
```
|
||||
node ../../tiddlywiki.js \
|
||||
--verbose \
|
||||
--load <path_to_recipe_file> \
|
||||
--rendertiddler $:/core/templates/tiddlywiki2.template.html <path_to_write_index_file> text/plain \
|
||||
|| exit 1
|
||||
```
|
||||
|
||||
@@ -1,57 +0,0 @@
|
||||
created: 201311011114
|
||||
creator: JeremyRuston
|
||||
modified: 201311011114
|
||||
modifier: JeremyRuston
|
||||
tags: introduction
|
||||
title: Contributing
|
||||
|
||||
TiddlyWiki5 welcomes contributions to its code and documentation via [[GitHub|https://github.com/Jermolene/TiddlyWiki5]]. Please take a moment to read these notes to help make the process as smooth as possible.
|
||||
|
||||
!! Bug Reports
|
||||
|
||||
From the perspective of the developers, a bug report that says little more than "it doesn't work" can be frustrating. For effective debugging, we need as much information as possible. At a minimum, please try to include:
|
||||
|
||||
* A descriptive title
|
||||
* A summary
|
||||
* Steps to reproduce
|
||||
* Expected behaviour
|
||||
* Context (OS, browser etc.)
|
||||
|
||||
There's a lot of good material on the web about bug reports:
|
||||
|
||||
* http://mhay68.tumblr.com/post/1648223018/what-makes-a-good-bug-report
|
||||
* http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
|
||||
|
||||
!! Pull Requests
|
||||
|
||||
Like other OpenSource projects, TiddlyWiki5 needs a signed contributor license agreement from individual contributors before contributions of code can be accepted. This is a legal agreement that allows contributors to assert that they own the copyright of their contribution, and that they agree to license it to the UnaMesa Association (the legal entity that owns TiddlyWiki on behalf of the community).
|
||||
|
||||
* For individuals use: [[CLA-individual|https://github.com/Jermolene/TiddlyWiki5/tree/master/licenses/cla-individual.md]]
|
||||
* For entities use: [[CLA-entity|https://github.com/Jermolene/TiddlyWiki5/tree/master/licenses/cla-entity.md]]
|
||||
|
||||
//This is a first pass at a CLA for TiddlyWiki. Please let us know if we missed something important. If we do have to make essential changes to the CLA, there is a possibility that all contributors will need to sign it again//
|
||||
|
||||
!!! How to sign the CLA
|
||||
|
||||
```
|
||||
git clone https://github.com/Jermolene/TiddlyWiki5.git TiddlyWiki5
|
||||
cd TiddlyWiki5
|
||||
git checkout -b sign-cla
|
||||
```
|
||||
|
||||
''Add your name and the date to cla-individual.md or cla-entity.md''. Date format (YYYY/MM/DD)
|
||||
eg: `Jeremy Ruston, @Jermolene, 2011/11/22`
|
||||
|
||||
```
|
||||
git add .
|
||||
git commit -m "sign contributor license agreement"
|
||||
git push origin sign-cla
|
||||
```
|
||||
|
||||
''Go to your github repo and create a pull request.''
|
||||
|
||||
''Thank you!''
|
||||
|
||||
!!!! Attribution
|
||||
|
||||
The CLA documents used for this project where created using [[Harmony Project Templates|http://www.harmonyagreements.org]]. "~HA-CLA-I-LIST Version 1.0" for "CLA-individual" and "~HA-CLA-E-LIST Version 1.0" for "CLA-entity"
|
||||
@@ -1,24 +0,0 @@
|
||||
created: 20130822170200000
|
||||
creator: JeremyRuston
|
||||
modified: 20131126220042886
|
||||
modifier: JeremyRuston
|
||||
tags: introduction
|
||||
title: HelloThere
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
This is the developer documentation hub for TiddlyWiki. For convenience, it also contains all of the end user documentation that appears at http://five.tiddlywiki.com/.
|
||||
|
||||
! Overview
|
||||
|
||||
* TiddlyWikiArchitecture
|
||||
* [[TiddlyWiki5 Development Environment]]
|
||||
* [[Building classic TiddlyWiki with TiddlyWiki5]]
|
||||
|
||||
! Developer Cookbooks
|
||||
|
||||
<$list filter="[tag[dev]tag[howto]sort[title]]"/>
|
||||
|
||||
! Internal Objects and Mechanisms
|
||||
|
||||
<$list filter="[tag[mechanism]sort[title]]"/>
|
||||
|
||||
@@ -1,26 +0,0 @@
|
||||
created: 201308251618
|
||||
creator: JeremyRuston
|
||||
modified: 201308262048
|
||||
modifier: JeremyRuston
|
||||
tags: dev
|
||||
title: TiddlyWiki5 Development Environment
|
||||
|
||||
//This information is for people who are working on the development of TiddlyWiki5 itself, and isn't relevant for end users//
|
||||
|
||||
! Setting up npm
|
||||
|
||||
[[Installing TiddlyWiki5]] with NPM downloads a snapshot release of TiddlyWIki5. To use a development copy of the TiddlyWiki5 repository instead of the copy installed by [[NPM]], use this command within the root of the TiddlyWiki5 repo:
|
||||
|
||||
```
|
||||
npm link
|
||||
```
|
||||
|
||||
! Bumping version numbers
|
||||
|
||||
As releases are made during development it is necessary to adjust the version number of the TiddlyWiki5 core. This is done with the [[npm version|https://npmjs.org/doc/version.html]] command. For example:
|
||||
|
||||
```
|
||||
npm version 5.0.0-alpha.10
|
||||
```
|
||||
|
||||
As described in #10 in [[this article by npm's author|http://blog.izs.me/post/1675072029/10-cool-things-you-probably-didnt-realize-npm-could-do]], when run from within a git repo this command will also commit the change and tag it
|
||||
@@ -1,12 +0,0 @@
|
||||
created: 201308251621
|
||||
creator: JeremyRuston
|
||||
modified: 201308251621
|
||||
modifier: JeremyRuston
|
||||
tags: dev
|
||||
title: TiddlyWikiArchitecture
|
||||
|
||||
The heart of TiddlyWiki can be seen as an extensible representation transformation engine for text and images. 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 primary use of the engine is to convert raw `text/vnd.tiddlywiki` WikiText into a `text/html` or `text/plain` representation for display. The transclusion and templating features of WikiText allow the engine to also be used to generate TiddlyWiki HTML files from raw tiddlers.
|
||||
|
||||
If you're interested in understanding more about the internal operation of TiddlyWiki, it is recommended that you review the DeveloperDocs and read the code -- start with the boot kernel [[$:/boot/boot.js]].
|
||||
@@ -1,37 +0,0 @@
|
||||
created: 201308251501
|
||||
creator: JeremyRuston
|
||||
modified: 201308251501
|
||||
modifier: JeremyRuston
|
||||
tags: dev howto
|
||||
title: Using TiddlyWiki for GitHub Pages project documentation
|
||||
|
||||
TiddlyWiki5 can be used to produce documentation for GitHub projects. It lets you maintain a single set of documentation as a [[TiddlyWikiFolder|TiddlyWikiFolders]] containing separate tiddler files under source code control, and then use it to produce `readme.md` files for inclusion in project folders, or HTML files for storage in [[GitHub Pages|http://pages.github.com/]]. Both features are demonstrated by TiddlyWiki5 itself.
|
||||
|
||||
! Generating `readme.md` files
|
||||
|
||||
When displaying the contents of a folder GitHub will look for a `readme.md` file and display it. Note that it will not display full HTML files in this way, just static MarkDown files (this is a security measure). Happily MarkDown permits a safe subset of HTML, and thus to generate a `readme.md` file that is suitable for GitHub it is just necessary for TiddlyWiki5 to generate the content of the `<body>` element of an HTML document, and give it the appropriate filename.
|
||||
|
||||
This is done in `bld.sh` by this command:
|
||||
|
||||
```
|
||||
--rendertiddler ReadMe ./readme.md text/html
|
||||
```
|
||||
|
||||
It saves the tiddler ReadMe to the file `./readme.md` in the `text/html` format.
|
||||
|
||||
By default, tiddler links will be rendered as `<a>` links to a relative URI consisting of the title of the tiddler. This behaviour can be overridden by defining the macro `tw-wikilink-template`, as is done at the top of the tiddler ReadMe:
|
||||
|
||||
```
|
||||
\define tw-wikilink-template() http://five.tiddlywiki.com/static/$uri_encoded$.html
|
||||
```
|
||||
|
||||
See the LinkWidget for more details.
|
||||
|
||||
In this example, tiddler links are rendered as links to the static rendering of tw5.com.
|
||||
|
||||
! Publishing to GitHub Pages
|
||||
|
||||
Publishing to GitHub Pages is very straightforward. In the case of TiddlyWiki5, several different build products are published.
|
||||
|
||||
The `bld.sh` script deposits the build products directly into the local clone of the repo associated with the GitHub Pages account. There is then a manual step to review changes and push them up to github.com.
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
created: 201308251500
|
||||
creator: JeremyRuston
|
||||
modified: 201308251621
|
||||
modifier: JeremyRuston
|
||||
tags: deserializers dev
|
||||
title: TiddlerFiles
|
||||
|
||||
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 ContentType `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.
|
||||
|
||||
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 ContentType `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 ContentType `application/json` is used internally for these files//
|
||||
|
||||
!! TiddlyWiki HTML files
|
||||
|
||||
TiddlyWiki HTML files contain a collection of tiddlers encoded in `<DIV>` format.
|
||||
@@ -1,8 +0,0 @@
|
||||
color: #e37a61
|
||||
created: 201308251459
|
||||
creator: JeremyRuston
|
||||
modified: 201308251500
|
||||
modifier: JeremyRuston
|
||||
title: dev
|
||||
|
||||
See DeveloperDocs.
|
||||
@@ -1,4 +0,0 @@
|
||||
color: #cf7d89
|
||||
modified: 201306131058
|
||||
title: internals
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
created: 201308251538
|
||||
creator: JeremyRuston
|
||||
modified: 201308251538
|
||||
modifier: JeremyRuston
|
||||
title: mechanism
|
||||
|
||||
These are the internal mechanisms that fit together to make up TiddlyWiki.
|
||||
@@ -1,42 +0,0 @@
|
||||
created: 201308251429
|
||||
creator: JeremyRuston
|
||||
modified: 201310312218
|
||||
modifier: JeremyRuston
|
||||
tags: mechanism
|
||||
title: BootMechanism
|
||||
|
||||
!Introduction
|
||||
|
||||
At its heart, TiddlyWiki5 is a relatively small boot kernel that runs either under Node.js or in the browser with all other functionality added via dynamically loaded [[modules|Modules]].
|
||||
|
||||
The kernel boots just enough of the TiddlyWiki environment to allow it to load and execute module tiddlers. The module system is compatible with CommonJS and [[Node.js]].
|
||||
|
||||
There are many [[different types of module|ModuleType]]: parsers, deserializers, widgets etc. It goes much further than you might expect. For example, individual tiddler fields are modules, too: there's a module 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 plugin modules have further sub-plugins: the wikitext parser, for instance, accepts parsing rules as individual plugin modules.
|
||||
|
||||
!Plugins
|
||||
|
||||
In TiddlyWiki5, [[Plugins]] are bundles of tiddlers that are distributed and managed as one; [[Modules]] are JavaScript tiddlers with a module type identifying when and how they should be executed.
|
||||
|
||||
The tiddler [[$:/boot/boot.js]] is a barebones TiddlyWiki kernel that is just sufficient to load the core plugin modules and trigger a startup module to load up the rest of the application.
|
||||
|
||||
The boot kernel includes:
|
||||
|
||||
* Several short shared utility functions
|
||||
* A handful of methods implementing the module mechanism
|
||||
* The `$tw.Tiddler` class (and field definition plugins)
|
||||
* The `$tw.Wiki` class (and tiddler deserialization methods)
|
||||
* Code for the browser to load tiddlers from the HTML DOM
|
||||
* Code for the server to load tiddlers from the file system
|
||||
|
||||
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:
|
||||
|
||||
* Ordinary and system tiddlers, packed as HTML `<DIV>` elements
|
||||
* `core/bootprefix.js`, containing a few lines to set up the plugin environment
|
||||
* JavaScript modules, packed as HTML `<SCRIPT>` blocks
|
||||
* `core/boot.js`, containing the boot kernel
|
||||
|
||||
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.
|
||||
@@ -1,16 +0,0 @@
|
||||
title: DraftMechanism
|
||||
modified: 201308201324
|
||||
tags: mechanism
|
||||
|
||||
Tiddlers that have a `draft.of` field are treated as pending drafts of the tiddler specified in the field. Draft tiddlers should also have a `draft.title` field that specifies the title that will be given to the tiddler when it is saved.
|
||||
|
||||
Several features work in concert to give the desired behaviour for draft tiddlers:
|
||||
|
||||
* The ListWidget can optionally render draft tiddlers through a different template
|
||||
* The NavigatorWidget incorporates handlers for the following events:
|
||||
** `tw-new-tiddler` for creating a new tiddler in draft mode
|
||||
** `tw-edit-tiddler` for moving a tiddler into edit mode
|
||||
** `tw-cancel-tiddler` for cancelling a tiddler out of edit mode
|
||||
** `tw-save-tiddler` for saving a draft tiddler
|
||||
* Draft tiddlers are automatically excluded from search operations
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
created: 201308251542
|
||||
creator: JeremyRuston
|
||||
modified: 201311010906
|
||||
modifier: JeremyRuston
|
||||
tags: mechanism
|
||||
title: EncryptionMechanism
|
||||
|
||||
TiddlyWiki5 allows the entire content of a TiddlyWiki HTML file to be encrypted with the Stanford JavaScript Crypto Library. Opening an encrypted TiddlyWiki in the browser prompts for a password before decrypting and displaying the content.
|
||||
|
||||
For instructions on how to use TiddlyWiki5's encryption features, see [[How to use TiddlyWiki5 as a standalone HTML file with encryption]].
|
||||
|
||||
The EncryptionMechanism is implemented with the following elements:
|
||||
|
||||
* A PasswordVault within the BootMechanism that holds the current encryption password
|
||||
* The ability of the BootMechanism to read a block of encrypted tiddlers from the TiddlyWiki file, to prompt the user for a password, and to decrypt the tiddlers
|
||||
* Handlers for the messages [[WidgetMessage: tw-set-password]] and [[WidgetMessage: tw-clear-password]] that handle the user interface for password changes
|
||||
* The EncryptWidget within the main file template that encrypts a filtered list of tiddlers with the currently held password
|
||||
* The [[$:/isEncrypted]] tiddler that contains "yes" or "no" according to whether there is a password in the password vault
|
||||
** The availability of this tiddler allows the RevealWidget to be used to selectively display user interface elements according to whether encryption is in force
|
||||
* The [[$:/snippets/encryptionstatus]] snippet displays the current encryption status
|
||||
@@ -1,10 +0,0 @@
|
||||
created: 201308251625
|
||||
creator: JeremyRuston
|
||||
modified: 201308251626
|
||||
modifier: JeremyRuston
|
||||
tags: dev mechanism
|
||||
title: LazyLoadingMechanism
|
||||
|
||||
TiddlyWiki5 currently only implements lazy loading when its running in the browser talking to a TiddlyWeb-compatible server. When it syncs, it first requests a "skinny" version of each tiddler (consisting of all the fields apart from the text field). Subsequently, an attempt to read those skinny tiddlers with `wiki.getTiddler()` returns just the skinny fields, but an attempt to read one using `wiki.getTiddlerText()` will trigger an asynchronous load of the full tiddler text, which in turn triggers a refresh cycle, updating the display to reflect the newly loaded tiddler. Widgets that loop through all tiddlers are fine; it's only if they trigger `wiki.getTiddlerText()` for a tiddler that it will get loaded.
|
||||
|
||||
So, the browser-based search built into TiddlyWiki5 will only search the text of tiddlers that have been fully loaded. The expectation is that when lazy loading is used in a client-server configuration, then it's the server that really needs to handle search operations, because it's only the server that can "see" the text of all tiddlers. So, the plan is to integrate TW's built in search with TiddlyWeb's search API. The simplest approach is that any local search triggers an asynchronous server side search. The results of the search would be asynchronously loaded such that they would dynamically appear in the local search results.
|
||||
@@ -1,45 +0,0 @@
|
||||
title: ParsingMechanism
|
||||
tags: mechanism
|
||||
created: 201311011307
|
||||
modified: 201311011307
|
||||
|
||||
! Introduction
|
||||
|
||||
The parsing mechanism analyses the text of a tiddler against a set of parsing rules, producing a tree representing the structure of the text. The RenderingMechanism is used to transform parse trees into render trees of widget nodes.
|
||||
|
||||
TiddlyWiki5 includes ParserModules for several types of tiddler:
|
||||
|
||||
* WikiText
|
||||
* Raw HTML
|
||||
* Plain text
|
||||
* Images (bitmap, SVG and PDF)
|
||||
|
||||
The WikiText parser is the most complex, comprising separate individual WikiRuleModules encapsulating each parsing rule.
|
||||
|
||||
! Parse Trees
|
||||
|
||||
The output of parsing a tiddler is an object containing a tree of parse nodes corresponding to the original text. For example:
|
||||
|
||||
```
|
||||
> JSON.stringify($tw.wiki.parseText("text/vnd.tiddlywiki","Some //italics// and a {{Transclusion}}.").tree)
|
||||
|
||||
[
|
||||
{type: "element", tag: "p", children: [
|
||||
{type: "text", text: "Some "},
|
||||
{type: "element", tag: "em", children: [
|
||||
{type: "text", text: "italics"}
|
||||
]},
|
||||
{type: "text", text: " and a "},
|
||||
{type: "tiddler", attributes:{
|
||||
tiddler: {type: "string", value: "Transclusion"}
|
||||
}, children:[
|
||||
{type: "transclude", attributes:{
|
||||
tiddler: {type: "string", value: "Transclusion"}
|
||||
}}
|
||||
]},
|
||||
{type: "text", text: "."}
|
||||
]}
|
||||
]
|
||||
```
|
||||
|
||||
Parse tree nodes are plain JavaScript objects, and do not have a prototype.
|
||||
@@ -1,82 +0,0 @@
|
||||
created: 201308261220
|
||||
creator: JeremyRuston
|
||||
modified: 201308261220
|
||||
modifier: JeremyRuston
|
||||
tags: mechanism
|
||||
title: PluginMechanism
|
||||
|
||||
[[Plugins]] are bundles of tiddlers that are distributed and managed as a single unit by being packed into a single JSON tiddler. If a tiddler isn't found in the main store, then the registered plugins are searched for it instead.
|
||||
|
||||
Tiddlers within plugins behave something like shadow tiddlers in classic TiddlyWiki: they can be freely overwritten by creating a tiddler with the same title, but deleting that tiddler restores the underlying tiddler value from the plugin.
|
||||
|
||||
Plugins have a `plugin-type` field that may be:
|
||||
|
||||
* `plugin` //(default)// - a plain plugin
|
||||
* `theme` - a theme plugin (see ThemeMechanism)
|
||||
|
||||
Plugins can be used to package ordinary content, or can include JavaScript [[modules|Modules]] that extend and enhance the core TiddlyWiki5 functionality.
|
||||
|
||||
Plugins conventionally have a title of the form `$:/plugins/publisher/name`. Plugins that are part of the core TiddlyWiki distribution have titles of the form `$:/plugins/tiddlywiki/name`.
|
||||
|
||||
Plugins that define macros, views or other named entities are expected to prefix the name with their publisher identifier, for example: `tiddlytools.slider`.
|
||||
|
||||
! Plugin format
|
||||
|
||||
Plugins are stored as tiddlers of type `application/json` with the field `plugin-type` present and the text containing a JSON structure encoding the plugin metadata and the list of tiddlers within it.
|
||||
|
||||
The JSON structure for plugin tiddlers is as follows:
|
||||
|
||||
```
|
||||
{
|
||||
"title": "$:/plugins/publisher/name",
|
||||
"description": "An exemplary plugin for demonstration purposes",
|
||||
"author": "JeremyRuston",
|
||||
"version": "1.2.3-alpha3",
|
||||
"coreVersion": ">=5.0.0",
|
||||
"source": "http://tiddlywiki.com/MyPlugin",
|
||||
"plugin-type": "plugin",
|
||||
"tiddlers": {
|
||||
"$:/plugins/publisher/name/title1": {"type": "image/png", "text": "<base64>"},
|
||||
"title2": {"text": "Text"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The titles of the individual tiddlers are typically prefixed with the title of the containing plugin (as in the ''title1'' example above), but they are not restricted to do so (the second example specifies a tiddler with the raw title ''title2'').
|
||||
|
||||
! Plugin folders
|
||||
|
||||
On the server, plugins can be stored as ordinary JSON tiddlers but it is often more convenient to store them as separate tiddler files within folders. Plugin folders must contain a `plugin.info` file that contains the metadata for the plugin. It can also optionally identify files external to the plugin folder that should be loaded as tiddlers.
|
||||
|
||||
The `plugin.info` file should contain the same JSON as given for plugin tiddlers above, with the `tiddlers` object omitted.
|
||||
|
||||
Note that if the `version` field is omitted from a `plugin.info` file when the plugin folder is packed then it is automatically filled in by the core to the current core version number. This is to ensure that all the core plugins carry the correct version number. Generally plugin authors will want to ensure that they do explicitly specify a version number.
|
||||
|
||||
! Plugin library
|
||||
|
||||
The standard distribution of TiddlyWiki includes a number of standard plugins in the `plugins` directory.
|
||||
|
||||
! Including plugins in a wiki
|
||||
|
||||
To be usable in the browser, plugins just need to be included in the wiki. This is done when the wiki is generated on the server.
|
||||
|
||||
A folder containing an exploded TiddlyWiki can contain a `tiddlywiki.info` file that identifies the plugins to be included in this wiki:
|
||||
|
||||
```
|
||||
{
|
||||
"plugins": [
|
||||
"tiddlywiki/slider",
|
||||
"tiddlytools/chooser"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Plugins names refer to plugin folders listed in TiddlyWiki5's root `plugins` folder.
|
||||
|
||||
Plugins can also be included manually by copying them into the `plugins` subfolder of the wiki.
|
||||
|
||||
! Plugin processing
|
||||
|
||||
The wiki object keeps track of all of the currently loaded plugins. If a request for a tiddler isn't in the store then the wiki looks through the cascade of plugins to find the requested tiddler. It is a similar idea to the way that shadow tiddlers are implemented in classic TiddlyWiki.
|
||||
|
||||
In the browser, any constituent tiddlers that are JavaScript modules (ie shadow tiddlers of content type `application/javascript` and possessing the field `module-type`) are executed during startup processing.
|
||||
@@ -1,5 +0,0 @@
|
||||
title: RenderingMechanism
|
||||
tags: mechanism
|
||||
created: 201311011307
|
||||
modified: 201311011307
|
||||
|
||||
@@ -1,36 +0,0 @@
|
||||
modified: 201311222159
|
||||
tags: dev
|
||||
title: TestingMechanism
|
||||
|
||||
TiddlyWiki5 incorporates the Jasmine JavaScript testing framework (see http://pivotal.github.io/jasmine/). It allows the same tests to be run both in the browser and under Node.js.
|
||||
|
||||
! TiddlyWiki5 Testing Components
|
||||
|
||||
There are two main elements to the TiddlyWiki5 testing mechanism:
|
||||
|
||||
* The plugin `tiddlywiki/jasmine` that wraps Jasmine up into a plugin along with some glue code
|
||||
* The TiddlyWiki5 edition `test` that contains the core test specifications and includes the Jasmine plugin
|
||||
|
||||
! Running the Tests in Node.js
|
||||
|
||||
To run the tests under Node.js just load up the `test` wiki:
|
||||
|
||||
```
|
||||
node ./tiddlywiki.js \
|
||||
./editions/test \
|
||||
```
|
||||
|
||||
! Running the Tests in the Browser
|
||||
|
||||
To generate a wiki containing the browser tests load up the `test` wiki and save it as an HTML file:
|
||||
|
||||
```
|
||||
node ./tiddlywiki.js \
|
||||
./editions/test \
|
||||
--verbose \
|
||||
--rendertiddler $:/core/save/all $TW5_BUILD_OUTPUT/test.html text/plain \
|
||||
```
|
||||
|
||||
Then, open the `test.html` file in the browser to see the test results. There is a prebuilt version of `test.html` at:
|
||||
|
||||
http://five.tiddlywiki.com/test.html
|
||||
@@ -1,101 +0,0 @@
|
||||
created: 201308251621
|
||||
creator: JeremyRuston
|
||||
modified: 201311011307
|
||||
modifier: JeremyRuston
|
||||
tags: dev moduletypes
|
||||
title: SyncAdaptorModules
|
||||
|
||||
! Introduction
|
||||
|
||||
SyncAdaptorModules encapsulate storage mechanisms that can be used by the SyncMechanism. Two examples are:
|
||||
|
||||
* The TiddlyWebAdaptor interfaces with servers compatible with TiddlyWeb's HTTP API, such as TiddlyWeb itself and TiddlyWiki5's built-in ServerMechanism.
|
||||
|
||||
* The LocalFileAdaptor interfaces with file systems with an API compatible with Node.js's `fs` module
|
||||
|
||||
SyncAdaptorModules are represented as JavaScript tiddlers with the field `module-type` set to `syncadaptor`.
|
||||
|
||||
! Exports
|
||||
|
||||
The following properties should be exposed via the `exports` object:
|
||||
|
||||
|!Property |!Description |
|
||||
|adaptorClass |The JavaScript class for the adaptor |
|
||||
|
||||
Nothing should be exported if the adaptor detects that it isn't capable of operating successfully (eg, because it only runs on either the browser or the server, or because a dependency is missing).
|
||||
|
||||
! Adaptor Module Methods
|
||||
|
||||
Adaptor modules must handle the following methods.
|
||||
|
||||
!! `Constructor(syncer)`
|
||||
|
||||
Initialises a new adaptor instance.
|
||||
|
||||
|!Parameter |!Description |
|
||||
|syncer |Syncer object that is using this adaptor |
|
||||
|
||||
!! `getTiddlerInfo(tiddler)`
|
||||
|
||||
Gets the supplemental information that the adaptor needs to keep track of for a particular tiddler. For example, the TiddlyWeb adaptor includes a `bag` field indicating the original bag of the tiddler.
|
||||
|
||||
|!Parameter |!Description |
|
||||
|tiddler |Target tiddler |
|
||||
|
||||
Returns an object storing any additional information required by the adaptor.
|
||||
|
||||
!! `getStatus(callback)`
|
||||
|
||||
Retrieves status information from the server. This method is optional.
|
||||
|
||||
|!Parameter |!Description |
|
||||
|callback |Callback function invoked with parameters `err,isLoggedIn,username` |
|
||||
|
||||
!! `login(username,password,callback)`
|
||||
|
||||
Attempts to login to the server with specified credentials. This method is optional.
|
||||
|
||||
|!Parameter |!Description |
|
||||
|username |Username |
|
||||
|password |Password |
|
||||
|callback |Callback function invoked with parameter `err` |
|
||||
|
||||
!! `logout(callback)`
|
||||
|
||||
Attempts to logout of the server. This method is optional.
|
||||
|
||||
|!Parameter |!Description |
|
||||
|callback |Callback function invoked with parameter `err` |
|
||||
|
||||
!! `getSkinnyTiddlers(callback)`
|
||||
|
||||
Retrieves a list of skinny tiddlers from the server.
|
||||
|
||||
This method is optional. If an adaptor doesn't implement it then synchronisation will be unidirectional from the TiddlyWiki store to the adaptor, but not the other way.
|
||||
|
||||
|!Parameter |!Description |
|
||||
|callback |Callback function invoked with parameter `err,tiddlers`, where `tiddlers` is an array of tiddler field objects |
|
||||
|
||||
!! `saveTiddler(tiddler,callback)`
|
||||
|
||||
Saves a tiddler to the server.
|
||||
|
||||
|!Parameter |!Description |
|
||||
|tiddler |Tiddler to be saved |
|
||||
|callback |Callback function invoked with parameter `err,adaptorInfo,revision` |
|
||||
|
||||
!! `loadTiddler(title,callback)`
|
||||
|
||||
Loads a tiddler from the server.
|
||||
|
||||
|!Parameter |!Description |
|
||||
|title |Title of tiddler to be retrieved |
|
||||
|callback |Callback function invoked with parameter `err,tiddlerFields` |
|
||||
|
||||
!! `deleteTiddler(title,callback)`
|
||||
|
||||
Delete a tiddler from the server.
|
||||
|
||||
|!Parameter |!Description |
|
||||
|title |Title of tiddler to be deleted |
|
||||
|callback |Callback function invoked with parameter `err` |
|
||||
@@ -1,81 +0,0 @@
|
||||
title: WidgetModules
|
||||
tags: dev moduletypes
|
||||
created: 201311011307
|
||||
modified: 201311011307
|
||||
|
||||
! Introduction
|
||||
|
||||
Widget modules are used as part of the RenderingMechanism to implement each type of renderable entity. As well as the widgets that are familiar to end users, the following primitives are also implemented as widgets:
|
||||
|
||||
* HTML text nodes
|
||||
* HTML element nodes
|
||||
* HTML entities
|
||||
|
||||
All widgets inherit from a base widget class that is defined in [[$:/core/modules/widgets/widget.js]].
|
||||
|
||||
! Widget Properties
|
||||
|
||||
The following widget properties are defined by the core. The lifecycle of a widget object is largely a matter of maintaining the consistency of these internal properties in the face of external state changes. Individual widgets usually add their own additional properties too.
|
||||
|
||||
|!Name |!Description |
|
||||
|''parseTreeNode'' |Reference to the parse tree node corresponding to this widget |
|
||||
|''wiki'' |Reference to the [[Wiki]] object associated with this widget |
|
||||
|''variables'' |Hashmap of information about each [[widget variable|WidgetVariables]] (see below) |
|
||||
|''parentWidget'' |Reference to the parent widget |
|
||||
|''document'' |Reference to the document object associated with this widget. Usually either the browser global `document` variable or a reference to the FakeDomMechanism's `$tw.document` |
|
||||
|''attributes'' |Hashmap of information about each attribute attached to this widget (see below) |
|
||||
|''children'' |Array of child widgets |
|
||||
|''domNodes'' |For widgets that directly generate DOM nodes, an array of the generated nodes |
|
||||
|''eventListeners'' |Array of event listener definitions |
|
||||
|
||||
!! Widget Variables
|
||||
|
||||
The widget variables defined on a widget are stored in a hashmap of the variable name. The hashmap contains:
|
||||
|
||||
* `name`: name of variable
|
||||
* `params`: array of parameters for macro definitions, each `{name: "<name>", default: "<optionaldefault>"}`
|
||||
* `value`: string value of variable
|
||||
|
||||
!! Widget Attributes
|
||||
|
||||
The widget attributes associated with a widget are stored in a hashmap of the attribute name. The hashmap contains an object that describes the attribute value. Currently three attribute value types are supported:
|
||||
|
||||
* Strings: `{type: "string", value: "<value>"}`
|
||||
* Tiddler text reference indirection: `{type: "indirect", textReference: "<textref>"}`
|
||||
* Macro invocation: `{type: "macro", value: {name: "<macroname>", params: [{name: "<paramname>", value: "<paramvalue>"}, ... ]}`
|
||||
|
||||
!! Widget Event Listeners
|
||||
|
||||
The event listeners attached to a widget are stored as a hashmap by event type. Each value is a handler function that accepts a single `event` parameter.
|
||||
|
||||
! Widget methods
|
||||
|
||||
The individual methods defined by the widget object are documented in the source code of [[$:/core/modules/widgets/widget.js]]. Here we give an overview of the overall lifecycle, and how the methods fit together
|
||||
|
||||
!! Widget `initialise` method
|
||||
!! Widget `widgetClasses` method
|
||||
!! Widget `render` method
|
||||
!! Widget `execute` method
|
||||
!! Widget `getVariable` method
|
||||
!! Widget `substituteVariableParameters` method
|
||||
!! Widget `substituteVariableReferences` method
|
||||
!! Widget `evaluateMacroModule` method
|
||||
!! Widget `setVariable` method
|
||||
!! Widget `hasVariable` method
|
||||
!! Widget `getStateQualifier` method
|
||||
!! Widget `computeAttributes` method
|
||||
!! Widget `hasAttribute` method
|
||||
!! Widget `getAttribute` method
|
||||
!! Widget `assignAttributes` method
|
||||
!! Widget `makeChildWidgets` method
|
||||
!! Widget `makeChildWidget` method
|
||||
!! Widget `renderChildren` method
|
||||
!! Widget `addEventListeners` method
|
||||
!! Widget `addEventListener` method
|
||||
!! Widget `dispatchEvent` method
|
||||
!! Widget `refresh` method
|
||||
!! Widget `refreshSelf` method
|
||||
!! Widget `refreshChildren` method
|
||||
!! Widget `findNextSiblingDomNode` method
|
||||
!! Widget `findFirstDomNode` method
|
||||
!! Widget `removeChildDomNodes` method
|
||||
@@ -1,33 +0,0 @@
|
||||
created: 201308252147
|
||||
creator: JeremyRuston
|
||||
modified: 201311011307
|
||||
modifier: JeremyRuston
|
||||
tags: dev moduletypes
|
||||
title: WikiRuleModules
|
||||
|
||||
WikiRuleModules cover the module types `wikirunrule`, `wikiblockrule` and `wikipragmarule`. Modules of these types encapsulate the logic of individual parsing rules used by the WikiParser engine. For example, there is a `wikirunrule` module that identifies references to HTML entities by matching the pattern `&<chars>;`.
|
||||
|
||||
Pragma rules are applied at the start of a block of text, and cover definitions and declarations that affect the parsing of the rest of the text. Block rules are only applied at the beginning of a block of wikitext, while run rules can appear anywhere. The only current example of a pragma rule is for macro definitions.
|
||||
|
||||
Examples of block rules:
|
||||
|
||||
* Headings
|
||||
* Tables
|
||||
* Lists
|
||||
|
||||
Examples of run rules:
|
||||
|
||||
* Entities
|
||||
* HTML tags
|
||||
* Wiki links
|
||||
|
||||
Parser rule modules extend the `$tw.WikiParserRule` class. This is done by instantiating the class and then copying the exports of the rule module onto the instance. In this way, the parser rule can override the base behaviour of the `$tw.WikiParserRule` class. In particular, the base class incorporates logic for using regular expressions to match parse rules but this logic could be overridden by a parse rule that wanted to, say, use `indexOf()` instead of regular expressions.
|
||||
|
||||
The standard methods and properties of parser rules are as follows:
|
||||
|
||||
* `name`: a string containing the name of this parse rule
|
||||
* `init(parser)`: initialisation function called immediately after the constructor with a pointer back to the parser containing this rule
|
||||
* `findNextMatch(pos)`: returns the position of the next match after the specified position
|
||||
* `parse()`: parses the most recent match, returning an array of the generated parse tree nodes. Pragma rules don't return parse tree nodes but instead modify the parser object directly (for example, to add local macro definitions)
|
||||
|
||||
The built in parser rules use regular expression matching. Such rules can take advantage of the implementation of `findNextMatch()` in the base `$tw.WikiRule` class by ensuring that their `init()` method creates a `matchRegExp` property containing the regular expression to match. The `match` property contains the details of the match for use in the `parse()` method.
|
||||
@@ -1,12 +0,0 @@
|
||||
created: 201308251449
|
||||
creator: JeremyRuston
|
||||
modified: 201308251449
|
||||
modifier: JeremyRuston
|
||||
title: ContributingTemplate
|
||||
|
||||
\define tw-wikilink-template() http://five.tiddlywiki.com/static/$uri_encoded$.html
|
||||
! Contributing to TiddlyWiki5
|
||||
|
||||
{{Contributing}}
|
||||
|
||||
//This file was automatically generated by TiddlyWiki5//
|
||||
@@ -1,12 +0,0 @@
|
||||
title: ReadMe
|
||||
|
||||
\define tw-wikilink-template() http://five.tiddlywiki.com/static/$uri_encoded$.html
|
||||
! Welcome to TiddlyWiki5
|
||||
|
||||
{{HelloThere}}
|
||||
|
||||
! Getting started with TiddlyWiki under Node.js
|
||||
|
||||
{{TiddlyWiki5 Node Edition}}
|
||||
|
||||
//This readme file was automatically generated by TiddlyWiki5//
|
||||
@@ -1,5 +0,0 @@
|
||||
title: TiddlyWiki2ReadMe
|
||||
|
||||
\define tw-wikilinks() no
|
||||
! Building classic TiddlyWiki with TiddlyWiki5
|
||||
{{Building classic TiddlyWiki with TiddlyWiki5}}
|
||||
@@ -1,6 +0,0 @@
|
||||
title: $:/DefaultTiddlers
|
||||
|
||||
HelloThere
|
||||
Resources
|
||||
ReleaseHistory
|
||||
RoadMap
|
||||
@@ -1,4 +0,0 @@
|
||||
title: SiteSubtitle
|
||||
modifier: JeremyRuston
|
||||
|
||||
developer information for ~TiddlyWiki5
|
||||
@@ -1,4 +0,0 @@
|
||||
title: SiteTitle
|
||||
modifier: JeremyRuston
|
||||
|
||||
five.tiddlywiki.com/dev
|
||||
@@ -1,3 +0,0 @@
|
||||
title: $:/theme
|
||||
|
||||
$:/themes/tiddlywiki/nighttime
|
||||
@@ -1,14 +0,0 @@
|
||||
{
|
||||
"plugins": [
|
||||
"tiddlywiki/fullscreen",
|
||||
"tiddlywiki/googleanalytics",
|
||||
"tiddlywiki/github-fork-ribbon"
|
||||
],
|
||||
"themes": [
|
||||
"tiddlywiki/nighttime",
|
||||
"tiddlywiki/vanilla"
|
||||
],
|
||||
"includeWikis": [
|
||||
"../tw5.com"
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user