1
0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2025-02-04 13:19:11 +00:00

Docs update

Hopefully fixing #309
This commit is contained in:
Jermolene 2013-12-28 17:57:11 +00:00
parent d69614259f
commit ac81d9d43f
9 changed files with 171 additions and 5 deletions

View File

@ -0,0 +1,15 @@
created: 20131228164411884
modified: 20131228164955084
tags: releasenote
title: Release 5.0.6-beta
type: text/vnd.tiddlywiki
//[[See GitHub for detailed change history of this release|https://github.com/Jermolene/TiddlyWiki5/compare/v5.0.5-beta...v5.0.6-beta]]//
!! Improvements
*
!! Bug Fixes
*

View File

@ -1,5 +1,5 @@
created: 20130822080600000
modified: 20131129163429930
modified: 20131228161338857
tags: concepts
title: SystemTags
type: text/vnd.tiddlywiki
@ -11,6 +11,7 @@ System tags are used to give special behaviour to tiddlers:
* [[$:/tags/ControlPanel]] for control panel tabs
* [[$:/tags/SideBar]] for sidebar tabs
* [[$:/tags/MoreSideBar]] for tabs in the "more" sidebar
* [[$:/tags/ViewTemplate]] for the view template
* [[$:/tags/ViewToolbar]] for the view mode tiddler toolbar
* [[$:/tags/EditTemplate]] for the edit template
* [[$:/tags/EditToolbar]] for the edit mode tiddler toolbar

View File

@ -1,12 +1,14 @@
created: 201308251625
modified: 201308251625
created: 20130825162500000
modified: 20131228084302609
tags: definitions
title: JeremyRuston
type: text/vnd.tiddlywiki
I'm the inventor of TiddlyWiki. I am available through my company FederatialLimited for consultancy and speaking engagements.
You can find me on these services:
* jeremy (at) jermolene (dot) com
* [[Jermolene on GitHub|https://github.com/Jermolene]]
* [[Jermolene on GitTip|https://www.gittip.com/Jermolene/]], a micropayment service
* [[@Jermolene on Twitter|http://twitter.com/#!/jermolene]]

View File

@ -0,0 +1,20 @@
created: 20131228162825226
modified: 20131228163922307
tags: macros
title: ChangeCountMacro
type: text/vnd.tiddlywiki
The changecount macro returns a counter maintained by the TiddlyWiki core that tracks the number of modifications made to each tiddler. The changecount macro always applies to the tiddler named in the [[currentTiddler|WidgetVariable: currentTiddler]] variable.
For example:
```
<<changecount>>
```
Displays as:
<<changecount>>
Note how the changecount increases every time this tiddler is modified.

View File

@ -0,0 +1,37 @@
created: 20131228163141555
modified: 20131228163843163
tags: macros
title: MakeDataUriMacro
type: text/vnd.tiddlywiki
The makedatauri macro constructs a data URI from a block of text and an associated ContentType. It is commonly used within stylesheets to generate an inline image or font.
! Parameters
|!Position |!Name |!Description |!Default |
|1st |text |Text to be converted to a data URI | |
|2nd |type |ContentType of text | |
! Examples
A trivial example to show how the macro works:
```
<<makedatauri "HelloThere" "text/plain">>
```
<<makedatauri "HelloThere" "text/plain">>
A user-defined macro such as this would typically be used within a stylesheet:
```
\define datauri(title)
<$macrocall $name="makedatauri" type={{$title$!!type}} text={{$title$}}/>
\end
```
Then one can write CSS rules like this:
```
background: url(<<datauri "$:/themes/tiddlywiki/starlight/ltbg.jpg">>);
```

View File

@ -0,0 +1,25 @@
created: 20131228164411884
modified: 20131228164955084
tags: macros
title: QualifyMacro
type: text/vnd.tiddlywiki
The qualify macro is part of the StateMechanism. Given a base tiddler title it generates a unique string that includes a hashed encoding of a position within the widget render tree, identified by the stack of transcluded tiddlers that leads to that position.
! Parameters
|!Position |!Name |!Description |!Default |
|1st |title |Base tiddler title | |
! Examples
The results returned by the qualify macro will depend upon where it is used. For example:
```
<<qualify "base">>
```
Returns:
<<qualify "base">>

View File

@ -1,6 +1,8 @@
title: TabsMacro
modified: 201311211345
created: 20131228162203521
modified: 20131228162445166
tags: macros
title: TabsMacro
type: text/vnd.tiddlywiki
The tabs macro displays a list of tiddlers as a tab control. The user can switch between tabs by clicking on them. By default, the tabs are labelled with the title of the corresponding tiddler. Alternatively, if a `caption` field is specified then it is used instead.
@ -15,6 +17,10 @@ The tabs macro displays a list of tiddlers as a tab control. The user can switch
Here is an example of the tabs macro:
```
<<tabs "Docs WikiText Features RoadMap" "WikiText" 1>>
```
<<tabs "Docs WikiText Features RoadMap" "WikiText" 1>>
<<tabs "[tag[tips]]" "GoogleChromeTips" 2>>

View File

@ -0,0 +1,17 @@
created: 20131228162448664
modified: 20131228162605081
tags: macros
title: VersionMacro
type: text/vnd.tiddlywiki
The version macro returns the current TiddlyWiki version number.
! Example
The version macro takes no parameters:
```
Version number: <<version>>
```
Version number: <<version>>

View File

@ -0,0 +1,43 @@
created: 20131228164411884
modified: 20131228164955084
tags: mechanism
title: StateMechanism
type: text/vnd.tiddlywiki
The StateMechanism in TiddlyWiki is at the heart of how complex user interfaces can be built from WikiText.
In the browser, the TiddlyWiki display is produced by dynamically rendering the tiddler [[$:/core/ui/PageMacros]]. Through various transclusions and other widgets it renders the entire user interface. The dynamic rendering is accomplished by a mechanism called "binding": any changes to the tiddlers in the store are dynamically reflected in the browser display.
The stack of templates that make up the TiddlyWiki display are complex but we'll focus on the line that displays the main story column:
```
<$list filter="[list[$:/StoryList]]" history="$:/HistoryList" template="$:/core/ui/ViewTemplate" editTemplate="$:/core/ui/EditTemplate" storyview={{$:/view}} />
```
Breaking down the attributes applied to the list widget:
* ''filter'': selects the list of tiddlers in the `list` field of the tiddler [[$:/StoryList]]. If a tiddler is added or removed from that list then it is automatically reflected in the displayed list
* ''history'': references the tiddler to be used to store the history stack (see the NavigationMechanism)
* ''template'': identifies a template tiddler to be used for rendering each tiddler in the list
* ''editTemplate'': identifies a different template tiddler to be used for rendering tiddlers that are in [[draft mode|DraftMechanism]]
* ''storyview'': specifies the story view to be used (eg classic, or zoomin)
The [[$:/StoryList]] tiddler is an example of a StateTiddler: a tiddler that is used to hold the state of the user interface. Changes to the user interface are made indirectly, by changing the underlying state tiddlers, and letting TiddlyWiki ripple the changes through the user interface.
Note how this approach makes the ''open'' tab in the sidebar very easy to implement: it is just another list widget referencing the same state tiddler, but with a different template:
```
<$list filter="[list[$:/StoryList]]" history="$:/HistoryList" storyview="pop" itemClass="tw-menu-list-item tw-open-tiddler-list">
<$button message="tw-close-tiddler" class="btn-invisible btn-mini">&times;</$button> <$link to={{!!title}}><$view field="title"/></$link>
</$list>
```
Now consider the implementation of the info panel within the tiddler template. We want to be able to toggle the info panel open and closed, which means that we must track its current state in a tiddler.
However, we can't track the state in a tiddler called, say, [[$:/InfoPanelState]] because every tiddler would share the same state; changing the value of the tiddler would affect all tiddlers displayed in the story.
The solution is to dynamically generate a unique title for each state tiddler that we need. We need to ensure that the same state tiddler title is generated each time a user interface element is rendered. To do that, we append together tokens representating each of the stack of transclusions that led to the current rendering location. Then that string of symbols is hashed to a simple numeric value.
The process of generating a state tiddler title is encapsulated in the QualifyMacro.