Simple example scripts for study

[wgw]

I would like to program TW a bit more. Here is what I have done so
far:

I looked into the macro introduction on tiddlywiki.org and the
references materials at TWhelp; then the tutorial at
http://softwareas.com/tiddlywiki-internals-1-of-3-architectural-concepts.
I have rummaged, fairly unsuccessfully, in the brilliant
http://www.tiddlytools.com/insideTW/ (I think I need a full search
engine to find what I want there; like how to reference server.host,
for example. A search on "store" for example, does not show how store
is used.) Also http://hoster.peermore.com/recipes/tiddlywiki-reference/tiddlers.wiki.

All that is great, and has got me off the ground (ok; off the ground
as in Wilbur and Orville's first flight; just barely up there with a
favorable wind), but now I'm looking for the next step(s).

I learn best from examples.

Could anyone recommend scripts at different levels of complexity? The
idea is to have some scripts (with or without comments) that go beyond
the helloWorld macro and introduce further dimensions of the code
base. I will of course begin looking for good examples myself (that's
one thing that makes javascript terrific: the code is *really* open!),
and honorably plagiarize what I find, with credit to original
authors, but I'm sure others have a better idea of good learning
scripts.

Any suggestions for a helloWorld II, III, and IV?

Thanks!

(PS: I started looking into programming because I wanted to tweak a
set of tiddlers: take the server.host information for plugin sources
and put it as a tag or display it in the date line or in the tiddler
body. The problem was figuring out how to reference it in each
tiddler. As tiddler.server.host? But of course something like
<script>tiddler.server.host </script> is silly and produces only an
error.)

[Knightnet]

Hi, I'm rather rusty and out of date on TW but the following link
might at least get you part way:
http://tiddlywiki.org/wiki/Dev:SetTiddlerTag

Also store.getValue(tiddler,"fieldname") gets you the value of a
custom field.

Regards, Julian Knight

On Jun 10, 6:47 pm, wgw <wgwin...@gmail.com> wrote:
> I would like to program TW a bit more. Here is what I have done so
> far:
>
> I looked into the macro introduction on tiddlywiki.org and the

> references materials at TWhelp; then the tutorial athttp://softwareas.com/tiddlywiki-internals-1-of-3-architectural-concepts.
> I have rummaged, fairly unsuccessfully, in the brillianthttp://www.tiddlytools.com/insideTW/ (I think I need a full search

> engine to find what I want there; like how to reference server.host,
> for example. A search on "store" for example, does not show how store

> is used.) Alsohttp://hoster.peermore.com/recipes/tiddlywiki-reference/tiddlers.wiki.

[Mike]

pre transclusion upgrade ELS had a large amount of sample scripts. . .
Maybe someone can share those. . . Or maybe ELS has a archive
somewhere. . . ?

Other than that the transclusion section on tiddlytools.com has some
great javascript to look through.

I wish I had a bunch of those scripts to reference myself. . .

Mike

[wgw]

Thanks for the remarks!

I am making some progress (firebug is your friend!). Got around a
stumbling block with "store." (did not understand that when in
firebug, you have to do something like:
store.getTiddler('MyTiddlerName').title ) So I made this macro (my
first!), which seems to work in the tiddler body:

//{{{
config.macros.sayHost = {
handler: function (place, macroName, params, wikifier, paramString,
tiddler)
wikify(tiddler.fields['server.host'], place);
}
};
//}}}

Also looked at jQuery -- looks like it can do amazing tricks with tw;
I could rewrite that macro more directly with jQuery.

I say "more directly" simply because with jQuery, as far as I can
tell, there is no distinction between extended fields and attributes,
like tags. So I can just look at the tiddler div and "get" (maybe
"put" too) whatever seems to be there.

Now, on to trying to figure out how to get my host macro into the tags
section. Can macros run there? Again, it looks like jq could do that
in a snap.

Thanks again for your suggestion.

Bill Winder

[PMario]

Hi Bill,

Put the view macro in a tiddler
<<view server.host>>

Or in your ViewTemplate like this :

... some text ...
<div class='subtitle'>
<span macro='view modifier link'></span>,
<span macro='view modified date'></span>
(<span macro='message views.wikified.createdPrompt'></span>
<span macro='view created date'></span>)

<span macro='view server.host wikified'></span> <!-- NEW -->
</div>
.. some more text ...

regards Mario

[wgw]

Hi Mario,

Yes, that is the elegant solution: view. Doing it the hard way is a
learning experience :).

Still, the mysteries of the tag set are still closed to me (macros do
not work as tags...). I want to get server.host into the tag list. So,
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....

So it may be the best way to get up to steam with tw is to 1)
understand the basic objects and then 2) get fluent with jq.

To all: thanks for the pointers.

B

[Eric Shulman]

> 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"

[wgw]

Eric,

Thank you for making your response "entirely too long": it is
entirely, and extremely good and useful.

On Jun 12, 1:52 am, Eric Shulman <elsdes...@gmail.com> wrote:

> 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.

Yes: so that is why it is important to understand the core structures.

> 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).

Documentation is always a pain, because once one is fluent in the
"language" --tw or javascript-- the code seems self-documenting and
comments feel redundant. And so they are for the fluent programmer.
But open-source software has to be well-commented, because it requires
many hands to keep it going and training for new volunteers. That is
why I think Knuth's idea of literate programming will eventually make
its way into the programming world. It seems odd in some ways that tw
is poorly documented, only because in tw there is a such blurring of
code and data. There should be some kind of automatic documentation
process, à la java.

Your insideTW is certainly a big step in the right direction. Another
of a long list of crucial contributions that the tw community owes
you.

>
> Here's some starting clues:
>
> There are THREE different ways that tiddlers are represented in TW:

As usual, such a clear presentation of the core. (You are living proof
of what Knuth understood: good programmers are good writers and clear
thinkers. It is the clear expression that is the real focus of large
programming projects, even more so than the clever solutions to local
problems.)

> anyway..... this message is entirely too long.... :-)
>

Thank you for this excellent tiddly lesson! A collections of such
messages (for tiddly.org?) would serve as the perfect on-ramp for
potential tiddly troupes :).

Best,

Bill

[Chris]

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.

[Knightnet]

Nice-one Eric, a very useful summary.

Take care of yourself.