Customer Defined Export

Bonsai Outliner for Windows > How Do I ... ? > Export an Outline > Customer Defined Export

By creating an export template file, you can customize the exporting of a Bonsai Outline. Here is a simple example that creates a text file that includes the title, indents each level by four spaces, and only numbers leaf items.

[HEADER]

Title: #TITLE#

[BRANCH_BEGIN]

#LEVEL(" ")#TEXT#

[LEAF_BEGIN]

#LEVEL(" ")#NUMBER# #TEXT#

The exported file would look something like the following.

Title: My Outline

Weekend Chores

1. Clean gutters

2. Cut grass

Fun things

1. Go to movies

2. Go swimming

3. Take a ride

An Export Template file is a text file that has the extension "OXT". All template files stored in the Bonsai installation directory will be shown on the Export menu below the fixed export formats. Several example template files are included and installed by Bonsai.

ExportTemplateMenuWin

An Export Template file is made up of sections that describe what will be written to the export file. Each section begins with a line containing the section name in the first column. The section continues until another section name is seen, or the end of the file is reached.

Use a text editor, such as notepad, to edit the template file. Make a copy of one of the example template files, or start a new file with the extension "OXT". All section and substitution names are case sensitive. Text before the first section name is ignored allowing comments regarding the template to be placed at the start of the file.

Each section contains text that is passed through unchanged to the export file and substitution names that are replaced with values from the outline. Not all substitutions can be used in all sections. If you use a substitution for an item attribute (e.g., #NOTE#) in the Header section, an empty string will be inserted. The following table defines the sections.

Section Name Section Description

Section	Description
[OPTIONS]	This is a unique section in that it does not contain text to be written to the output file, but instead contains options that control aspects of the export. The table on the following page defines the contents of the Options section.
[HEADER]	Written at the start of the export file.
[FOOTER]	The last section written to the export file.
[ITEM_BEGIN]	Written once for each item in the outline.
[ITEM_END]	Written once for each item in the outline after the completion of the branch (all children of the item have been processed).
[BRANCH_BEGIN]	Written once for each item that has child items. When this section is used, the [ITEM_BEGIN] section is skipped.
[BRANCH_END]	Written once for each item that has child items after all the child items have been processed. When this section is used, the [ITEM_END] section is skipped.
[LEAF_BEGIN]	Written once for each item that does not have child items. When this section is used, the [ITEM_BEGIN] section is skipped.
[LEAF_END]	Written once for each item that does not have child items. When this section is used, the [ITEM_END] section is skipped.
[NOTE]	Written once for each item that has a note. Immediately follows either; [ITEM_BEGIN], [BRANCH_BEGIN], or [LEAF_BEGIN]
[FOOTNOTE_BEGIN]	Written once after all items in the outline have been processed
[FOOTNOTE]	Written once for each item that has a note.
[FOOTNOTE_END]	Written once after all the [FOOTNOTE] sections have been written.

The Options section is used to specify control options for the export. Options are entered one to a line in an "Option=Value" format. Blank lines and spaces are ignored. Here is an example that would be used in a template to generate a web page.

[OPTIONS]

EXTENSION=HTM

MARKUP=1

Template sections

The following table lists all the supported options.

Option Description

Option Name	Description
OUTPUT	The name of the output file. When this option is not defined in the template, Bonsai will prompt for the output file name using the name of the outline file as the base name. Example: "OUTPUT=c:\report.html"
ENCODE	The encoding to use for the output text. If not specified, the default is to use the default code page for character encoding. Set to "UTF-8" if you want the text fields (such as TEXT, NOTE, CATEGORY, etc.) to be outputted in the UTF-8 format.
EXTENSION	The default file extension for the export file. This extension is used in the export file save dialog. If this option is not given, the default is "TXT". Example: "EXTENSION=XML"
MARKUP	If the markup option is "HTML" or "XML", characters used for markup languages are converted to special character sequences. These changes are made in outline text, notes, categories, and the outline title. The template text is not modified. These sequences are translated for both "HTML" and "XML". '>' = ">" '<' = "<" '&' = "&" '"' = """ The apostrophe sequence is only translated for "XML". ''' = "'" Example: "MARKUP=HTML". The default value is "NONE".
TAG_URLS	If the markup option is "HTML", text in the outline item title and notes that are recognized as URL's are converted to anchor tags of the form "<a href='URL''>'URL''</a>". If this option is set to 0 the anchor tag insertion is not done.
MAX_LEVEL	This option limits the levels of the outline that are exported. The default value of 0 will export the entire outline. A value of 1 will export only the outermost level of the outline. Example: "MAX_LEVEL=2"
NO_DATE	This string is used when a replacement is made for a date that is not assigned. For example, it a To Do does not have a due date and the #DUE_DATE# replacement is used; the value of this option will be inserted.
NO_CATEGORY	This string is used when a replacement is made for the Unfiled category.
CUSTOM_ZERO	This string is used when a replacement is made for a Custom value of 0. A typical use would be to suppress a value.
NOTE_NEWLINE	Defines a string to substitute for newline characters within notes. Example: "NOTE_NEWLINE=<br>"
NOTE_NEWLINE_CHAR	Defines a single character to substitute for newline characters within notes. The character value is given in decimal. Example: "NOTE_NEWLINE_CHAR=127"
PRIORITY	Defines a text substitutions for the priority numbers (1..5). Provide a list of 5 comma separated names. Example: "PRIORITY=highest,high,medium,low,lowest"

The following substitutions have a single value during the export.

Substitution Description

Substitution Name	Description
#TITLE#	The name of the outline file. Does not include the extension.
#NUMBERING#	The type of numbering is used on the outline. 0 – none, 1 – basic. As Bonsai supports more numbering formats, this list will expand.
#CATEGORIES#	The categories as a comma separated list.
#COLLAPSED_ITEMS#	The Id's of all the collapsed items as a comma separated list.
#TODAY#	Today's date
#NOW#	The current time and date
#FILE_NAME#	The file name of the outline being exported.
#FILTER_NAME#	The name of the active filter used for the export.

As the outline is exported, the following substitutions are given values from each item in the outline.

Substitution Description

Substitution Name	Description
#POSITION#	The location of the item in the outline. The first item is at position 0.
#ID#	A unique number assigned to each item in the outline.
#PARENT#	The unique Id assigned to the parent of this item (0 for level 0 items).
#LEVEL#	The indentation level of the item. Items not indented are at level 0.
#LEVEL1#	Same as #LEVEL#, but 1 based.
#LEVEL("XXX")#	Repeat the quoted string "XXX" by the level number for the item. For example, if you put a tab between the quotes, you can tab indent an item by the depth of the outline. Items at the outer level insert an empty string.
#TYPE#	The item type. 0 – Simple, 1 – To Do, 2 – Task
#NUMBER#	The outline numbering for the item.
#FULLNUMBER#	The outline numbering where all levels are included (e.g., "2.3.1")
#PERCENT#	The percent complete for an item. If the item is a Simple type, the string is empty.
#STATUS("N","Y")#	If the item is not completed, insert the first quoted string. If the item is completed, insert the second quoted string. If the item is a Simple type, an empty string is inserted.
#TODO_STATUS("N","Y")#	If the item has the type To Do, then the text from the quoted strings are replaced as done with STATUS. Otherwise, an empty string is inserted.
#TASK("string")#	If the item has the type of Task, then the quoted text is inserted. Otherwise, an empty string is inserted.
#SIMPLE("string")#	If the item has the type of Simple, then the quoted text is inserted.
#CREATE_DATE#	The date the item was created.
#START_DATE#	The start date. If the item is a Simple type, an empty string is inserted.
#DUE_DATE#	The due date. If the item is a Simple type, an empty string is inserted.
#COMPLETED_DATE#	The completed date. If the item is a Simple type, an empty string is inserted.
#CREATE_DATEN#	The date the item was created as the number of seconds since Jan. 1, 1970.
#START_DATEN#	The start date created as the number of seconds since Jan. 1, 1970. If the item is a Simple type, an empty string is inserted.
#DUE_DATEN#	The due date as the number of seconds since Jan. 1, 1970. If the item is a Simple type, an empty string is inserted.
#COMPLETED_DATEN#	The completed date as the number of seconds since Jan. 1, 1970. If the item is a Simple type, an empty string is inserted.
#ELAPSED_DURATION#	The number of days between the start date and the end date inclusive. If the item is a Simple type, an empty string is inserted.
#PRIORITY#	The priority. A value of 0 is used for a priority value of none.
#PRIORITY_NAME#	The priority text for the priority of the item. See the PRIORITY parameter in the option section. An empty string is used for a priority value of none.
#CATEGORY#	The category name.
#CATEGORY_NUMBER#	The category number. 0 – Unfiled. 1 through 15 are user defined.
#COLOR#	The color of the item. The color is in a format suitable for HTML (i.e., "#RRGGBB").
#COLLAPSED#	The collapsed state. 0 – Not collapsed, 1 – Collapsed.
#CONTACT#	The contact name.
#CUSTOM1#	The numeric value of the Custom field.
#KEYWORDS#	The keywords for the item. The keywords are separated by the "\|" character.
#TEXT#	The item's title.
#NOTE#	The item's note.
#PARENT_TEXT#	The item's parent's title.
#PARENT_NOTE#	The item's parent's note.