Shadow Desktop - Export Templates Demystified
Introduction
Sharing data between applications has always been an important
goal of the Shadow Plan suite of software - the handheld side pioneered
linking data between applications while the sync conduit and desktop
applications always stored data using the industry standard
XML trappings; of course, making it easier to work with is pretty
important as well, so we've always included various import and
export systems, though in the past with lower powered devices we
were fairly limited in these regards. To remedy this situation and
make your data more available to the outside world (for presentations
or just emailing around perhaps), we built a fairly flexible
export system dubbed the "Template Exporter" - a system where anyone
can define the layout of an export, and share that layout with
others.
My hope is that after a few people hack together useful templates,
we can share and optimize them, and perhaps ultimately include some
in the download to the benefit of everyone. While still young, it
should be very possible to make pretty-printed HTML layouts for
websites, XML layouts for Mind Mapping applications, simple text
layouts for emailing around, CSV files for sucking into your
favourite spreadsheet... maybe anything you can think of! Of course,
if you really wish to go crazy with formatting, you can always
fall back upon 'XSLT', a language for transforming XML documents
into other documents.
Overall
An Export Template is simply a plain textfile that describes
how to output the content of your Shadow document; for instance, the
template might wish to say that when emitting (to the output file)
a header that it should be 'bold' or 'indented' or however you'd
like it. Naturally, the layouts you detail depend entirely upon
what you wish to do - if you're designing an export template so
Shadow Desktop can write out an HTML pretty-print version, you'll
be able to make 'bold' content hints since HTML can do that; but if
you're creating a template to write out CSV files for feeding into
Microsoft Excel, you'll not be able to specify things like 'bold'..
CSV files can't do that. The key here is that Shadow Desktop doesn't
know what you're writing out too -- as a user you provide a filename
and pick a template and Shadow Desktop just writes out the file.
This can be powerful, but it means the Desktop will be dumb and just
do what its told to!
To keep things relatively flexible, without too much
complexity (a common Codejedi theme -- give the tools to perform
what you need, but try to stop you from hanging yourself!), we've
devided the outline document into a few sections, whereby
the exporter figures out to do with a given piece of the outline
by matching it to its section. A good example is the 'Header'
section - you define a header formatting in your template text
file, and the exporter spits your header section at the top of
exports. If your output layout needs something to occur just once
at the top of a report, this is where you'd do it; alternatively,
if you need some text to repeat at the top of every page in a
template printout, you'd use the "Pageheader" section instead as
it is repeated at the top of each page.
The template is a pure textfile, which has lines that begin
definition of a section, and other lines that are the content of
that section for the Desktop to copy to the output file.
A Quick Sample
Here is a short and very ugly sample template, that when used
will cause the Desktop to spit out a simple HTML file representing
your outline document. Don't worry, I'll define what it all
means in just a moment!
[header]
<html>
<UL>
[footer]
</UL>
</html>
[opensublevel]
<UL>
[closesublevel]
</UL>
[record]
<LI><b>@@TITLE@@</b> [@@CHECKED@@]
<PRE>
Priority: @@PRIORITY@@
Progress: @@PROGRESS@@
Created: @@CREATED@@
Target: @@TARGET@@
Begin: @@BEGIN@@
End: @@END@@
Prime Tag: @@PRIMETAG@@
Tags: @@ALLTAGS@@
</PRE>
<i>Note: @@NOTE@@
If you've seen a Microsoft Windows ".ini" file, you'll likely
see the resemblance here; if not, then trust me -- its not too hard
to make one of these up.
Defining Sections:
Each template section begins with a section name enclosed by
brackets; see above in the sample to identifiy sections like
[header] and [opensublevel] -- the 'header' section
is defined in the template by '[header]' on a line by itself.
After a section-line, any subsequent lines in the file are
considered the content of the previous section -- except another
section-name; in the sample above you will observe that the
'header' section is followed by two HTML lines ("<html>" and
"<UL>"), and then another section begins being defined (the 'footer'
section.)
NOTE:
- Section names are enclosed with brackets, such as [header] -
and this piece of text must occur at the beginning of a line.
- Section names enclosed in brackets are case-insensitive; you
can use [HEADER] or [Header] or [header] or [HeAdEr] or
what makes you happier.
- Sections should likely occur only once, but if they
occur multiple times - fine; the section content is always just
appended to the existing section content.
- The first line in the template file should be a section
name, so that the export loader knows how to deal with your
template content -- no leading section name and it won't know
what section your layouts belong to!
- You need only supply the sections you need; sections you
do not need/define are skipped! Likewise, sections that do not
make sense are skipped - sections for printing are ignored when
just performing an export for instance.
- The preceeding rule also suggests a template cannot be
empty; if there is no data at all (no sections), then it is
an invalid template for export.
- If you're really a keener, you may wonder whats going on with
newlines; newlines in the section layouts are preserved, except for
the 'indent' section - which has its final newlines removed. If you
want the indent section to have newlines, place an extra blank line
at the end of that section. This mechanism of removing the final
newline in the indent section (and only that section!) permits
indenting to work for textfile exports.
Sections
As you can see from the sample above, export templates are built
up from a group of sections, where each section is just some text
to be copied into the exported file as required.
For instance, the 'header' section is put into the export just
once, the very first thing in an export using that template. If you
didn't define that section - no problem, it is skipped. You needn't
specify every section every time... just the sections you need!
Obviously then, you will need to know what sections are available
so you can know if and when to define them in a given template
export.
- Header - The 'header' section is copied into the export output
just once, at the very beginning of the file; this should not be
used for page headers but could be used to perhaps add a titlepage
to a report, or prepare the rest of the job, or open up a table
or whatever you need to do just once. For instance, if emitting a
website, you could perhaps include some javascript up top, or
other trappings - defining fonts, requesting serve side includes..
whatever. If you need to do it once and up front, the 'header'
section is where you'll want to do it.
- Footer - like 'header', but copied to the very end of the
exported file; use this to close up a document, or finish up the
file.. anything that needs tobe done just once, at the very end of
the file. A footer page to request signatures on a document, or
some final javascript, or standard fax information for your company.
Again, if you don't need this section.. don't include it :)
- Indent - this can be a very useful section, or perhaps you do not
need it at all! If your export requires a piece of text that occurs
once for each 'depth' of an item, here is where you'd do it. For
instance, if you're emitting a shopping list in pure text, but
want each 'deeper' child to be tabbed or spaved over, then you
could include a tab or space in an indent section; if the item in
the outline is 10 levels deep, then the indent section's text
would be copied 10 times before the record of that item. If you're
emitting a 'flattened' output that doesn't worry about actually
indenting the records (or that doesn't need to repeat text to
do it, such as with HTML and nesting), then you do not need this
section.
- Record - this is the most important section,
as it defines the
layout for each item in the Shadow document. For every item in the
outline, this section is copied to the export once. Use this section
to define how to lay out your actual list data in the export. Every
export should include this section, likely! See below for
how to represent your list data in this section (or in any section.)
- Opensublevel - this section is included within the export when
entering a child item in the outline; if your format needs some
special text to be included when 'descending' into the outline, you'll
need this section.. however, if you needn't include any special
markings you needn't use this section. An example is in HTML exports,
where you may need to perform a "<UL>" to open an unordered list.
(For that as an example, see the sample above which does just that.)
- Closesublevel - the counterpart to Opensublevel - if you opened
a sublevel I bet you'll maybe need to close it. For HTML again, see
above, where to go back up a level in the outline a "</UL>" is
written into the export. These two sections are not always needed
of course... it depends very much on your output format.
- Pageheader - as with 'header' but included at the begining of
each printed page when using a template print. Ignored for file
based exports, and thus often not included in templates.
- Pagefooter - The bottom of page friend of the 'Pageheader'
section; if you wish to put some footer information on every page
of a printout, use this section; it is ignored for file exports and
so is often omitted.
Whew! Thats most of the heavy lifting of the template export
system... but you likely noticed we didn't talk yet about how to
include actual item details in the export; chances are you'll include
such details in the [record] section, but you'll need to read the
documentation below to know how to put item details into that
section.
Content Tags
To make a template you'll need to know the 'record' section defined
above, and the 'content tags' defined below; everything else you can
basicly ignore!
While the export is being performed, Shadow Desktop is just copying
sections from your template into the output file. If you tell it your
'header' section is simply the phrase 'jack be nimble', then every
export based on that template will say 'jack be nimble' at the
beginning. Well and good... but if you want each record to actually
include content from your outline (instead of or in addition to
raw text from the template section) you'll have to know about
Content Tags.
When the export engine needs a section (such as the header section
up front, or the record section for each outline item) it just looks
it up in your template; before it copies it to the output file,
it first swaps any content tags it finds for their real content.
For instance, if it is about to copy the 'record' section into the
output, it will swap the specific text @@TITLE@@ with the
item title. This is where the magic is -- by including @@TITLE@@
in the 'record' section, you now include the item's title text.
No we're getting somewhere!
NOTE:
- Content tags, such as "@@TITLE@@" are case insensitive.
You could use @@title@@, or @@TiTle@@, and it will work fine.
- Not all content tags are available everywhere - the item
content tags are available in the 'record' section, but not in the
'header' section -- since a header has no item associated to it.
As time goes on, we'll define more content tags and sections as
the need arises. The available content tags are defined here:
- @@UNIQUE_ID@@ - this tag inserts the item's unique ID; a unique ID
is a magic number that is unique to a given item within its outline;
other outlines likely use the same unique ID, but within a given
file you're always safe. If creating an export to another database,
you may need this as a primary key for instance.
- @@PROGRESS@@ - inserts the item's progress percentage.
- @@CHECKED@@ - inserts whethor or not the item is checked as
the number 0 or 1.
- @@CHECKEDTEXT@@ - inserts whethor or not the item is checked,
as the text 'Checked' or 'Unchecked'.
- @@PRIORITY@@ - inserts the item priority level.
- @@TITLE@@ - inserts the items title text
- @@NOTE@@ - inserts the items note text
- @@CREATED@@ - inserts the items creation date
- @@TARGET@@ - inserts the items target date
- @@BEGIN@@ - inserts the items begin date
- @@END@@ - inserts the items end date
- @@DEPTH@@ - inserts the items depth (0 is the top level)
- @@ALLTAGS@@ - inserts all the tags the item has upon it,
separated by spaces.
- @@PRIMETAG@@ - inserts the items prime tag
See the sample up top for an idea; you could, for instance
include the text 'Title: @@TITLE@@' in your 'record' section.
The raw text 'Title: ' is copied verbatim into your export, but
the text @@TITLE@@ is changed into the items title text. Handy.
Template Files
A template is created as a simple textfile, such as by using
the Notepad tool (or any other text editor. MSWord could be used,
though you must be careful to 'save as' and write out a .txt file
instead of a Word .doc file, for example!) In order for Shadow
Desktop to locate and allow you to use the template file, it has
to be stored in the right place.
Place your template files in the Templates directory. That
directory should be created (if it does not already exist) in the same
location as the Shadow.exe application file.
For instance, if you installed Shadow Desktop to
"C:\Program Files\Codejedi Inc.\ShadowPlan" then you could find
Shadow.exe in there; just create a new directory "Templates" beside
Shadow.exe and drop any template files in there, and you should
be good to go.
When you select Template Export from the Desktop menu, it will
present you with a form to enter a filename and select an export
template to define the layout.
