915
edits
Changes
Add Configuration section
The Form gramplet allows users to create and edit structured source data in a single form.
==Configuration==
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 identifies the form to be used.
{{man tip| Translated Gramps |2=If you are using Gramps in a language other than English, enter the translated version of the key.}}
=== Supported definitions ===
A number of supported [[Census Definitions|definitions]] are included with the download.
A full list of codes is available. See: [[Census Definitions]]
=== Writing your own definitions ===
If a form you require is not in the list of supported definitions then you can write your own.
Form defintions are stored in XML files. These are located in the Form directory beneath your plugins directory. The file called form.xml, provided in the download, contains some common definitions. Additional files called custom.xml and test.xml will also be searched.
Definition files consist of an XML declaration followed by a forms element.
<?xml version="1.0" encoding="UTF-8" ?>
<forms>
'''Note:''' Make sure that your definition file is saved using UTF-8 encoding.
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.
* 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:
* An _attribute element. 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 _longname element. This contains a fuller description of the column that is used in the tooltips in the editor.
* A size element. This contains the size of the column in the census report. It is a percentage of the page width. The sum of all size elemnts 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 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:
* An _attribute element. 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.xml, you can create a separate file called custom.xml for this purpose.
=== Submitting your definitions ===
Once you have written some custom definitions, you may wish to share them with the Gramps community.
A [[Census Testing]] area is available for this purpose.
[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]