Eric, This is a really useful write up - thanks from outside of the thread. I've used TW for a few years. Written plugins for years. I only ever got to clarity by hacking through Your and a few others plugins ;-) This is great.
Chris. On Jun 12, 10:52 am, Eric Shulman <[email protected]> wrote: > > I'm following Mike's suggestion and looking at tiddlytool's > > transclusions. Very interesting stuff! Though I must admit jQuery > > seems to do an end run around much pre-jquery code.... > > While jQuery is very good for manipulating *DOM elements* (rendered > page content), it really doesn't have any bearing on the TW internal > store "object", which is where the actual *data* for all tiddler is > kept during the session. > > Learning the TW core object model can be somewhat confusing, primarily > due to lack of comprehensive (or even adequate) documentation (except > for reading the code itself, which is sparsely commented). > > Here's some starting clues: > > There are THREE different ways that tiddlers are represented in TW: > > * as hidden DIVs within the source content of the HTML file itself > * as javascript objects within the run-time "store" > * as rendered DOM elements > > Of course, each has different usage within the system: > > The hidden DIVs are used to hold HTML-encoded tiddler *source* content > and related tiddler fields within the saved TW file. For example: > ------------------ > <div title="SomeTitle" modifier="UserName" created="200805181707" > modified="200806150338" tags="sample stuff" somefieldname="..." > someotherfieldname="..."> > <pre> > ... HTML-encoded tiddler source goes here... > </pre> > </div> > ------------------ > > When a TW document starts up, one of the first things it does it to > read these hidden DIVs, and convert them into tiddler objects, held in > the core's "store", and retrieved via: > var t=store.getTiddler("TiddlerName"); > > within the returned tiddler object, "t", are several important > properties: > t.text > the body of the tiddler - simple text, not HTML-encoded > t.created > datetime of initial tiddler creation (written once) > t.modified > datetime of last tiddler update > t.modifier > TW username (config.options["txtUserName"]) of last editor > t.tags > space-separated, bracketed tags, e.g.: > "foo bar [[baz has spaces]] mumble [[so does frotz]] gronk" > t.fields > a container object for "custom tiddler fields". > > Lastly, when a tiddler is opened for viewing, it is *displayed* in the > story column (the central column of the standard TW layout - defined > by HTML contained in the PageTemplate tiddler). The story column is > actually a DIV (id=#tiddlerDisplay) in which each rendered tiddler is > a child element, using an id of "tiddler"+TiddlerName (e.g., the > "FooBar" tiddler object will be rendered into the "tiddlerFooBar" DOM > element). > > The layout for the elements within a *rendered* tiddler are defined by > HTML contained in the ViewTemplate tiddler. By default, this > definition invokes the "view" macro to render and display the content > of the tiddler within a sub-element of the tiddler named "viewer": > <div class='viewer' macro='view text wikified'></div> > > When the "view" macro is processed, the desired field name and an > optional 'wikified' keyword param are passed to the > config.macros.view.handler() function for processing. This function > retrieves the stored value of the specified field, e.g.: > var v=store.getValue("TiddlerName","text"); > and then passes this value, along with a target DOM element ('place') > to the core's central wikify() parser... which interprets the stored > tiddler source, and generates corresponding DOM elements within the > indicated place. > > ------------------------------- > > Hopefully, the above descriptions will help you get your bearing as > you dig through the source to learn more. > > Fortunately, I am actively working on expanding upon my "InsideTW" > documentation to provide a comprehensive reference for all core > macros, as well as guides to using templates, stylesheets, plugins, > inline scripts, transclusions, toolbars, options, cookies, etc. > > Unfortunately, due to mostly to poor health, I have been very slow in > writing this new content, and it is still not ready for even 'alpha' > level distribution. My first target for expanded documentation is to > write documentation for all the core macros, using a style similar to > how I have documented my plugin-defined macros on TiddlyTools.com. > > If I can manage to get a couple of good, focused weeks in a row.. I > might have something to release by mid-summer. If that goes well, the > next installment will likely be a basic to plugin installation and > basic document customization (i.e., modifying default "shadow" > templates, toolbars, stylesheets to add plugin-defined features). > > Beyond that... I have a long list of topics, including how to use: > * slices, sections, and custom fields > * transclusions with 'substitution' parameters > * inline scripting (using InlineJavascriptPlugin) > * 'evaluated' macro parameters > * embedded HTML forms in tiddlers > and many more.... > > Each of these subject areas will probably be delivered as one or more > *separate* "insideTW" documents. Note that the current > "insideTW.html" document is really just the "TW Core Explorer" portion > of the overall work that I hope to create... > > anyway..... this message is entirely too long.... :-) > > so I will close here... with more to come.... > > enjoy! > -e > Eric Shulman > TiddlyTools / ELS Design Studios > "Small Tools for Big Ideas" -- You received this message because you are subscribed to the Google Groups "TiddlyWikiDev" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/tiddlywikidev?hl=en.
