Difference between revisions of "Addon:Forms Gramplet"

From Gramps
(→‎Usage)
 
(37 intermediate revisions by 3 users not shown)
Line 4: Line 4:
 
The {{man label|Forms 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.
 
The {{man label|Forms 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.
  
−
The {{man label|[[Addon:Forms_Gramplet#Forms_Gramplet|Forms Gramplet]]}} has been enhanced to handle other {{man label|[[Form_Definitions|forms]]}} such as birth, marriage and death certificates and parish register entries as well as the originally supported census forms.
+
The {{man label|[[Addon:Forms_Gramplet#Forms_Gramplet|Forms Gramplet]]}} has been enhanced to handle other {{man label|[[Addon:Form Definitions|forms]]}} such as birth, marriage and death certificates and parish register entries as well as the originally supported census forms.
  
−
Using a Form doesn't mean creating data that can only be accessed with the Form tool. You can stop 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 [[Gramps_{{Version manual}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_3#Attributes|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.
+
Using a Form doesn't mean creating data that can only be accessed with the Form Gramplet. You can stop 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 [[Gramps_{{man version}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_3#Attributes|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.
  
 
== Usage ==
 
== Usage ==
 
After [[#Adding_the_Forms_Gramplet|adding]] the {{man label|Forms Gramplet}} to the view and [[#Configuration|configuring]] your source form.
 
After [[#Adding_the_Forms_Gramplet|adding]] the {{man label|Forms Gramplet}} to the view and [[#Configuration|configuring]] your source form.
  
−
You can enter data by selecting the {{man button|New}} button to show the form selector and choosing which form type you are entering.
+
You can enter data by selecting the gramplets {{man button|New}} button to show the [[#Form_Selector|form selector]] and choosing which form type you are entering to see the associated [[#Form_Editor|Form Editor]].
−
 
 
−
{{stub}} <!-- needs a basic brief usage section that assumes the addon has been installed and the form configured -->
 
  
 
== Forms Gramplet ==
 
== Forms Gramplet ==
Line 20: Line 18:
 
{{-}}
 
{{-}}
 
=== Adding the Forms Gramplet ===
 
=== Adding the Forms Gramplet ===
−
[[File:FormsGramplet-ShownDocked-InBottombarOfPeopleCategoryView-60.png|thumb|right|450px|Forms Gramplet - Shown docked In Bottombar Of People Category View for Groupe People]]
+
[[File:FormsGramplet-ShownDocked-InBottombarOfPeopleCategoryView-60.png|thumb|right|600px|Forms Gramplet - Shown docked In Bottombar Of People Category View for Groupe People]]
  
−
The '''{{man label|Forms Gramplet}}''' is designed to be added to the bottombar {{icon|peop}}[[Gramps_{{Version manual}}_Wiki_Manual_-_Categories#People_Category|People Category]] (''Grouped'' or ''List'') view modes of Gramps. (After [[Third-party_Addons#Installing_Addons_in_Gramps|installation]], this gramplet will be available for addition in all these locations: the [[Gramps_{{man version}}_Wiki_Manual_-_Gramplets#The_split-screen_Sidebar_.26_Bottombar|sidebar/bottombar option]] for the following views: {{icon|peop}}People, {{icon|rela}}Relationships, {{icon|ance}}Charts, and {{icon|geog}}Geography.)   
+
The '''{{man label|Forms Gramplet}}''' is designed to be added to the bottombar {{icon|peop}}[[Gramps_{{man version}}_Wiki_Manual_-_Categories#People_Category|People Category]] (''Grouped'' or ''List'') view modes of Gramps. (After [[Third-party_Addons#Installing_Addons_in_Gramps|installation]], this gramplet will be available for addition in all these locations: the [[Gramps_{{man version}}_Wiki_Manual_-_Gramplets#The_split-screen_Sidebar_.26_Bottombar|sidebar/bottombar option]] for the following views: {{icon|peop}}People, {{icon|rela}}Relationships, {{icon|ance}}Charts, and {{icon|geog}}Geography.)   
  
 
Select the {{man menu|Forms}} menu option from the {{man menu|Add a gramplet}} submenu of the [[Gramps_{{man version}}_Wiki_Manual_-_Main_Window#Gramplet_Bar_Menu|Gramplet selection menus]]. Accessible by pressing the {{man button|&or;}} (''Down Arrowhead'' button) in the view's sidebar or bottombar.
 
Select the {{man menu|Forms}} menu option from the {{man menu|Add a gramplet}} submenu of the [[Gramps_{{man version}}_Wiki_Manual_-_Main_Window#Gramplet_Bar_Menu|Gramplet selection menus]]. Accessible by pressing the {{man button|&or;}} (''Down Arrowhead'' button) in the view's sidebar or bottombar.
Line 47: Line 45:
  
 
== Form Selector ==
 
== Form Selector ==
−
[[File:Form Selector.png|thumb|right|left|450px|'''Select Form''' selector - example]]
+
[[File:Form Selector-50.png|thumb|right|left|450px|'''Select Form''' selector - example]]
  
 
The {{man label|Select Form}} selector allows the user to select a source that has been associated with a form.  The sources are listed grouped by event type.
 
The {{man label|Select Form}} selector allows the user to select a source that has been associated with a form.  The sources are listed grouped by event type.
Line 55: Line 53:
  
 
== Form Editor ==
 
== Form Editor ==
 +
[[File:Form Editor.png|right|thumb|600px|example form]]
 +
The {{man label|New Form}} editor is designed so that most data for an event can be entered into a single form.
  
−
The form editor is designed so that most data for an event can be entered into a single form.
+
===Top section of the form ===
 +
The top section of the form may show
  
−
* 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.
+
* First a citation {{man label|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.
+
* The {{man label|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.
+
* A {{man label|Place:}} can be selected in the usual Gramps manner.
 +
 
 +
The form may have the following three tabs:
 +
* [[#Details_tab|Details tab]]
 +
* [[#Headings_tab|Headings tab]]
 +
* [[#Gallery_tab|Gallery tab]]
 
{{-}}
 
{{-}}
 +
 
=== Details tab===
 
=== Details tab===
−
The "{{man label|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.
+
The "{{man label|Details}}" tab provides an area which allows the user to enter data specific to individual people listed in the source. This tab maybe divided into sections.  Each section consists of people performing a role in the event.
−
 
+
[[File:Form Editor.png|left|thumb|450px]]
−
[[File:Form Editor.png|left]]
 
 
{{-}}
 
{{-}}
 
==== Person Section ====
 
==== Person Section ====
Line 98: Line 104:
 
{{man tip|{{man menu|'''Before using the form addons, you need to define the form that describes the information contained within a source.'''}}}}
 
{{man tip|{{man menu|'''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 {{man label|[[Gramps_{{Version manual}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_2#Editing_information_about_sources|Source]]}} and add an entry in the {{man label|"Attributes"}} tab.  The entry '''must''' have a key of "<code>Form</code>" and a value which is a {{man label|[[Form_Definitions|Code]]}} that uniquely identifies the form to be used eg: <code>UK1841</code>
+
To define the form to use you need to edit each {{man label|[[Gramps_{{man version}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_2#Editing_information_about_sources|Source]]}} and add an entry in the {{man label|"Attributes"}} tab.  The entry '''must''' have a key of "<code>Form</code>" and a value which is a {{man label|[[Addon:Form Definitions|Code]]}} that uniquely identifies the form to be used eg: <code>UK1841</code>
  
 
{{man tip| Translated Gramps |2=If you are using Gramps in a language other than English, enter the translated version of the key (e.g. In French, "<code>Formulaire</code>" instead of "<code>Form</code>").}}
 
{{man tip| Translated Gramps |2=If you are using Gramps in a language other than English, enter the translated version of the key (e.g. In French, "<code>Formulaire</code>" instead of "<code>Form</code>").}}
  
 
[[File:Form Source.png|left]]
 
[[File:Form Source.png|left]]
 +
 +
{{man note|While you may have more than one form code associated with a source; only the form for the first entry will be shown|To access the other forms change the order attribute to be the first.}}
 
{{-}}
 
{{-}}
 
=== Supported form definitions ===
 
=== Supported form definitions ===
Line 109: Line 117:
  
 
=== Writing your own form definitions ===
 
=== Writing your own form definitions ===
−
 
+
To create a form see the
−
{{man note|Note|Make sure that your definition file is saved using UTF-8 encoding.}}
+
* [[Addon:Form Creation|Form Creation]] page.
−
 
 
−
If a form you require is not in the list of supported [[Form Definitions|definitions]] then you can write your own.
 
−
 
 
−
Form definitions are stored in XML files.  These are located in the Form directory beneath your [[Gramps_{{Version manual}}_Wiki_Manual_-_User_Directory|user plugins directory]].  The file called <code>form_xx.xml</code>(where ''xx'' is a country code), is provided in the download, and contains some common definitions.  Additional files called <code>custom.xml</code> and <code>test.xml</code> will also be searched.
 
−
 
 
−
Definition files consist of an XML declaration followed by a <code>forms</code> element.
 
−
 
 
−
<?xml version="1.0" encoding="UTF-8" ?>
 
−
<forms>
 
−
</forms>
 
−
 
 
−
The <code>forms</code> element contains a number of <code>form</code> elements, each representing a form definition.  The form start-tag contains 4 attributes:
 
−
 
 
−
* <code>id</code> : A unique code to identify the form definition.  You will use this code in the "Form" attribute of the source.
 
−
* <code>type</code>: The type of the event created by the form editor.  This value will appear in the "<code>Type</code>" 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).
 
−
* <code>title</code> : A description of the form.  It should be possible to use anything here.
 
−
* <code>date</code> : 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'>
 
−
 
 
−
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 <code>section</code> start-tag can specify these 3 attributes:
 
−
 
 
−
* <code>role</code> : The role that people in this section perform in the event.  This value will appear in the "<code>Role</code>" column of events ("EventRoleType").
 
−
* <code>type</code> : The type of section. This defines how a section is displayed and people are selected.  Allowed values are:  '<code>person</code>' for a single person, '<code>multi</code>' for one or more people, or '<code>family</code>' for two people selected by a family.
 
−
* <code>title</code> : 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".
 
−
 
 
−
<nowiki><section role='Primary' type='person' title='Child'></nowiki>
 
−
 
 
−
Each section element should contain a <code>column</code> 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 <code>_attribute</code> element.  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 "<code>Name</code>" then the selected person's name will be prefilled.  Once defined this text must not be changed.
 
−
* An optional <code>_longname</code> element.  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 <code>size</code> 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 elements in a definition should total 100%.
 
−
 
 
−
<column>
 
−
    <_attribute>At Home</_attribute>
 
−
    <_longname>Working at Home</_longname>
 
−
    <size>6</size>
 
−
</column>
 
−
 
 
−
{{man note|Note|The underscore is important and indicates that the text should be translated by translators.}}
 
−
 
 
−
Each form element may optionally contain <code>heading</code> elements.  Heading elements describe information that is recorded once for each form.
 
−
 
 
−
A heading element contains:
 
−
 
 
−
* An <code>_attribute</code> 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 <code>form_xx.xml</code>, it is recommended you create a separate file called <code>custom.xml</code> or <code>test.xml</code> for this purpose.
 
−
 
 
−
====Tips on debugging your custom form definitions====
 
−
After creating or updating a form (in <code>custom.xml</code> or <code>test.xml</code>) to make sure your Form is correctly formatted use a text editor that includes an XML mode and syntax check, (like <code>NotePad++</code> and install the "<code>XML Tools</code>" 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 {{man button|New}} and {{man button|Edit}} buttons don't appear in the {{man label|Forms Gramplet}} then there is a good chance that an XML syntax (or other) error has occurred. The {{man label|Forms Gramplet}} will not tell you where the error is, but luckily you may get a message in <code>grampsXX.log</code> (in the root of gramps user directory) that may look like:
 
−
 
 
−
<nowiki>
 
−
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</nowiki>
 
−
 
 
−
If there are other (non-syntax) errors in the file then when you use the {{man button|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:
 
−
 
 
−
<nowiki>
 
−
  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)</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 [[Addon:Forms_Gramplet#Writing_your_own_form_definitions|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==
 
==Issues==
 
See issues attached to the ''[https://gramps-project.org/bugs/tag_view_page.php?tag_id=257 Forms]'' tag.
 
See issues attached to the ''[https://gramps-project.org/bugs/tag_view_page.php?tag_id=257 Forms]'' tag.
−
<!--
 
−
===Feature Request===
 
−
* {{bug|}} :
 
−
-->
 
  
 
==See also==
 
==See also==
−
* [https://en.wikipedia.org/wiki/Civil_registration Civil registration] From Wikipedia, the free encyclopedia
+
* [[Addon:Forms Gramplet|Forms Gramplet]] addon.
−
* [https://en.wikipedia.org/wiki/Vital_record Vital records] From Wikipedia, the free encyclopedia
+
** [[Addon:Form Definitions]]
−
* [https://en.wikipedia.org/wiki/Census Census] From Wikipedia, the free encyclopedia
+
** [[Addon:Form Testing]]
 +
** [[Addon:Form Creation]]
 +
** [[Addon:Census Check]] quickviews are part of the Forms addon; they are not available separately as it does not make any sense without the Forms addon.
  
 
* [[Addon:DataEntryGramplet|Data Entry Gramplet]] addon that allows an easy method of editing previously added people, and adding new and related people in your family tree.  
 
* [[Addon:DataEntryGramplet|Data Entry Gramplet]] addon that allows an easy method of editing previously added people, and adding new and related people in your family tree.  
 +
 +
===From Wikipedia, the free encyclopedia===
 +
* [https://wikipedia.org/wiki/Civil_registration Civil registration]
 +
* [https://wikipedia.org/wiki/Vital_record Vital records]
 +
* [https://wikipedia.org/wiki/Census Census]
  
 
===Form Tutorials===
 
===Form Tutorials===

Latest revision as of 02:28, 31 March 2026

Gramps-notes.png
This is a Third-party Addon. The Addon/Plugin system is controlled by the Plugin Manager.

Please use carefully on data that is backed up, and help make it better by reporting any issues to the bug tracker.
Unless otherwise stated on this page, you can download this addon by following these instructions.
Please note that some Addons have prerequisites that need to be installed before they can be used.

Tango-Dialog-information.png
Census or Form?

Please note the Forms Gramplet addon is an upgrade released in 2015 to expand the flexibility of the original Census Addons. The Forms Gramplet Addons supersede the Census Addons from Gramps 4.2.X

Forms Gramplet - Shown Undocked from Bottombar Of People Category View

The Forms 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.

The Forms Gramplet has been enhanced to handle other forms such as birth, marriage and death certificates and parish register entries as well as the originally supported census forms.

Using a Form doesn't mean creating data that can only be accessed with the Form Gramplet. You can stop 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.

Usage

After adding the Forms Gramplet to the view and configuring your source form.

You can enter data by selecting the gramplets New button to show the form selector and choosing which form type you are entering to see the associated Form Editor.

Forms Gramplet

Gnome-important.png
Before using the Forms Gramplet addon

You need to define the form that describes the information contained within a source.
See: Configuration


Adding the Forms Gramplet

Forms Gramplet - Shown docked In Bottombar Of People Category View for Groupe People

The Forms Gramplet is designed to be added to the bottombar PeoplePeople Category (Grouped or List) view modes of Gramps. (After installation, this gramplet will be available for addition in all these locations: the sidebar/bottombar option for the following views: PeoplePeople, RelationshipsRelationships, ChartsCharts, and GeographyGeography.)

Select the Forms menu option from the Add a gramplet submenu of the Gramplet selection menus. Accessible by pressing the ∨ (Down Arrowhead button) in the view's sidebar or bottombar.

The blank Forms Gramplet will be shown docked.

Initial Configuration for each source

Tango-Dialog-information.png
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.

Forms Gramplet - Shown Undocked from Bottombar Of People Category View


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 Form Editor.


If the Forms Gramplet is undocked you can use the Help button to see this page.

Form Selector

Select Form selector - example

The Select Form selector allows the user to select a source that has been associated with a form. The sources are listed grouped by event type.

Tango-Dialog-information.png
If the Select Form selector list is empty then you need to define the form that describes the information contained within a source.

See: Configuration


Form Editor

example form

The New Form editor is designed so that most data for an event can be entered into a single form.

Top section of the form

The top section of the form may show

  • 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 form may have the following three tabs:


Details tab

The "Details" tab provides an area which allows the user to enter data specific to individual people listed in the source. This tab maybe divided into sections. Each section consists of people performing a role in the event.

Form Editor.png


Person Section

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.

Form Person Section.png


Family Section

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.

Form Family Section.png


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.

Form Multiple Section.png


Headings tab

The Headings tab provides an area which allows the user to enter data specific to the event listed in the source.

Gallery tab

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.

Configuration

Tango-Dialog-information.png
Before using the form addons, you need to define the form that describes the information contained within a source.


To define the form to use 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: UK1841

Tango-Dialog-information.png
Translated Gramps

If you are using Gramps in a language other than English, enter the translated version of the key (e.g. In French, "Formulaire" instead of "Form").


Form Source.png
Gramps-notes.png
While you may have more than one form code associated with a source; only the form for the first entry will be shown

To access the other forms change the order attribute to be the first.


Supported form definitions

To see a full list of the supported Code's for definitions included with the addon that are available, See: Addon:Form Definitions

Writing your own form definitions

To create a form see the

Issues

See issues attached to the Forms tag.

See also

  • Data Entry Gramplet addon that allows an easy method of editing previously added people, and adding new and related people in your family tree.

From Wikipedia, the free encyclopedia

Form Tutorials

  • Using the Form Gramplet, By Tim Graham, Photo Restorations by Tim G.

Support forum threads

Retrieved from "https://ftp.gramps-project.org/wiki/index.php?title=Addon:Forms_Gramplet&oldid=130246"