Addon:Form Creation
|
Form Creation: Intended for users who wish to create custom Form definitions for the Forms Gramplet addon. That can be shared with other members of the Gramps community. |
|
Please note in Gramps 4.2.x or newer the Forms Gramplet addon replaced the older Census Addon. |
Information on creating a new form for the Forms Gramplet addon.
Contents
Writing your own form definitions
|
|
Note: For the form to work Make sure that your definition file is saved using UTF-8 encoding. |
If a form you require is not in the list of supported definitions then you can write your own.
Form definitions are stored in XML files. These are located in the Form directory beneath your user plugins directory. The file called form_xx.xml(where xx is a country code), is provided in the download, and contains some common definitions. Additional files called custom.xml and test.xml will also be searched.
Although you can add your definitions to the pre-defined entries in form_xx.xml, it is recommended you create a separate file called custom.xml or test.xml for this purpose.
Definition file structure
Definition files consist of an XML declaration followed by a forms element.
<?xml version="1.0" encoding="UTF-8" ?> <forms> </forms>
forms element
The forms element contains a number of form elements, each representing a form definition. The form start-tag contains 4 attributes:
id: A unique code to identify the form definition. You will use this Code in the Form attribute of the source.type: The type of the event created by the form editor. This value will appear in the "Type" column of events ("EventType"). It would be wise to avoid standard ones, for example, to add death information you could specify "Death.Info" or another one you make up (Data loss is possible otherwise).title: A description of the form. It should be possible to use anything here.date: An optional date in a Gramps date format. This is only useful for census definitions or similar events that happen on a specific date.
<form id='UK1841' type='Census' title='1841 UK Census' date='6 Jun 1841'>
form sections
The form is divided into sections which describe the information that needs to be captured for people performing a given role in the event. Each form element should contain at least one section element. The section start-tag can specify these 3 attributes:
role: The role that people in this section perform in the event. This value will appear in the "Role" column of events ("EventRoleType").type: The type of section. This defines how a section is displayed and people are selected. Allowed values are: 'person' for a single person, 'multi' for one or more people, or 'family' for two people selected by a family.title: This is used when displaying the section on the form and provides the only way to visually tell multiple sections apart. In a marriage you would have a "Husband", a "Wife" and possibly others such as "Witnesses".
<section role='Primary' type='person' title='Child'>
column element
Each section element should contain a column element for each column in the section. Column elements describe information that may be recorded for each person in the section.
A column element contains:
- An
_attributeelement. This contains the key used to store column information in the attributes of event reference objects within the Gramps database (The "Type" Attribute of the reference information for the event. If you use "Name" then the selected person's name will be prefilled. Once defined this text must not be changed. - An optional
_longnameelement. This contains a fuller description of the column and is only used for tooltips (when you hover the mouse over the field in the form). - A
sizeelement. This contains the size of the column in the census report. It is a percentage of the page width. The sum of all size elements in a definition should total 100%.
<column>
<_attribute>At Home</_attribute>
<_longname>Working at Home</_longname>
<size>6</size>
</column>
|
|
Note: The underscore is important in the <_attribute> & <_longname> elements.As the underscore indicates that the text should be translated by translators. |
heading elements
Each form element may optionally contain heading elements. Heading elements describe information that is recorded once for each form.
A heading element contains:
- An
_attributeelement. This contains the key used to store information in the attributes of the event objects within the Gramps database.
<heading>
<_attribute>City or Borough</_attribute>
</heading>
Tips on debugging your custom form definitions
After creating or updating a form (in custom.xml or test.xml) to make sure your Form is correctly formatted use a text editor that includes an XML mode and syntax check, (like NotePad++ and install the "XML Tools" plugin), then the editor will be able to tell you if your Form's XML code is formatted correctly.
If the XML form check worked then start Gramps to test the form.
If Forms Gramplet's New and Edit buttons don't appear then there is a good chance that an XML syntax (or other) error has occurred. The Forms Gramplet will not tell you where the error is, but you may get a message in grampsXX.log (in the root of gramps user directory) that may look like:
Traceback (most recent call last):
File "C:\Program Files\GrampsAIO64-6.0.5\gramps\gen\plug\_manager.py", line 252, in load_plugin
_module = self.import_plugin(pdata)
...
File "C:\Users\<~username>\AppData\Roaming\gramps\gramps60\plugins\Form\form.py", line 114, in __load_definitions
dom = xml.dom.minidom.parse(definition_file)
File "AIO/xml/dom/minidom.py", line 1958, in parse
File "AIO/xml/dom/expatbuilder.py", line 911, in parse
File "AIO/xml/dom/expatbuilder.py", line 207, in parseFile xml.parsers.expat.ExpatError: mismatched tag: line 12, column 10
If there are other (non-syntax) errors in the file then when you use the New button and select the form, it will probably fail and suggest you restart Gramps, if you open the details first you will see some information which may give you a clue as to where the issue is (start from the bottom of the error message), the following is an example:
25285: ERROR: grampsapp.py: line 157: Unhandled exception
...
File "C:\Users\<~username>\AppData\Roaming\gramps\gramps60\plugins\Form\editform.py", line 995, in __init__
title1, title2 = title.split('/')
ValueError: not enough values to unpack (expected 2, got 1)
For the example error above, the title was fine, the Forms Gramplet was reporting that one of the entries in the custom form was incorrectly typed and should be exactly like the supported form elements.
Submitting your form definitions
Once you have written some custom form definitions, you may wish to share them with the Gramps community.
On the Addon:Form Testing area that is available for this purpose.
See existing Addon:Form Definitions for a current list.
Issues
See issues attached to the Forms tag.
