About
Downloads
Register/Buy
Help and FAQ

Manual
Screenshots
Reviews/Media
User Forums
User Contributed
Developer Support
Thanks to...


About
Downloads
Register/Buy
Screenshots
User Forums
FAQ

Free Stuff
CaSTaway
Kronos
Manticore
Columbo
B.o.R.
GuineaPig
GP32
Zot!
Telnet BBS
ZGrab
ZQuake
DevFAQ
All

Message Board
Personal Blog
Support and Contact
Home


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.