RootsMagic 8:Creating a source template

Navigation: RootsMagic 8 > Working With Sources > Source Templates >

---

We will use a step-by-step approach to illustrate how to create a new source template. We will also illustrate some of the concepts that make RootsMagic's source templates so powerful.

Source templates are created in two steps – first, define source fields applicable to the type of source, and, second, arrange these fields (with other text, punctuation, formatting and switches) for the first full footnote entry, for the short (subsequent) footnote entry, and for the bibliographic entry.

To begin:

1. Select the Sources page
2. Click the 3 dot menu and choose "Source template list"
3. Click Add to open the Source template window.

source template new

The fields and commands in the Source template window are:

• Name of the source type – enter the name of the source type in this field. The name should be descriptive to help you identify it later. If you are using a style guide, use the model name as a basis for the source type name.
• Details – this button will open the Source Template Description dialog, which has two fields
  • Category – enter an optional category name. This will appear in the Ref: field. The built-in templates use a code: a 2-3-letter code for the style guide, i.e. EE, E! or CYS; QC-x (x=chapter) or sec. xx.xx (section number); page numbers.
  • Description – you can enter a longer description here to provide more details about the source type. These can also be extra keywords that can be used when searching for a specific fact.
  • Click OK to save the changes, or Cancel to discard the changes and close the window.
• Add field – click this button to add a new source field.
• Edit field – this button will open an existing Source Template Field to make changes or to view the information defined for this field. The same dialog is used as for the Add field button.
• Delete field – click the button to delete a source field. You will be asked if you want to remove the field and the name of the field is listed. Confirm the name is the correct one, and click Yes to delete it and close the dialog, or No to close the dialog without deleting the field.
• green down arrow green up arrow – use these buttons to move the fields down or up to reposition the fields in the fields list. (Note that this has no impact on the arrangement of fields in the Templates fields.)
• Source field list – this list shows all the fields that are defined for this Source template. They are the only fields that can be used in the templates fields. The columns are:
  • Field Name – the field name to be used in the template. The name can only have upper or lower case letters and the underscore "_" character. All other characters are ignored.
  • Display Name – The name that will be displayed to the left of the field in the Edit source window. Be careful to limit the number of characters used since the start of the display name will not be displayed if too long.
  • Type – the field type: Name, Date, Place, Text
  • D – x indicates the field is a Source details field. No x indicates a Master Source field.
  • Hint – a brief hint to help the user determine what data should be entered into the field. Note: While you can enter the bar or pipe "|" character in the hint field, the symbol and anything following it will not be displayed in the field in the Edit Source window
• q-mark blue – x indicates there is a long hint defined for this source field. This long hint can be more detailed and show examples to help the user understand the data to be entered into the field. There is no restriction on the characters that can be used, or that will be displayed.
• Templates – this list shows all the fields that are defined for this Source template. They are the only fields that can be used in the templates fields. The columns are:
  • Footnote Template – the template to create the first full footnote when a source is used in a report
  • Short Footnote Template – the template to create the short footnote when the same footnote is used in subsequent locations in a report.
  • Bibliography Template – the template to create the bibliographic entries that appear in the bibliography or in a source list in a report.

Defining source fields

To add a source field:

• From the Source Template window, click Add or Edit (Edit opens an existing field to view the contents or to make changes.)
• Source Template Field fields are:
  • Field Name – the field name to be used in the template. The name can only have upper or lower case letters and the underscore "_" character. All other characters are ignored.
  • Type – the field type: Name, Date, Place, Text
    • Text – use this field type for text to be displayed as entered. This can be used for names, places, or even some dates, if no formatting is required. Note: When the Text field type is used for names, places or dates, the field checking and formatting options are not available. This may or may not have advantages. Normally, you would use the appropriate field type, unless you had a specific reason to not use it..
    • Name – use this field type when you need to reverse the order of the name parts [field:Reverse], or to access the last name [field:Surname]
    • Date – use this field type to have RootsMagic check that the data entered is a valid date, and displays the date in the format set up in Options. One common use of this field type is when you want to display the full date in one place yet access the year [field:Year] only in another location.
    • Place – use this field type when you need to reverse the order of the place parts [field:Reverse], or use the short place name in the Short footnote [field:short].
  • Display Name – The name that will be displayed to the left of the field in the Edit source window. Be careful to limit the number of characters used since the start of the display name will not be displayed if too long.
  • Brief hint – enter a brief hint to help the user determine what data should be entered into the field. This will be displayed in the field when there is nothing entered or as a pop-up tool tip if the user hovers the mouse pointer over the field name Note: While you can enter the bar (or pipe) "|" character in the hint field, the character and anything following it will not be displayed in the tool tip in the Edit Source window – use the long hint to include bars.
  • Long hint – you can enter more detailed information and show examples to help the user understand the data to be entered into the field. There is no restriction on the characters that can be used, or that will be displayed.
  • This field is a source details field – check this box to indicate the field is a Source details field. Leave this box unchecked to indicate a Master Source field (the default).
  • Click OK to save the changes, or Cancel to discard any changes and close the dialog.

Building the template

There are three template fields, Footnote Template, Short Footnote Template and Bibliography Template. They are all created in the same way. The only differences are the fields used, the order of the fields, the field options used for the lead (first) field, where a shortened (abbreviated) form is used, and the punctuation.

To build a source template, you would drag the fields from the field list on the left to a template on the right. You can also type in the field name, but you have to remember to add the square brackets and spell the name as shown at the left. You would also add the punctuation, text, field options, and switches to complete the template. For a full discussion of the template language, see the topic Source Template Language.

The following examples illustrate a number of techniques that you can use when building a template.

The field options, switches and formatting codes used above include

:Caps – capitalize the first letter of the first word, to ensure the entry starts with a capital letter :Year – display the year from the date field

• Abbrev – use alternate text (text following || in the field) if found, otherwise use the text entered

  Reverse – reverse the elements entered, in this case the name of the compiler, but can also apply to a place. Prefixes that denote rank are not moved to the end of the name after the given name as required by some style guides – they remain before the given name, i.e. Major Thomas Grong, when reversed would become Grong, Major Thomas rather than Grong, Thomas, Major.

• <[field] ,> – the < > brackets indicate a simple conditional switch. If the [field] has data entered into it (one or more characters), the content of the field is displayed plus the space and comma. This technique makes the punctuation optional so it won't appear if the associated field contains no data.
• <. [field:Caps]> – similar to the above, but inserted the punctuation before the field data, adding a period to end the previous sentence and starting a new sentence in this case. The :Caps option was included to force the first letter in the field to be capitalized.
• <sc> ... </sc> – convert the lower case textual characters to small caps
• <![StreetAddress|<sc>address for private use</sc>> – this uses the privacy switch (syntax is "<! private | public/non-private >"). This switch tells RootsMagic to display the first part only if the user chooses to display private data, otherwise the second part would be displayed. In this case, the street address would be only shown if the user chose to see the private data. In all other cases, the phrase "address for private use" in small caps would be shown.
• Punctuation – you'll notice that punctuation between groups of fields tends to be commas or semi-colons in the footnotes and periods in the bibliography. Study your style guide to determine the punctuation that is required.

Additional field options, switches and formatting codes used here that were not mentioned above

• [Title]<: [SubTitle]> – This example uses two things: for italics formatting, and <: [SubTitle]> in a conditional switch to include the colon and space if the user enters a subtitle
• [field:Lower:Abbrev] – This illustrates using multiple options, forcing the text to lower case, and use the alternate text (entered after ||) if available. Whether the alternate text is used or note, text will be in lower case.

  Surname – use the surname only of the author.

• <[PubPlace]|N.p.> – this tells RootsMagic to display the first part (before the "|" bar) if there is data entered into the field, or use the second part (after the "|") if there is no data entered into the field. This technique lets you set up default text to be inserted if the user doesn't enter anything. In other cases, it can be used to enter standard wording, which the user can overwrite by entering a value. This is used in online templates to insert the word "accessed", <[AccessType]|accessed>, but the user can still enter another word of phrase, such as printed or downloaded or whatever.
  • When using the above technique, you must remember to format the case of the text following the | bar. For instance, if you use :Caps to capitalize the first letter in the field, you must capitalize the first letter of the text you enter, as in <[ItemType:Caps]|Card file>.
  • You cannot use the above technique when you want to make the field optional, because the text following the "|" bar always results in text being present, either from the field or from the default text.

Additional field options, switches and formatting codes used here that were not mentioned above

• < [<[TranslatedName]>]> – This example illustrates a technique you can use to add square brackets around a field name. By entering the field name within conditional angle brackets, the outer pair of square brackets are treated as square brackets, and not as part of the field name.

Additional coding used here that was not mentioned above:

• <[NewspaperPlace|Newspaper]> – This example uses two newspaper name fields, one for the regular name, the second for the newspaper name with a place inserted. Note the placement of these two elements in the Footnote template. A simple switch is used to display the name with the place if it is entered, or the newspaper name if the place version is not entered.
• <; [CreditLine]> – This field allows users to enter the original source of the source for online images.
• "[Article]<?[SpecificContent]|," [SpecificContent].|."> – This code solves the problem of punctuation that is dependent on whether a field has content or not. You cannot simply use a period at the end of the template. If there is no content, the period has to appear inside the closing quote, otherwise a comma is required inside the closing quote and the period would appear at the end. Thus, if the field [SpecificContent] has data, a comma and a closing quote is inserted before the content is displayed, otherwise if the field is empty, the period and closing quote are displayed.