Templates

It is quite usual to use GenScriber and never have need to know about templates. GenScriber will automatically create and save user templates for the worksheets you edit, and each time a worksheet is opened the corrisponding template is used.
Any changes you make to the column settings of a worksheet will be saved in the template each time you quit GenScriber.

Templates are formatted text files. If you really need to, you can edit them using a text editor, but that is rarely necessary.
A template file contains the structure of column widths, limits, actions etc.

The user templates are stored in the 'include/tmp folder'. User templates will over-ride master templates that have the same structure.

Master templates are stored in the 'include/templates' folder.


Creating Master Templates

First you need to save a worksheet you wish to make a template from.
It does not matter if the worksheet contains data. We only care about the column structure and options.

1. If the worksheet is not already open, then 'choose a new template', 'create a new one' or open a csv file to extract the template from.

2. Click on the 'Column Options' tab, and select 'Show Advanced Options'

3. Add,Delete,Edit columns and set any options you want as default.

4. Save the worksheet, and then open it again, this will ensure the options are updated in the user template.

5. Click on the 'Tools' menu, and select 'Save Master Template'.

6. Give it a name and save it.

After saving, the template name will appear under the 'New Document(from template)' menu.

Now, any worksheets created using this template will inherit this templates default options

Note: The 'Save Master Template' menu only appears if a master template does not already exist (or if template protection is turned off. see i mportant note (1)).

Important Note:

(1) Template protection can be disabled in 'General Options' to allow modifying a master template.

Please Note. If you change the layout of a master template, all worksheets previously created from the template will no longer belong to it.

If you change the column headings or column positions of a worksheet, then you have changed the worksheet structure, and genscriber will create a new user template for it.

This user template will live in the tmp folder, where it will be used each time you open a worksheet using the same column layout. If a master template is changed, the original worksheet will simply continue to use the old user template.


Creating Templates Manually


Predefined (master) templates are stored in the 'GenScriber/include/templates' folder.
Template files may be organised into subfolders. The template filename suffix is '.tpl'.

Templates are formatted text files, and you can edit them using a text editor.
A template file contains the structure of column widths, limits, actions etc.

The file is separated into sections using braces ' { } '.

The 'file header' section contains the template name, and if used, it may also contain other global settings.

example of the file header section:
{ TEMPLATE = Burials }
or
{ TEMPLATE = Burials » AUTHOR = Les Hardy }

These settings are terminated by ' » ' Note there is no space between the > characters.
The terminator (») may be omitted from the last setting in header section.

All sections that follow the header are field sections.
Each field section contains a keyword and a value, formatted as KEYWORD=value.

The keyword value pair is separated by a single equal sign ' = '.
These settings are terminated by ' » ' Note there is no space between the > characters.
The terminator (») may be omitted from the last setting in a field section.
All keywords must be Uppercase.

Line-feeds and spaces between settings are ignored.
Line-feeds in the 'HINT' text are recognised, and the bar ( | ) is also converted to a line-feed.

Recognised file header settings are:
TEMPLATE
The template name. This is used once at the top of the file.

AUTHOR
Displays the author in the title bar. Useful to help recognise your own templates.

PICKLISTDROP =0
Hides the fixedlist dropdown (do not confuse the with PICKLIST, which activates the normal picklist)

FULLTEXT =#
Set a column as fulltext. Only a single column is allowed, and it cannot be column 1.
# is the number of the column. FULLTEXT=4 would make column 4 the fulltext edit area.
The fulltext field will display as a text area, to the right of the worksheet.

Recognised field setting are:
FIELD The field (column) title.

VISIBLE
1= visible, 0 = hidden. Default=1 if omitted

WIDTH
The field (column) width. Default =100 if omitted.

PICKLIST
1= use picklist, if omitted or 0 = do not use picklist

AUTOINC
If omitted or 0 = no autoinc.
1= from current cell value, increment to bottom row.
2= increment from top row to bottom row (use top row value as start)

AUTOFILL
If omitted or 0 = no autofill.
1= fill column with value of current cell.
2= fill column with value of current cell (overwrite existing data)


AUTOCASE
If omitted or 0 = no autocase.
1= SentenceCase(strict) First character is uppercase. All other characters are forced to lowercase.
2= SentenceCase First character is uppercase. All other characters are left as is.
3= TitleCase First character of each word is uppercase.
4= UpperCase All uppercase.
5= LowerCase All lowercase.

AUTOREPEAT
If omitted or 0 = no autorepeat
1= copy contents of cell above.(do not overwrite current cell data)
2= copy contents of cell above (overwrite current cell data)

HINT
The hint for this field (column). Omit or Leave blank for no hint.

FIXEDLIST
The name of the FixedList to use for current column. Omit or Leave blank for no fixedlist.

MAXCHARS
The maximum number of characters allowed in a cell.

HYPERLINK
Set the column to follow hyperlinks. 1= hyperlinks. if omitted or 0 = no hyperlinks



The FIELD setting is always required. Other settings are optional.

Defaults for omitted field settings are as follows:-
VISIBLE=1
WIDTH=100
PICKLIST=0
AUTOINC=0
AUTOFILL=0
AUTOREPEAT=0
AUTOCASE=0
HINT=
FIXEDLIST=
MAXCHARS=
HYPERLINK=0


Template Example.

The field sections below are formated in different ways to demonstrate the relaxed format of template files. Any of the styles used below are ok.

{TEMPLATE = Burials}
{
FIELD = ImageNo >>
VISIBLE = 1 >>
WIDTH = 200 >>
HINT = Enter the image number against the first entry on each new image, e.g. 4312010_01682. |The first image number must be entered in full. Later ones may be abbreviated - see crib sheet. |For non-LDS films, use the PhotoNo column instead.
}

{FIELD=RecordNo >> VISIBLE=1 >> WIDTH=100 >> PICKLIST=0 >> HINT=
This is a hint.
Line feeds are recognised|This is also a new line}

{FIELD=Day>>VISIBLE=1>>WIDTH=80>>HINT=The day of the month}

{FIELD=Month>>AUTOCASE=1}

{
FIELD=Year
}    

Note: The separator (») may be omitted from the last setting in a field section.

Important note: Field(column) titles must be unique, and they must not contain special characters. The column titles are used as a reference by some functions.
They are also case sensitive, 'Surname' is not the same as 'surname'

Spaces in titles should not be used.
'Father Surname' and 'Father Surname' may look the same to the eye, but the computer will see that the first (with 2 spaces) as a different title to the second (with 1 space).
Errors like this can be extremely difficult to debug, so avoid spaces in column titles.

The best way to format a title is to use 'medial capitals' in compound words, also known as camel-case. ie. FatherSurname.
You could multihyphenate ie. This-Is-A-Long-Title or This_Uses_Underscore


Rules for FullText Edit.
There are a few rules when using the option to have a fulltext editbox replace a column.
1. Only one column may be set as 'fulltext'.
2. The column number for the fulltext field must be greater than 1.
3. You cannot set the following options on a fulltext field:-
WIDTH, PICKLIST, AUTOINC, AUTOFILL, AUTOREPEAT, AUTOCASE, HINT, FIXEDLIST, MAXCHARS, HYPERLINK

Example full text template header.

The fulltext field is Will_Details (field 4).
{
TEMPLATE=Wills>>
FULLTEXT=4>>
PICKLISTDROP=0>>
AUTHOR=Les Hardy
}

{ FIELD=Title>> VISIBLE=1>> WIDTH=200 }

{ FIELD=Reference>> VISIBLE=1>> WIDTH=100 }

{FIELD=Date>>VISIBLE=1>>WIDTH=100>>HYPERLINK=1 }

{ FIELD=Will_Details>> }

Adding a unique ID to a column

Sometimes it is helpful to be able to identify a template from other templates, even though the templates have apparently identical columns. This can be done by adding an 'ID' column

Adding a unique Id to a column
Add a column with a title that starts with ID: , and then add your unique id for that template.

example: ID:mytemplate-123

This will make the template unique, and tell genscriber that this is an 'ID' column. When genscriber finds an ID: column, it is hidden in the worksheet.

ID columns are useful for coordinators. Some useful information can be stored in this column, and processed when the transcription is returned to the coordinator.

There is one caveat. The software used to process returned transcriptions will have to be capable of handling the extra column(s)

If you are using condition scripting, please read about 'Functions' in the GenScriber-Scripting.pdf file.


Removing Existing Templates

To delete a master template

1. First quit GenScriber

2. In the GenScriber folder go into include/templates/.

3. Locate the template and delete it.

To delete a user template

1. First quit GenScriber

2. In the GenScriber folder go into 'include/tmp/'.

3. Locate the template and delete it.


Changing Template Structure Mid Stream

Although it should always be avoided, it may become necessary to change a template structure while the transcribers are using it.
The following attempts to explain when and how a worksheet template can be change for worksheets that already contain data.

Scenario One

Let us suppose that you're coordinating a project and transcribers are using a template with the following columns…

First_Name, Last_Name, Age
We will call this template 'TPL01'.

After transcribing has begun you realise more columns are needed.
You add two columns to your original template (TPL01) and save it as TPL02.

The fields of the new template are…
First_Name, Last_Name, Age, Mother_Name, Father_Name

If you don't change or remove any of the original column titles, then the old template is just a subset of the new template. It doesn't matter what order the new titles are in, provided the original titles are in there, and are exactly the same characters as before.
With this kind of template change it is not too difficult for the transcriber to move over to the new template.

So let's assume you enabled 'Template Updates' and your transcribers have the new template in their template folder. They now have TPL01 and TPL02.

Now for the instructions to the transcribers…

If it is your intention to discontinue TPL01, then you can instruct them to delete TPL01 either before or after the following is carried out.

How to transfer the existing data to the new template.

1. Start up GenScriber and in 'Preferences' ensure that the option for 'Advanced Copy/Paste' is selected.

2. Open the original worksheet (csv file) that is currently being used with the old template (TPL01).

3. In the 'Edit' menu click on 'Copy All'.
The complete worksheet will be copied to the clipboard.

4. In the 'File' menu select 'New Document from Template', and choose the new template (TPL02)

5. Click on the 'Special Paste' toolbar button, and then click the 'Paste' button (bottom right).
All data from the original worksheet will be pasted into the correct columns.

6. Save the new worksheet. From now on the worksheet will automatically use TPL02.

Note: If any data is missing after the paste, it is either because some of the original column titles do not match the new column titles, or the 'Special Paste' option was not selected in the Special Paste window.

Important Notes
When a predefined master template is attached to a worksheet, it is cached in the 'include/tmp' folder. Therefore, if the old template is delete and the old worksheet is opened, the cached settings will still be used.

However, it will no longer be considered a master template. It will revert to a user template, and will allow the user to modify it as they wish.
All this really means is that if for some reason an older worksheet needs to be opened, transcribers will still have the settings for that worksheet.

Scenario Two
Let us suppose that your transcribers are using a template with the following columns…
FullName, Age
We will call this template 'TPL01'.

After transcribing has begun you realise you should have split the name.
You add another column to your original template (TPL01) and change the column titles, and save it as TPL02.

The fields of the new template are…
First_Name, Last_Name, Age

Because you changed the name of a column, it would be impossible to match the original data to the new columns.
With this kind of template change it is quite difficult for the transcriber to move over to the new template.
However, it can be done, and I will explain how.

How to transfer the existing data to the new template.

1. Delete the original template (TPL01) (genscriber must be closed)

2. Start up GenScriber and in 'Preferences' ensure that 'Advanced Copy/Paste Button' is active.

3. Open the original worksheet (csv file) that is currently being used with the old template (TPL01).

4. Go into the 'Column Options' tab and change the title 'FullName' to 'First_Name'.

5. Go back to the worksheet.