Changes

Jump to: navigation, search

Addon:Forms Gramplet

7,854 bytes added, 14:56, 2 October 2021
m
Improved 'Adding the gramplet' instructions
{{Third-party plugin}}
{{man notetip|Census or Form?|Please note the ''Form Addons'' are an upgrade released in 2015 to expand the flexibility of the orignal Census Addons. The ''Form Addons'' supersede the [[Census_Addons|Census Addons]] from Gramps 4.2.X the }}[[File:Forms Gramplet.png|thumb|right|450px|Forms Gramplet - Shown Undocked from Bottombar Of People Category View]]The Form Addons are gramplet allows users to create and edit structured source data in a replacement for single form. It makes the Census Addonsmeticulous process of recording all the discrete elements far less fussy and error-prone.}}
The {{man label|[[Form_Addons#Forms_Gramplet|Form gramplet allows users ]]}} has been enhanced to create handle other {{man label|[[Form_Definitions|forms]]}} such as birth, marriage and edit structured source data in a single formdeath 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 forego using the Form Gramplet at any time but still see and edit the data that was entered. The Form gramplet has been enhanced merely streamlines creating Events with the [[Gramps_{{Version manual}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_3#Attributes|Attributes]] to handle other forms such as birth, marriage and death certificates and parish register entriesseparately 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.
== Forms Gramplet == {{man warn|Before using the forms addons|You need to define the form that describes the information contained within a source.'''<br>See: [[Form_Addons#Configuration|Configuration]]}}{{-}}=== Adding the Forms Gramplet ===[[File:AddingFormsGrampletToBottombarOfPeopleCategoryView-51.png|thumb|right|450px|Adding Forms Gramplet to bottombar of People Category (Tree) View]]The '''Forms gramplet''' is designed to be added for 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.)  Select the {{man label|Forms}} menu option from the {{man label|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. The blank '''Forms Gramplet''' will be shown docked as below.{{-}}[[File:FormsGrampletShownInBottombarOfPeopleCategoryView-51.png|thumb|left|450px|Forms Gramplet - Shown docked In Bottombar Of People Category View]]{{-}}=== Initial Configuration for each source ==={{man menu|Before using the forms addons you need to define the form that describes the information contained within a source. See: [[Form_Addons#Configuration|Configuration]]}} The Forms Gramplet lists all the events for the active person that can stop 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 {{man button|New}} button at the bottom of the {{man label|Forms Gramplet}} which will show you the {{man label|[[Form_Addons#Form_Selector|Select Form]]}} selector dialog where you can choose the form to use. Once you select a form you will be taken to the {{man label|[[Form_Addons#Form_Editor|Form Editor]]}}. [[File:Forms Gramplet.png|thumb|right|450px|Forms Gramplet - Shown Undocked from Bottombar Of People Category View]]{{-}}<!-- [[File:Forms Gramplet showing existing event.png|thumb|right|450px|Forms Gramplet at any time - Showing existing event]] --> An existing event can be edited either by highlighting a row and still access clicking the {{man button|Edit}} button or by double-clicking on a row to bring up the {{man label|[[Form_Addons#Form_Editor|Form Editor]]}}.  If the {{man label|Forms Gramplet}} is undocked you can use the {{man button|Help}} button to see this page.{{-}} == Form Selector == The form selector allows the user to select a source that has been associated with a form. The sources are grouped by event type. [[File:Form Selector.png|thumb|left|450px]]{{-}}{{man menu|If the {{man label|Form Selector}} list is empty then you need to define the form that describes the information contained within a source. See: [[Form_Addons#Configuration|Configuration]]}}{{-}} == Form Editor == 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. All For a census, the Form gramplet does date is create populated automatically. * A place can be selected in the usual Gramps manner.{{-}}=== 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 . [[File:Form Editor.png|left]]{{-}}==== Person Section ==== A person section allows information about a single person to be entered. A new person can be created and attributes selected by clicking the {{man button|+}} button. A person already in Gramps can be selected by clicking the second button ({{man button|share}}). The user is prevented from entering data until a person is selected. [[File:Form Person Section.png|left]]{{-}}==== Family Section ==== A family section allows information about two people belonging to a family to store source be entered. A new family can be created and selected by clicking the {{man button|+}} button. A family already in Gramps can be selected by clicking the second button ({{man button|share}}). The user is prevented from entering datauntil a family is selected. [[File:Form Family Section.png|left]]{{-}}==== 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 {{man button|+}} button. A person already in Gramps can be added to the section by clicking the second button ({{man button|share}}). You could do this A person can be removed from the section by clicking the {{man button|-}} button. The order of people in the section can be changed by highlighting a row and then using the up {{man button|↑}} and down {{man button|↓}} arrow buttons. [[File:Form Multiple Section.png|left]]{{-}} ===Headings tab===The {{man label|Headings}} tab provides an area which allows the user to enter data specific to the event listed in the source. ===Gallery tab===The {{man label|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==
{{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_5.0_Wiki_Manual_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>
{{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>").}}
[[ImageFile:Form Source.png|left]]{{-}}=== Supported form definitions ===
To see a full list of the supported {{man label|Code}}'s for definitions included with the addon that are available, See: [[Form Definitions]]
=== Writing your own form definitions ===
{{man note|Note|Make sure that your definition file is saved using UTF-8 encoding.}}
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.
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 is value will appear in the XML representation "<code>Type</code>" column of an 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 definitionsor 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 contains can specify these 3 attributes:
* <code>role</code> : The role that people in this section perform in the event. This is value will appear in the XML representation "<code>Role</code>" column of an 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> : An optional title which will be This is used to describe when displaying the sectionon 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>
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 that and is only used in for tooltips (when you hover the mouse over the tooltips field in the editorform).* 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>
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.
=== Submitting =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.
Once 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 have written some custom definitionswhere the error is, but luckily you may wish to share them with get a message in <code>grampsXX.log</code> (in the Gramps community.root of gramps user directory) that may look like:
A [[ <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 Testing]] area is available for this purpose\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>
== Forms Gramplet ==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:
{{man menu|The Forms Gramplet is designed to be added to the bottombar of a [[Gramps_5 <nowiki> 25285: ERROR: grampsapp.py: line 157: Unhandled exception ... File "C:\Users\<~username>\AppData\Roaming\gramps\gramps51\plugins\Form\editform.0_Wiki_Manual_-_Categories#People_Category|person view]]}}py", line 995, in __init__ title1, title2 = title.split('/')ValueError: not enough values to unpack (expected 2, got 1)</nowiki>
The For the example error above, the title was fine, the Forms Gramplet lists all was reporting that one of the events for entries in the active person that can custom form was incorrectly typed and should be edited using exactly like the supported [[Form_Addons#Writing_your_own_form_definitions|form editor. The listing displays the source, date and place of the event together with the role the active person performs in the eventelements]].
A new event can be created by clicking the {{man button|New}} button at the bottom of the Forms Gramplet.=== Submitting your form definitions ===
An existing event can be edited either by highlighting a row and clicking Once you have written some custom form definitions, you may wish to share them with the {{man button|Edit}} button or by double-clicking on a rowGramps community.
A [[File:Forms Gramplet.png]] == Form Selector == The form selector allows the user to select a source that has been associated with a form. The sources are grouped by event type. [[Image:Form Selector.pngTesting]] == Form Editor == The form editor area is designed so that most data available 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. === 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. [[Image: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. [[Image: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 selectedthis purpose.
See existing [[Image:Form Family Section.pngDefinitions]]for a current list.
==Issues== Multiple Person Section See issues attached to the ''[https://gramps-project.org/bugs/tag_view_page.php?tag_id=257 Forms]'' tag.<!--===Feature Request===* {{bug|}} :-->
A multiple person section allows information about multiple people to be entered==See also==* [https://en. A new person can be created and then added to wikipedia.org/wiki/Civil_registration Civil registration] From Wikipedia, the section by clicking the "+" buttonfree encyclopedia* [https://en.wikipedia. A person already in Gramps can be added to the section by clicking org/wiki/Vital_record Vital records] From Wikipedia, the second button ("share")free encyclopedia* [https://en. A person can be removed from the section by clicking the "-" buttonwikipedia. The order of people in the section can be changed by highlighting a row and then using org/wiki/Census Census] From Wikipedia, the up and down arrow buttons.free encyclopedia
* [[Image:Form Multiple Section.pngData Entry Gramplet]]addon that allows an easy method of editing previously added people, and adding new and related people in your family tree.
===Headings tabForm Tutorials===The {{man label|Headings}} tab provides * Using the Form Gramplet, By Tim Graham, Photo Restorations by Tim G.** [https://www.youtube.com/watch?v=Y5hijkAF6eE Using the Form Gramplet] - Shows an area which allows older version of the user to enter data specific to Form addon (Published on Aug 4, 2016) Note: Video says it can be installed on the event listed in Dashboard and or the sourceCharts page but current version cannot.** [https://www.youtube.com/watch?v=NQL5shB9NzQ Defining Custom Forms for the Form Gramplet] - Shows an older version of the Form addon (Published on Aug 1, 2016)
===Gallery tab===
The {{man label|Gallery}} tab provides the ability to add media to the event. This is done in the same way as in the standard Gramps editors.
[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]
3,015
edits

Navigation menu