On Oct 10, 6:22 pm, AlanBCohen <alanbco...@gmail.com> wrote:
> I've been trying to fully understand the ways you can record, edit,
> and retrieve structured data in a TW. So far, I see the following as
> the options:
"Slices" and "Sections"
----------------------------------
Tiddler slices and tiddler sections are TW native methods of storing
*named* data values by entering information within the normal text of
a tiddler, surrounded by specific patterns of wiki-syntax formatting.
Because they are part of the regular tiddler content, it is easy for
users to add or update information stored in slices or sections,
without having to create any special input or display handling.
A slice is a simple name/value pair, specified using a 2-column TW
table, like this:
|slicename1|slicevalue|
|slicename2|slicevalue|
(e.g. at the top of published plugins, scripts, etc.)
or, using a 'description' syntax, like this:
slicename1: slicevalue
slicename2: slicevalue
(e.g., the default shadow ColorPalette definition)
Regardless of which syntax you use, each slicename should be unique to
the tiddler in which it is defined. Slice values are intended to hold
relatively short bits of text, and cannot contain any newlines.
Fortunately, when you need to store larger, multi-line blocks of text,
the tiddler *section* syntax is available.
A section begins with the TW 'heading' syntax, ! through !!!!!!, where
the heading text is used as the section name, and the value of the
section is everything following the heading, up until the next heading
(of any level), or the end of the tiddler, whichever is reached
first. Thus:
!SectionName
This content is on
multiple lines
!NextSectionName
This is a different section
with more lines of content
!AnotherSectionName
etc.
Once they are stored within the tiddler text, you can easily embed the
value of any given slice or section into another tiddler, by using the
standard <<tiddler ...>> macro, with a special syntax for referring to
slices or sections, like this:
<<tiddler SomeTiddler::SliceName>>
<<tiddler SomeTiddler##SectionName>>
Note: As with any tiddlername used in a macro, if the slice or section
name contains spaces, you will need to enclose the reference in
brackets:
<<tiddler [[SomeTiddler::Slice Name with spaces]]>>
<<tiddler [[SomeTiddler##SectionName with spaces]]>>
As a general rule-of-thumb, when possible, avoid using long text with
spaces when defining slices and section names... it's just easier that
way.
If you enclose your slice tables or sections within TW comment markers
(/%...%/), then they will not be *rendered* when the tiddler is
displayed, but will still be accessible as named slice or section data
using the <<tiddler>> macro as described above. These are called
"hidden slices" and "hidden sections", and can be used to store
'variables' associated with the tiddler, without affecting the
rendered appearance of that tiddler.
When definining a hidden section, it can be helpful to ensure that it
has a specific beginning *and* ending by adding a 'junk' heading
following the section content, like this:
/%
!SectionName
This is content
!end
!OtherSection
More content
!end
%/
Note the "!end" heading is repeated multiple times in the same
tiddler. The "!end" simply serves to mark the ending of each hidden
section. This is OK, as long as we don't actually try to retrieve a
*value* from the "!end" section... and, since the entire block of
content is *hidden*, it doesn't matter how many times "!end" is used,
as it is never actually displayed.
To get the value of a slice or section *programatically* (i.e., for
use with <<forEachTiddler>>, InlineJavascriptPlugin, or when writing
actual plugin code), you can use the TW standard function:
var txt=store.getTiddlerText("TiddlerName::slicename")
var txt=store.getTiddlerText(""TiddlerName##sectionname)
Of course, not every tiddler in a document will have the same slice
and/or section definitions (if any). While it is possible to query
each tiddler in turn to determine if a given slice/section is present,
it is often more useful to determine the kind of information stored in
a tiddler's slices/sections by tagging the tiddler with some pre-
determined value that desigates it's "type".
Then, you can use that tag value to 'filter' the list of tiddlers to
be retrieved, so that only those with the desired slices and/or
sections are processed.
For example, here's an inline script that gathers up information about
'bookmark' tiddlers, and outputs a summary, formatted as an "HR-
separated list"
<script>
var out=[];
var tids=store.getTaggedTiddlers("bookmark");
for (var i=0; i<tids.length; i++) {
var t=tids[i].title;
var d=store.getTiddlerText(t+"::Description");
var u=store.getTiddlerText(t+"::URL")
out.push("[[%0]] - %1\n%2".format([t,d,u]));
}
return out.join("\n----\n");
</script>
Hopefully, this should be enough to get you started with slices and
sections...
enjoy,
-e
Eric Shulman
TiddlyTools / ELS Design Studios
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"TiddlyWiki" group.
To post to this group, send email to tiddlywiki@googlegroups.com
To unsubscribe from this group, send email to
tiddlywiki+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/tiddlywiki?hl=en
-~----------~----~----~----~------~----~------~--~---
