Share Details Template, Export Template, etc.

The Share Details Template is used to format the text of an entry that is being shared with another application in the Android system. The template is stored in the file sharedetailstemplate.txt located in the Pimlical folder.  The documentation below also covers the use of the Export Template in Pimlical/Desktop, and the template routines are used wherever formatting is needed for one or more events that are shared as text files. Note that a different, more complex set of template commands handles the screen display items (which require additional fields to cover things like font, color, x/y coordinates, as well as drawing objects like rectangles and lines.

These files are automatically installed by Pimlical from default templates in the program when this command is first used. These files can be freely edited by the user to change the way in which the text is formatted. This is of course a feature for Power Users and requires some study to get familiar with how to format commands (if you choose to do this, it is recommended that you turn on Debug mode so that any error messages appear in a dismissable dialog rather than a quick message that flashes on the screen)

Formatting in the Template File

The template file may contain [StartPreScript] and [EndPreScript] tags to enclose a block of text that appears one time ahead of the processing of the list of events. This would be typically used to create a title for the file. It may also contain [StartPostScript] and [EndPostScript] tags to provide a block of text that will appear one time after processing of all the events. While processing the PreScript or PostScript section, the following substitutions are made (these tags are case sensitive, so they must match the case below).

<invoice>    Is replaced by the Invoice Number. On first access, the invoice number is retrieved from a text file with the name PimlicalInvoice.txt in the main Pimlical folder. There should just be a number on the first line and nothing else. When the file is read, Pimlical automatically increments the number by one and rewrites the file. For HTML output files, the tag is &lt;invoice&gt (same tag, but the <> are declared as &lt (less than) and &gt (greater than) for HTML formatting.

<date>                Is replaced with the current system date in medium date format (like mm/dd/yyyyy, depending on the Date Format Preference). For HTML output files, the tag would be &lt;date&gt;.

<time>                Is replaced with the current time in HH:MM format (either 12 or 24hr format depending on preferences. For HTML output files, the tag would be &lt;time&gt;.

<EOL>                Is replaced with the standard line ending for that platform (usually a line feed code: \n).

There are some simple formatting commands that allow control over what gets put in the shared text. All information is presented in standard Ascii Text format that should be read by any Android program that can handle raw Ascii Text.

All text in the template file appears in the shared text. In that text, Pimlical searches for the special character - the opening bracket ( [ ). From the opening bracket to the closing bracket, Pimlical takes this as a request to extract data from a field in the record and format it in a certain way. The format of this request is:

[fieldname, FieldLength, format, Justify-left/right/center]

where fieldname is the name of a field in the record (see list of calendar database fields at end of this section). And where the justification characters are < > = | (< = flush left, > = flush right, = = center, | = no padding).

For example, [description,50,=] would take the description field of the record, truncate it to 50 characters if necessary and then center it within a 50 character field. The format parameter is only used for date and time to indicate what format to use (1 = short, 2 = medium date/long time, 3 = long date). The Default format is flush left with wordwrap.

The backslash character ( \ ) is used to copy over the next character in the template without having Pimlical attach any special meaning to it. For example \[ can be used to insert a square bracket into the template file without having Pimlical think that it is the start of a request to extract data from the current record.

\t can be used to insert a tab character

Special Fields

In addition to the standard calendar fields, there are some special fields that can be used in the template. Each of these fields starts and ends with a square bracket and takes up a line by itself. These field tags are not case sensitive. They normally only appear in the Prescript and PostScript sections.

[ExportTemplate] this field must always be present as the first line in an export template, or the program will not recognize
this file as an Export Template. It has no other significance other than to avoid inadvertently submitting some other file to the program for use as an export template.  Only implemented in Pimlical/Desktop.

[ShareTemplate] this field must always be present as the first line in the share template, or the program will not recognize this file as a valid Template for use with the share command.  Only implemented in Pimlical/Android.

[DisplayDurations:{description}] causes Pimlical to display the total sum of all the durations of all events that are being shared (the colon is part of the tag). After the colon can be a description that is displayed ahead of the duration value such as Total Time Spent:. This is displayed after all the records have been added to the shared text. At this time, since the Share command can only be invoked on a single item, the duration will just be that of the currently selected event. You can embed the tag <EOL> to start a new line.

[DisplayCosts:{description}] causes Pimlical to display the total cost associated with all the events that are being shared (calculated from the sum of all the durations multiplied by the cost per hour figure). After the colon can be a description that is displayed ahead of the cost value such as Total Cost:. This is displayed after all the records have been added to the shared text. Again, at this time, this command only calculates the total cost for the currently selected event. You can embed the tag <EOL> to start a new line.

[CostPerHour=125.50] sets the cost per hour value that is used to calculate the total costs based upon durations. It also defines the number of decimal places in the currency, so if there were 3 decimal places, the tag might look like: CostPerHour=125.500. The currency delimiter character should match the preference CurrencyDelimiter.

Special Action Tags processed for the Share Function

There are two Action tags that can appear in the event record itself and which have special meaning:

AddTime: is followed by a Pimlical Duration string (i.e. 3d2h or 2h3m or 30m etc.). This duration value is added to the duration of the event and is used in the Display Costs calculation. A typical use is with a quick entry template that has no duration and adds a fixed duration (such as a minimum/fixed billing interval).

Add$: is followed by a currency value (see section below for definition of a currency value). This cost value is added to the accumulated value of Display Costs. A typical use is to add some fixed cost with a quick entry template (such as standard travel time billings, etc.).

Currency Value

A currency value consists of the string of digits separated by a character defined by the preference: CurrencyDelimiter (default value is a period). In Pimlical/Desktop there is also a preference for CurrencyCharacter (although it's not really needed). Pimlical processes currencies in tags based upon the [CostPerHour tag format.

Template Files

There is no limit on the number of export template files that you can create. Simply copy an existing template to create a new one. They can be kept in any folder (you might want to set up a separate folder if you have a lot of export templates). It is suggested that they have a TXT extension (the command to locate a template assumes this extension, although this is not actually required by Pimlical.