Difference between revisions of "Form Addons"
(→Tips on debugging your custom form definitions: no one can see your form here so we have to generalise)
(→Tips on debugging your custom form definitions)
|Line 171:||Line 171:|
ValueError: not enough values to unpack (expected 2, got 1)</nowiki>
ValueError: not enough values to unpack (expected 2, got 1)</nowiki>
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
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 .
=== Submitting your form definitions ===
=== Submitting your form definitions ===
Revision as of 06:03, 6 May 2020
This is a Third-party Addon.
Please use carefully on data that is backed up, and help make it better by reporting any comments or problems to the author, or issues to the bug tracker
Census or Form?
Please note the Form Addons are a 2015 upgrade to expand flexibility. They supercede the Census Addons from Gramps 4.2.X
The Form gramplet allows users to create and edit structured source data in a single form. It makes the meticulous process of recording all the discrete elements far less fussy and error-prone.
Using a Form doesn't mean creating data that can only be accessed with the Form tool. You can forego using the Form Gramplet at any time but still see and edit the data that was entered. The Form gramplet merely streamlines creating Events with the Attributes to separately store elements of data from a structured source. You could do the same process using the standard Gramps editors... it would just involve a lot more steps per Person or Event.
- 1 Forms Gramplet
- 2 Form Selector
- 3 Form Editor
- 4 Configuration
- 5 See also
Before using the forms addons
you need to define the form that describes the information contained within a source.
The Forms Gramplet is designed to be added to the bottombar of a person view.
Before using the forms addons you need to define the form that describes the information contained within a source. See: Configuration
The Forms Gramplet lists all the events for the active person that can be edited using the form editor. The listing displays the source, date and place of the event together with the role the active person performs in the event.
A new event can be created by clicking the New button at the bottom of the Forms Gramplet which will show you the Select Form selector dialog where you can choose the form to use. Once you select a form you will be taken to the Form Editor.
An existing event can be edited either by highlighting a row and clicking the Edit button or by double-clicking on a row to bring up the the Form Editor.
The form selector allows the user to select a source that has been associated with a form. The sources are grouped by event type.
If the Form Selector list is empty then you need to define the form that describes the information contained within a source. See: Configuration
The form editor is designed so that most data for an event can be entered into a single form.
- First a citation reference should be entered. This should comprise of one or more references that uniquely identify the citation. For example, in the case of a UK census you will need to enter the PRO reference, Piece, Folio and Page.
- The date of the event can be entered. For a census, the date is populated automatically.
- A place can be selected in the usual Gramps manner.
The "Details" tab provides an area which allows the user to enter data specific to individual people listed in the source. This tab can be divided into sections. Each section consists of people performing the same role in the event.
A person section allows information about a single person to be entered. A new person can be created and selected by clicking the "+" button. A person already in Gramps can be selected by clicking the second button ("share"). The user is prevented from entering data until a person is selected.
A family section allows information about two people belonging to a family to be entered. A new family can be created and selected by clicking the "+" button. A family already in Gramps can be selected by clicking the second button ("share"). The user is prevented from entering data until a family is selected.
Multiple Person Section
A multiple person section allows information about multiple people to be entered. A new person can be created and then added to the section by clicking the "+" button. A person already in Gramps can be added to the section by clicking the second button ("share"). A person can be removed from the section by clicking the "-" button. The order of people in the section can be changed by highlighting a row and then using the up and down arrow buttons.
The Headings tab provides an area which allows the user to enter data specific to the event listed in the source.
The Gallery tab provides the ability to add media to the event. This is done in the same way as in the standard Gramps editors.
Before using the form addons, you need to define the form that describes the information contained within a source.
To do this you need to edit each Source and add an entry in the "Attributes" tab. The entry must have a key of "
Form" and a value which is a Code that uniquely identifies the form to be used eg:
If you are using Gramps in a language other than English, enter the translated version of the key (e.g. In French, "
Supported form definitions
To see a full list of the supported Code's for definitions included with the addon that are available, See: Form Definitions
Writing your own form definitions
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
test.xml will also be searched.
Definition files consist of an XML declaration followed by a
<?xml version="1.0" encoding="UTF-8" ?> <forms> </forms>
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.
type: The type of the event created by the form editor. This is the XML representation of an EventType.
title: A description of the form.
date: An optional date in a Gramps date format. This is only useful for census definitions.
<form id='UK1841' type='Census' title='1841 UK Census' date='6 Jun 1841'>
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 contains 3 attributes:
role: The role that people in this section perform in the event. This is the XML representation of an 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: An optional title which will be used to describe the section.
<section role='Primary' type='person' title='Child'>
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:
_attributeelement. This contains the key used to store column information in the attributes of event reference objects within the Gramps database. Once defined this text must not be changed.
- An optional
_longnameelement. This contains a fuller description of the column that is used in the tooltips in the editor.
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>
The underscore is important and indicates that the text should be translated by translators.
Each form element may optionally contain
heading elements. Heading elements describe information that is recorded once for each form.
A heading element contains:
_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>
Although you can add your definitions to the pre-defined entries in
form_xx.xml, it is recommended you create a separate file called
test.xml for this purpose.
Tips on debugging your custom form definitions
After creating or updating a form (in
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 it and if the New and Edit buttons don't appear in the Forms Gramplet 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 luckily 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-5.1.2\gramps\gen\plug\_manager.py", line 252, in load_plugin _module = self.import_plugin(pdata) ... File "C:\Users\<~username>\AppData\Roaming\gramps\gramps51\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\gramps51\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.
A Form Testing area is available for this purpose.
See existing Form Definitions for a current list.
- Civil registration From Wikipedia, the free encyclopedia
- Vital records From Wikipedia, the free encyclopedia
- Census From Wikipedia, the free encyclopedia