From ac81d9d43f3ec40160e66b1830d2d7107d094278 Mon Sep 17 00:00:00 2001 From: Jermolene Date: Sat, 28 Dec 2013 17:57:11 +0000 Subject: [PATCH] Docs update Hopefully fixing #309 --- .../tw5.com/tiddlers/Release 5.0.6beta.tid | 15 +++++++ .../tw5.com/tiddlers/concepts/SystemTags.tid | 3 +- .../tiddlers/definitions/JeremyRuston.tid | 6 ++- .../tiddlers/macros/ChangeCountMacro.tid | 20 +++++++++ .../tiddlers/macros/MakeDataUriMacro.tid | 37 ++++++++++++++++ .../tw5.com/tiddlers/macros/QualifyMacro.tid | 25 +++++++++++ .../tw5.com/tiddlers/macros/TabsMacro.tid | 10 ++++- .../tw5.com/tiddlers/macros/VersionMacro.tid | 17 ++++++++ .../tiddlers/mechanisms/StateMechanism.tid | 43 +++++++++++++++++++ 9 files changed, 171 insertions(+), 5 deletions(-) create mode 100644 editions/tw5.com/tiddlers/Release 5.0.6beta.tid create mode 100644 editions/tw5.com/tiddlers/macros/ChangeCountMacro.tid create mode 100644 editions/tw5.com/tiddlers/macros/MakeDataUriMacro.tid create mode 100644 editions/tw5.com/tiddlers/macros/QualifyMacro.tid create mode 100644 editions/tw5.com/tiddlers/macros/VersionMacro.tid create mode 100644 editions/tw5.com/tiddlers/mechanisms/StateMechanism.tid diff --git a/editions/tw5.com/tiddlers/Release 5.0.6beta.tid b/editions/tw5.com/tiddlers/Release 5.0.6beta.tid new file mode 100644 index 000000000..a7e2e0ae3 --- /dev/null +++ b/editions/tw5.com/tiddlers/Release 5.0.6beta.tid @@ -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 + +* \ No newline at end of file diff --git a/editions/tw5.com/tiddlers/concepts/SystemTags.tid b/editions/tw5.com/tiddlers/concepts/SystemTags.tid index 7b0f76e96..45eb83bc1 100644 --- a/editions/tw5.com/tiddlers/concepts/SystemTags.tid +++ b/editions/tw5.com/tiddlers/concepts/SystemTags.tid @@ -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 diff --git a/editions/tw5.com/tiddlers/definitions/JeremyRuston.tid b/editions/tw5.com/tiddlers/definitions/JeremyRuston.tid index 872106aff..680478584 100644 --- a/editions/tw5.com/tiddlers/definitions/JeremyRuston.tid +++ b/editions/tw5.com/tiddlers/definitions/JeremyRuston.tid @@ -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]] diff --git a/editions/tw5.com/tiddlers/macros/ChangeCountMacro.tid b/editions/tw5.com/tiddlers/macros/ChangeCountMacro.tid new file mode 100644 index 000000000..34457c392 --- /dev/null +++ b/editions/tw5.com/tiddlers/macros/ChangeCountMacro.tid @@ -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: + +``` +<> +``` + +Displays as: + +<> + +Note how the changecount increases every time this tiddler is modified. + diff --git a/editions/tw5.com/tiddlers/macros/MakeDataUriMacro.tid b/editions/tw5.com/tiddlers/macros/MakeDataUriMacro.tid new file mode 100644 index 000000000..66c6f98cb --- /dev/null +++ b/editions/tw5.com/tiddlers/macros/MakeDataUriMacro.tid @@ -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: + +``` +<> +``` + +<> + +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(<>); +``` diff --git a/editions/tw5.com/tiddlers/macros/QualifyMacro.tid b/editions/tw5.com/tiddlers/macros/QualifyMacro.tid new file mode 100644 index 000000000..269fd09dd --- /dev/null +++ b/editions/tw5.com/tiddlers/macros/QualifyMacro.tid @@ -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: + +``` +<> +``` + +Returns: + +<> + diff --git a/editions/tw5.com/tiddlers/macros/TabsMacro.tid b/editions/tw5.com/tiddlers/macros/TabsMacro.tid index 64630309c..e27118682 100644 --- a/editions/tw5.com/tiddlers/macros/TabsMacro.tid +++ b/editions/tw5.com/tiddlers/macros/TabsMacro.tid @@ -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: +``` +<> +``` + <> <> diff --git a/editions/tw5.com/tiddlers/macros/VersionMacro.tid b/editions/tw5.com/tiddlers/macros/VersionMacro.tid new file mode 100644 index 000000000..9bcdfa428 --- /dev/null +++ b/editions/tw5.com/tiddlers/macros/VersionMacro.tid @@ -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 number: <> diff --git a/editions/tw5.com/tiddlers/mechanisms/StateMechanism.tid b/editions/tw5.com/tiddlers/mechanisms/StateMechanism.tid new file mode 100644 index 000000000..f9507943d --- /dev/null +++ b/editions/tw5.com/tiddlers/mechanisms/StateMechanism.tid @@ -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">× <$link to={{!!title}}><$view field="title"/> + +``` + +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. + +