Gramps - User contributions [en]

Gramps 5.2 Wiki Manual - Command Line

2024-11-28T04:14:42Z

Awg: Fixing typo of "AIO" acronym

{{man index|Gramps 5.2 Wiki Manual - Keybindings|Gramps 5.2 Wiki Manual - User Directory|5.2}}
{{languages|Gramps_5.2_Wiki_Manual_-_Command_Line}}
{{#vardefine:chapter|C}}
{{#vardefine:figure|0}}
This appendix provides the reference to the command line capabilities available when launching '''Gramps (for desktops)''' from the terminal.

For '''Gramps Web''', see "Managing users on the command line" on the [https://www.grampsweb.org/install_setup/users/ User System] page of the Gramps Web documentation.
== Start Gramps through the Command Line ==

Normally Gramps is started through the graphical user interface (GUI) on [[Gramps_5.2_Wiki_Manual_-_Getting_started#Start_Gramps|your platform]].

It is also possible to start Gramps using a command line interface (CLI). CLI use can
* produce reports that are not available via the GUI,
* create reports, do conversions etc. without opening a window and
* can provide [[Gramps_5.2_Wiki_Manual_-_Main_Window#Seeing_all_the_error_messages|extra information]] in the event of problems.

This section of the user manual describes how to start Gramps through the CLI, and the features that are available.

The way you start Gramps through the CLI depends on the operating system you are using.

For simplicity of description, the examples of use below are written from the point of view of running Gramps on Linux. The examples would need to be changed for other platforms.

=== Linux ===

Linux platform is the only ''officially'' supported platform. (Other platforms are ''community supported''.) This is because Gramps developers design, code, use and test the source code on that platform. So diagnosing and fixing any problems that arise (whether due to upgrades or other causes) is done using Linux tools.

Assuming you have used the standard Package Manager (either through a CLI or a GUI) for your Linux distribution, you start Gramps through the CLI by typing:
gramps

If you have done a "[https://gramps-project.org/wiki/index.php/Linux:Build_from_source build from source]", navigate to where you installed the the application. (That folder will include the <code>Gramps.py</code> file.) Type:
python3 Gramps.py

=== MS Windows ===

MS Windows is a [[Download|community supported]] platform. If you install the [[All_In_One_Gramps_Software_Bundle_for_Windows|Windows AIO bundle]], then this will place an icon on the desktop as well as a menu item in the 'Start' menu. However, the Gramps installation directory is not added to the system path and to run gramps via CLI, we need to know the path to that directory. To find the installation folder, refer to [[All_In_One_Gramps_Software_Bundle_for_Windows#Installation_folder|AIO bundle's installation folder section]].

To find the path using a shortcut icon instead,
* Right-click on the <code>GrampsAIO64 {{template:Version windows AIO64}}-console</code> application, or the corresponding item in the Start menu.
* Note down the file location (its "Start in' directory).
* Select the full path and copy ({{man key press|Ctrl|c}}) it.

To run Gramps from the command line, you'll need to start a console window:
* From the Start menu, start cmd.exe.
* Change directory to the installation directory you located.
* Type in or paste the path, surrounding it in quotes if there are spaces.
* Press {{man key press|Enter}}.

For example, this might be:
cd "C:\Program Files\GrampsAIO64-{{template:Version windows AIO64}}"
gramps

You may use any of the command-line options along with this. For example, to get a detailed listing of all of the Family Tree databases in your default Family Tree folder, you would append <code>-L</code>
cd "C:\Program Files\GrampsAIO64-{{template:Version windows AIO64}}"
gramps -L

See example usage https://github.com/gramps-project/addons-source/pull/121

=== macOS ===

macOS is a [[Download|community supported]] platform. If you download the macOS disk image (.dmg), then you simply drag the application to your application folder (or anywhere else you want to store it) and start Gramps by double clicking on the application in the normal way. The [https://github.com/Homebrew Homebrew package manager] also allows for installation of the application in the usual Applications folder.

To run from the command line, you'll need to start Terminal, found in the Utilities folder of the main Applications folder (/Applications/Utilities). Once you have a terminal window open, at the prompt type
/path/to/Gramps.app/Contents/MacOS/Gramps
If you installed Gramps in Applications along with most of your other apps, as suggested above, that would be
/Applications/Gramps.app/Contents/MacOS/Gramps
You may use any of the command-line options along with this. For example, to get a detailed listing of all of the Family Tree databases in your default Family Tree folder, you would use
/Applications/Gramps.app/Contents/MacOS/Gramps -L

There are other ways to install Gramps for macOS, but these are much more complicated and are not covered here.

== Python options ==

In the examples of different platforms above, and also in commands in various files you may see some options after the 'python' command, for example '-EO' in
"python3 -EO ..\share\gramps\gramps.py -L

It is important to distinguish between the '''python options''' in this case:
-EO
and the '''Gramps options''', in this case
-L

The '''python options''' that you may come across are:
* <code>-E</code> Ignore all PYTHON* environment variables, e.g. <code>PYTHONPATH</code> and <code>PYTHONHOME</code>, that might be set.
* <code>-O</code> Turn on basic optimizations. This changes the filename extension for compiled (bytecode) files from <code>.pyc</code> to <code>.pyo</code>. See also PYTHONOPTIMIZE.

The <code>-O</code> optimise flag has a number of effects in Gramps:
* If it is not turned on, an additional {{man menu|[[Gramps_5.2_Wiki_Manual_-_Tools#Debug|Debug]]}} entry appears in the {{man menu|[[Gramps_5.2_Wiki_Manual_-_Tools|Tools]]}} menu.
* If it is not turned on, [[Logging_system#So_how_logging_works_in_Gramps_after_all.3F|info logging messages are output]].
* If it is not turned on, [[Debugging_Gramps#Add_debug_statements|debug statements]] may be activated.
* If it is not turned on, additional features are available in the [[Gramps_5.2_Wiki_Manual_-_Plugin_Manager|Plugin Manager]].

The '''Gramps options''' are described below.

== Available Gramps options ==

This section provides the reference list of all command line options available in Gramps. If you want to know more than just a list of options, see next sections: [[#Operation|Operation]] and [[#Examples| Examples]]. The summary below is printed by
gramps -h
or
gramps --help

<pre>
Usage: gramps.py [OPTION...]
--load-modules=MODULE1,MODULE2,... Dynamic modules to load

Help options
-?, --help Show this help message
--usage Display brief usage message

Application options
-O, --open=FAMILY_TREE Open Family Tree
-U, --username=USERNAME Database username
-P, --password=PASSWORD Database password
-C, --create=FAMILY_TREE Create on open if new Family Tree
-i, --import=FILENAME Import file
-e, --export=FILENAME Export file
-r, --remove=FAMILY_TREE_PATTERN Remove matching Family Tree(s) (use regular expressions)
-f, --format=FORMAT Specify Family Tree format
-a, --action=ACTION Specify action
-p, --options=OPTIONS_STRING Specify options
-d, --debug=LOGGER_NAME Enable debug logs
-l [FAMILY_TREE_PATTERN...] List Family Trees
-L [FAMILY_TREE_PATTERN...] List Family Trees in Detail
-t [FAMILY_TREE_PATTERN...] List Family Trees, tab delimited
-u, --force-unlock Force unlock of Family Tree
-s, --show Show config settings
-c, --config=[config.setting[:value]] Set config setting(s) and start Gramps
-y, --yes Don't ask to confirm dangerous actions (non-GUI mode only)
-q, --quiet Suppress progress indication output (non-GUI mode only)
-v, --version Show versions
-S, --safe Start Gramps in 'Safe mode'
(temporarily use default settings)
-D, --default=[APXFE] Reset settings to default;
A - addons are cleared
P - Preferences to default
X - Books are cleared, reports and tool settings to default
F - filters are cleared
E - Everything is set to default or cleared
</pre>

The usage message is as follows:

gramps --usage

<pre>
Example of usage of Gramps command line interface

1. To import four databases (whose formats can be determined from their names)
and then check the resulting database for errors, one may type:
gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps -i file4.wft -a tool -p name=check.

2. To explicitly specify the formats in the above example, append filenames with appropriate -f options:
gramps -i file1.ged -f gedcom -i file2.gpkg -f gramps-pkg -i ~/db3.gramps -f gramps-xml -i file4.wft -f wft -a tool -p name=check.

3. To record the database resulting from all imports, supply -e flag
(use -f if the filename does not allow Gramps to guess the format):
gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg

4. To save any error messages of the above example into files outfile and errfile, run:
gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile

5. To import three databases and start interactive Gramps session with the result:
gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps

6. To open a database and, based on that data, generate timeline report in PDF format
putting the output into the my_timeline.pdf file:
gramps -O 'Family Tree 1' -a report -p name=timeline,off=pdf,of=my_timeline.pdf

7. To generate a summary of a database:
gramps -O 'Family Tree 1' -a report -p name=summary

8. Listing report options
Use the name=timeline,show=all to find out about all available options for the timeline report.
To find out details of a particular option, use show=option_name , e.g. name=timeline,show=off string.
To learn about available report names, use name=show string.

9. To convert a Family Tree on the fly to a .gramps xml file:
gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml

10. To generate a web site into an other locale (in German):
LANGUAGE=de_DE; LANG=de_DE.UTF-8 gramps -O 'Family Tree 1' -a report -p name=navwebpage,target=/../de

11. Finally, to start normal interactive session type:
gramps

Note: These examples are for bash shell.
Syntax may be different for other shells and for Windows.

</pre>

=== List options ===
Print a list of known family trees:

;Sparse
-l, List Family Trees

gramps -l

<pre>
List of known Family Trees in your database path

/home/<~username>/.gramps/grampsdb/5a46c1c3 with name "Example Family Tree"
</pre>
{{-}}

;Detailed
-L, List Family Trees in Detail

gramps -L

<pre>
Gramps Family Trees:
Family Tree "Example Family Tree":
Database: SQLite
Database module location: /usr/lib/python3.6/sqlite3/__init__.py
Database module version: 2.6.0
Database version: 3.21.0
Last accessed: 30/12/17 09:29:37
Locked?: False
Number of citations: 2854
Number of events: 3432
Number of families: 762
Number of media: 7
Number of notes: 19
Number of people: 2157
Number of places: 1294
Number of repositories: 3
Number of sources: 4
Number of tags: 2
Path: /home/<~username>/.gramps/grampsdb/5a46c1c3
Schema version: 18.0.0
</pre>

{{man note|Note that dates are shown in the default LOCALE format.|You change that at the system level. For example, on [[Gramps_Glossary#posix|POSIX]]-based systems you could use: <pre>LC_TIME=en_AU.UTF-8 gramps -L</pre>}}
{{-}}

=== Version options ===

-v or --version prints version of Gramps and dependencies,
information about environment settings and python and system paths

gramps -v

<pre>
Gramps Settings:
----------------
python : 3.7.5
gramps : 5.2.1
gtk++ : 3.24.12
pygobject : 3.34.0
pango : 1.42.3
cairo : 1.16.0
pycairo : 1.16.2
osmgpsmap : 1.0
GExiv2 : 0.10
ICU : 63.1
PyICU : 2.2
o.s. : linux
kernel : 5.3.0-24-generic

Environment settings:
---------------------
LANG : en_GB.UTF-8
LANGUAGE : en_GB:en
GRAMPSI18N: not set
GRAMPSHOME: not set
GRAMPSDIR : not set
PYTHONPATH:
/usr/lib/python3/dist-packages/gramps
/usr/bin
/usr/lib/python37.zip
/usr/lib/python3.7
/usr/lib/python3.7/lib-dynload
/usr/local/lib/python3.7/dist-packages
/usr/lib/python3/dist-packages

Non-python dependencies:
------------------------
Graphviz : 2.40
Ghostscr. : 9.27

System PATH env variable:
-------------------------
/usr/local/sbin
/usr/local/bin
/usr/sbin
/usr/bin
/sbin
/bin
/usr/games
/usr/local/games
/snap/bin

Databases:
-------------------------
bsddb :
version : 6.2.6
db version : 5.3.28
location : /usr/lib/python3/dist-packages/bsddb3/__init__.py
sqlite3 :
version : 3.29.0
py version : 2.6.0
location : /usr/lib/python3.7/sqlite3/__init__.py
</pre>

{{-}}

=== Format options ===

The format of any file destined for opening, importing, or exporting can be specified with the <pre>-f format</pre> option. The acceptable <tt>''format''</tt> values are listed below.

==== Full family tree support ====
These formats contain all your data that is present in a family tree.

* '''gramps''' - Gramps XML format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .gramps
* '''gpkg''' - Gramps package XML format: This format is available for import and export. When not specified, it can be guessed if the filename ends with .gpkg. This creates a zip package with your data as xml, and all your media files included
* '''grdb''' - pre Gramps 3.x database: This format is available for import to support the old file format of Gramps. Everything in the grdb file is imported. When not specified, it can be guessed if the filename ends with .grdb
* '''burn''' - GNOME iso burning: export, only available on GNOME where burn protocol exists

==== Reduced family tree support ====
These formats contain most, but not all data that can be created in Gramps

*'''ged''' - GEDCOM format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .ged
*'''gw''' - GeneWeb file: This format is available for import and export. When not specified, it can be guessed if the filename ends with .gw

==== Subset of your data ====
These formats contain a specific subset of your data

* '''csv''' - Comma Separated Value: This format is available for import and export. Be careful however, import must be as values created by the export function. Only a part of your data is contained in the output.
* '''vcf''' - VCard 3.0 format: import and export
* '''vcs''' - VCalendar format: export
* '''def''' - old Pro-Gen format: import
* '''wft''' - Web Family Tree: This format is available for export only. When not specified, it can be guessed if the filename ends with .wft

=== Opening options ===

You can open a family tree, or you can ''open'' a file by importing it in an empty family tree.

To let Gramps handle this automatically, just supply the family tree or filename you want to open:

python gramps.py 'My Fam Tree'
python gramps.py JohnDoe.ged

The first opens a family tree, the second imports a GEDCOM into an empty family tree.

Additionally, you can pass Gramps the name of the family tree to be opened:

* use this option : <code>-O famtree</code> or <code>--open=famtree</code>

<code>-O</code>, Open of a family tree. This can be done also by just typing the name (name or database dir)

Examples:
python gramps.py 'Family Tree 1'
python gramps.py /home/cristina/.gramps/grampsdb/47320f3d
python gramps.py -O 'Family Tree 1'
python gramps.py -O /home/cristina/.gramps/grampsdb/47320f3d

{{Man tip| Tip |If no option is given, just a name, Gramps will ignore the rest of the command line arguments. Use the <code>-O</code> flag to open, <code>-i</code> to import, and do something with the data.}}

{{Man tip| Tip |Only family trees can be opened directly. For other formats, you will need to use the import option which will set up the empty database and then import data into it.}}

{{Man tip| Tip |Only a single family tree can be opened. If you need to combine data from several sources, you will need to use the import option.}}

=== Import options ===

The files destined for import can be specified with the <code>-i filename</code> or <code>--import=filename</code> option. The format can be specified with the <code>-f format</code> or <code>--format=format</code> option, immediately following the ''filename'' . If not specified, the guess will be attempted based on the ''filename''.

Example:
python gramps.py -i 'Family Tree 1' -i 'Family Tree 2'
python gramps.py -i test.grdb -i data.gramps

{{man tip | Tip |More than one file can be imported in one command. If this is the case, Gramps will incorporate the data from the next file into the database available at the moment.}}

When more than one input file is given, each has to be preceded by <code>-i</code> flag. The files are imported in the specified order, i.e. <code> -i file1 -i file2 </code> and <code> -i file2 -i file1 </code> might produce different Gramps IDs in the resulting database.

=== Export options ===

The files destined for export can be specified with the <code>-e filename</code> or <code>--export=filename</code> option. The format can be specified with the <code>-f</code> option immediately following the ''filename'' . If not specified, the guess will be attempted based on the ''filename'' . For iso format, the ''filename'' is actually the name of directory the Gramps database will be written into. For gramps-xml, gpkg, gedcom, wft, geneweb, and gramps-pkg, the ''filename'' is the name of the resulting file.

-e, export a family tree in required format. It is not possible to export to a family tree.

Example:
python gramps.py -i 'Family Tree 1' -i test.grdb -f grdb -e mergedDB.gramps
Note that above does not change 'Family Tree 1' as everything happens via a temporary database, whereas:
python gramps.py -O 'Family Tree 1' -i test.grdb -f grdb -e mergedDB.gramps
will import test.grdb into Family Tree 1, and then export to a file !

{{man tip| Exporting more files |More than one file can be exported in one command. If this is the case, Gramps will attempt to write several files using the data from the database available at the moment.}}

When more than one output file is given, each has to be preceded by <code>-e</code> flag. The files are written one by one, in the specified order.

=== Action options ===

The action to perform on the imported data can be specified with the <code>-a action</code> or <code>--action=action</code> option. This is done after all imports are successfully completed.

The following actions remain the same:

*''report'': This action allows producing reports from the command line.

*''tool'': This action allows to run a tool from the command line.

Reports and tools generally have many options of their own, so these actions should be followed by the report/tool option string. The string is given using the <code>-p option_string</code> or <code>--options=option_string</code> option.

The actions available in older versions of Gramps which were relocated in Gramps 3.3 are:

*''summary'': This action was the same as {{man menu|Reports ->View ->Summary}}. In Gramps 3.3 it was replaced by (or renamed to) '''-a report -p name=summary'''.

*''check'': This action was the same as {{man menu|Tools ->Database Processing ->Check and Repair}}. In Gramps 3.3 it was replaced by (or renamed to) '''-a tool -p name=check'''.

==== report action option ====
You can generate most reports from the command line using the report action.

An example:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html"

You can provide the css style to use here with the css option:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css=Web_Nebraska.css"
or without css in the html output:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css="

{{man tip| Report option string |The report option string should satisfy the following conditions: It must not contain any spaces (due to the general nature of the command line interface). If some arguments need to include spaces, the string should be enclosed with quotation marks. Option string must list pairs of option names and values. Within a pair, option name and value must be separated by the equal sign. Different pairs must be separated by commas.}}

Most of the report options are specific for every report. However, there are some common options.

*<code>name=report_name</code>: This mandatory option determines which report will be generated.
{{man note|Report names|If the supplied report_name does not correspond to any available report, an error message will be printed followed by this list of available reports. 
<pre>
Available names are:
ancestor_chart - Ancestor Tree
ancestor_report - Ahnentafel Report
AncestorFill - AncestorFill
birthday_report - Birthday and Anniversary Report
calendar - Calendar
d3-ancestralcollapsibletree - Ancestral Collapsible Tree
d3-ancestralfanchart - Ancestral Fan Chart
d3-descendantindentedtree - Descendant Indented Tree
database-differences-report - Database Differences Report
denominoviso - DenominoViso
descend_chart - Descendant Tree
descend_report - Descendant Report
DescendantBook - Descendant Book
Descendants Lines - Descendants Lines
det_ancestor_report - Detailed Ancestral Report
det_descendant_report - Detailed Descendant Report
DetailedDescendantBook - Detailed Descendant Book
double_cousins - Double Cousins
DynamicWeb - Dynamic Web Report
endofline_report - End of Line Report
family_descend_chart - Family Descendant Tree
family_group - Family Group Report
familylines_graph - Family Lines Graph
FamilySheet - Family Sheet
FamilyTree - Family Tree
fan_chart - Fan Chart
gt_ancestor - Ancestor Tree
gt_descendant - Descendant Tree
gt_grandparent - Grandparent Tree
gt_sandclock - Sandclock Tree
gt_sandclock_family - Sandclock Tree for a Family
Heatmap - Heatmap
hourglass_graph - Hourglass Graph
indiv_complete - Complete Individual Report
kinship_report - Kinship Report
LastChangeReport - Last Change Report
LinesOfDescendency - Lines of Descendency Report
ListeEclair - Tiny Tafel
MediaReport - Media Report
navwebpage - Narrated Web Site
networkchart - Network Chart
notelinkreport - Note Link Report
number_of_ancestors - Number of Ancestors Report
PedigreeChart - Pedigree Chart
PersonEverythingReport - PersonEverything Report
place_report - Place Report
records - Records Report
rel_graph - Relationship Graph
Repositories Report - Repositories Report
SourcesCitationsReport - Sources and Citations Report
statistics_chart - Statistics Charts
summary - Database Summary Report
tag_report - Tag Report
timeline - Timeline Chart
TimePedigreeHTML - Timeline Pedigree Report
TodoReport - Todo Report
WebCal - Web Calendar
</pre>}}
*<code>of=</code>: output filename and optional destination folder/directory eg: <code>of="C:\Users\<username>\Desktop\FamilyTree.odt"</code>
*<code>off=</code>: output format. These are the extension an output format makes available, eg, pdf, html, doc, ...
*<code>style=</code>: for text reports, the stylesheet to use. Defaults to 'default'.
*<code>show=all</code>: This will produce the list of names for all options available for a given report.
*<code>show=option_name</code>: This will print the description of the functionality supplied by the option_name, as well as what are the acceptable types and values for this option.

So, to learn to use a report, do for example:
gramps -O "Family Tree 1" -a report -p "name=family_group,show=all"

{{man tip| Tip |If an option is not supplied, the last used value will be used. If this report has never been generated before, then the value from last generated report will be used when applicable. Otherwise, the default value will be used.}}

When more than one output action is given, each has to be preceded by <code>-a</code> flag. The actions are performed one by one, in the specified order.

{{man tip| lists |Some reports have options or arguments which are interpreted (by the report) to be on multiple lines. For instance some reports allow you to format how the information will be shown, perhaps with a name on one line and the person's birth date on the next line. Such multiple-line options or arguments are called "lists" by Gramps.}}

On the command line such lists must always start with a left square bracket <code>[</code> and must always end with a right square bracket <code>]</code> but since such square brackets are usually "special" to the "shell" (they mean something to the command interpreter
you are typing the command to), you must "escape" them so that they are ignored by your shell.

The details vary with each shell but (in linux/UNIX) usually you can precede such a square bracket with a backslash <code>\</code> or put quotation marks around the square bracket, usually either "single" or "double" ones.

The Hourglass Graph report allows you to put a "note" at the top of the report and such a "note" is an example of a "list" option. Here is an example:
gramps -O "Family Tree 1" -a report -p name=hourglass_graph,note='[line one,line two]'
which shows that inside such a list different lines are separated by commas, and that spaces are acceptable since the quotation marks are already there for the square brackets.

But if you want to have a comma inside your report you have to somehow tell Gramps that comma is not one which separates lines. You do that by enclosing the line with the comma in quotation marks (either single or double).

But if you are already using a set of quotation marks (to enclose your square brackets) you have to use the other type to enclose
the line with your comma. Here is an example:
gramps -O "Family Tree 1" -a report -p name=hourglass_graph,note="['line one, also line one','line two, also line two']"

It is possible to include any character in a list but the details are beyond the scope of this command-line introduction to Gramps.

You will need to know the precise methods available in your particular command shell interpreter to include a character which is "special" to your shell or "special" to Gramps (like the comma in the example above) but in general you will have to "escape" it twice, once to your shell and once again to Gramps, since you don't want your shell to think it is some instruction it should pay attention to and you don't want Gramps to think that either.

==== tool action option ====
You can run most tools from the command line using the 'tool' action.
To see which ones, say:
gramps -O "Family Tree 1" -a tool -p show=all
To see a tool's available options, for instance the "verify" tool:
gramps -O "Family Tree 1" -a tool -p name=verify,show=all
To run a tool, for instance the "verify" tool:
gramps -O "Family Tree 1" -a tool -p name=verify

{{man note|Tool names|If the supplied tool_name does not correspond to any available tool, an error message will be printed followed by this list of available tools. 
<pre>
Available names are:
check - Check and Repair Database
chtype - Rename Event Types
dgenstats - Dump Gender Statistics
evname - Extract Event Description
rebuild - Rebuild Secondary Indexes
rebuild_genstats - Rebuild Gender Statistics
rebuild_refmap - Rebuild Reference Maps
reorder_ids - Reorder Gramps IDs
test_for_date_parser_and_displayer - Check Localized Date Displayer and Parser
testcasegenerator - Generate Testcases for Persons and Families
verify - Verify the Data
</pre>}}

==== book action option ====
{{man note|New feature|Added in Gramps 5.0}}
You can run books from the command line using the 'book' action.
To see which ones, say:
gramps -O "Family Tree 1" -a book
To see a book's available options, for instance a book called "mybook":
gramps -O "Family Tree 1" -a book -p name=mybook,show=all
To run a book, for instance a book called "mybook":
gramps -O "Family Tree 1" -a book -p name=mybook

{{man note|Book names|If the supplied book_name does not correspond to any available Book, an error message will be printed followed by this list of available Books. eg: Example listing only as the Books will be whatever you have named them. 
<pre>
Available names are:
Granny Jones
Grampa John
Smith Family History
</pre>}}

=== Force unlock option ===

*<code>-u</code>: you can extend the <code>-O</code> flag with <code>-u</code> to force a locked family to be unlocked. This allows you to recover from a crash that leaves the family tree (database) locked, from the command line.

An example (to unlock the "Family Tree 1" database):
:<code>gramps -O "Family Tree 1" -a report -u > /dev/null</code>

{{man note|Note|It is not possible to open family trees that need repair from the command line.}}

See also:
* [[Gramps_5.2_Wiki_Manual_-_Manage_Family_Trees#Unlocking_a_Family_Tree|Manage Family Trees:Unlocking a Family Tree]]

=== Configuration (config) option ===
When all configuration variable(s) are set Gramps will start with these new values.

These options can takes three forms:
{{man note|Note|Except for examples <tt>1</tt> and <tt>3.2</tt>, All the following examples, use <code>behavior.database-path</code> as the configuration variable to change.}}

;1) See all config values: <code>-s</code> or <code>--show</code>
 For example:
gramps --show
<pre>
Gramps config settings from /home/<~username>/.gramps/gramps50/gramps.ini:
export.proxy-order=[['privacy', 0], ['living', 0], ['person', 0], ['note', 0], ['reference', 0]]

database.compress-backup=True
database.backend='bsddb'
database.backup-path='/home/<~username>'
database.port=''
database.autobackup=0
database.path='/home/<~username>/.gramps/grampsdb'
database.host=''
database.backup-on-exit=True

geography.lock=False
....
</pre>

{{-}}

;2) See a single config value: <code>--config=database.path</code> or <code>-c database.path</code>
 For example:
gramps --config=database.path
<pre>
Current Gramps config setting: database.path:'/home/<~username>/.gramps/grampsdb'
</pre>

;3) Set a value: <code>--config=behavior.database-path:'/media/mydb'</code> or <code>-c behavior.database-path:'/media/mydb'</code>
 For example:

;3.1) Set a value to its default: <code>--config=behavior.database-path:DEFAULT</code> or <code>-c behavior.database-path:DEFAULT</code>
 For example:

;3.2) Set more than one value: <code>--config=behavior.use-tips:False --config=behavior.autoload:True</code> or <code>-c behavior.use-tips:False -c behavior.autoload:True</code>
 For example:

=== Safe mode ===
<code>gramps -S</code> or <code>gramps --safe</code>

This CLI command starts Gramps as if it had never been installed before. In this mode, any previous family trees can still be loaded, as long as they were stored in the default folder. All other settings, filters, books, addons etc. are either cleared or returned to their default values. Other CLI commands can be used, or, if none, Gramps will start the GUI. Nothing except the actual family tree data is saved.

Note that this is typically used to see if Gramps behaves better when it is running as if with a totally 'clean' install. It is NOT permanent (if you want that see [[#Defaults|Defaults]] below), if you start Gramps normally after using this command all of your previous settings etc. are still there.

This actually works by setting the folder that Gramps uses to store its user data (except for family trees) to a temporary directory, which is deleted when Gramps closes.
=== Defaults ===
<code>gramps -D E</code> or <code>gramps --default=E</code>

This CLI command causes Gramps to clear out or return to defaults the desired settings.
The family tree databases are NOT cleared out or removed.
The sub-commands (replace the 'E' from the example command line above with one or more of
the subcommand characters) are:

*<code>A</code> Addons are cleared. Any installed addons are removed, along with their settings.
*<code>F</code> Filters are cleared. Any custom filters are removed.
*<code>P</code> Preferences are returned to their default values.
*<code>X</code> Books are cleared, Reports and Tools settings are returned to their default values.
*<code>Z</code> Old '.zip' files from family tree version upgrades are deleted.
*<code>E</code> Everything except the actual family tree data is returned to default settings. This does all of the above as well as a few more items; deletes thumbnails, maps, and the user CSS (used in web reports).

For example:
gramps -D AP
will cause Gramps to remove all the Addons and to reset Preferences to their default values.
== Operation ==

If the first argument on the command line does not start with a dash (i.e. no flag), Gramps will attempt to open the file with the name given by the first argument and start an interactive session, ignoring the rest of the command line arguments.

If the <code>-O</code> flag is given, then Gramps will try opening the supplied file name and then work with that data, as instructed by the further command line parameters.

{{man note|1=Note |2=Only one file can be opened in a single invocation of Gramps. If you need to get data from multiple sources, use the importing options by using <code>-i</code> flag.}}

With or without the <code>-O</code> flag, there could be multiple imports, exports, and actions specified further on the command line by using <code>-i</code> , <code>-e</code> , and <code>-a</code> flags.

The order of <code>-i</code> , <code>-e</code> , or <code>-a</code> options with respect to each does not matter. The actual execution order always is: all imports (if any) -> all exports (if any) -> all actions (if any).

{{man note| Note |But opening must always be first!}}

If no <code>-O</code> or <code>-i</code> option is given, Gramps will launch its main window and start the usual interactive session with the empty database, since there is no data to process, anyway. (Unless you have already expressed a "preference" that it start with the last database it used.)

If no <code>-e</code> or <code>-a</code> options are given, Gramps will launch its main window and start the usual interactive session with the database resulted from opening and all imports (if any). This database resides in a directory under the ''<code>~/.gramps/grampsdb/</code>'' directory.

Any errors encountered during import, export, or action, will be either dumped to stdout (if these are exceptions handled by Gramps) or to stderr (if these are not handled). Use usual shell redirections of stdout and stderr to save messages and errors in files.

== Examples ==

*To import four databases (whose formats can be determined from their names) and then check the resulting database for errors, one may type:

:<code>gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps -i file4.wft -a check</code>

*To explicitly specify the formats in the above example, append filenames with appropriate -f options:

:<code>gramps -i file1.ged -f gedcom -i file2.gpkg -f gramps-pkg -i ~/db3.gramps -f gramps-xml -i file4.wft -f wft -a check</code>

*To record the database resulting from all imports, supply -e flag (use -f if the filename does not allow Gramps to guess the format):

:<code>gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg</code>

*To save any error messages of the above example into files outfile and errfile, run:

:<code>gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile </code>

*To import three databases and start interactive Gramps session with the result:

:<code>gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps </code>

*To open a database and, based on that data, generate timeline report in PDF format putting the output into the my_timeline.pdf file:

:<code>gramps -O 'Family Tree 1' -a report -p name=timeline,off=pdf,of=my_timeline.pdf </code>

{{man tip|1=Listing report options |2=Use the <code>''name=timeline,show=all''</code> to find out about all available options for the timeline report. To find out details of a particular option, use <code>''show=option_name''</code> , e.g. <code>''name=timeline,show=off''</code> string. To learn about available report names, use <code>''name=show''</code> string.}}

*To convert the bsddb database on the fly to a .gramps xml file:

:<code>gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml</code>

* To generate a web site into an other locale (in German):

:<code>LANGUAGE=de_DE; LANG=de_DE.UTF-8 gramps -O 'Family Tree 1' -a report -p name=navwebpage,target=/../de </code>

*Finally, to start normal interactive session type:

:<code>gramps</code>

== Environment variables==

{{man warn|Warning|Gramps can take advantage of the following [[Gramps_and_Windows#Environmental_Variables|environment variables]] ('''Only change them if you know what are you doing.''')}}

===GRAMPSHOME===
* '''GRAMPSHOME''' - if set, [[Gramps_and_Windows#Setting_the_configuration_path|override default path]] to profile allowing user to use an external network drive to store data and all settings. For technically advanced users who run multiple versions of Gramps, setting a different $GRAMPSHOME is a way to avoid interference between the different versions in the Gramps [[Gramps_Glossary#user_directory|User Directory]]. It can also be used to configure Gramps to [[Run_Gramps_from_a_portable_drive|run from a portable drive]] or to prepare for a [[Installation|manual installation]]. The path can also be used to configure the path to a [[Gramps_for_Windows_with_MSYS2#Keep_your_GRAMPSHOME_separate|separate test Tree]] or [[Getting_started_with_Gramps_development|development Tree]].

For example <pre>GRAMPSHOME=$HOME/familytrees/paternal</pre>

===LANG, LANGUAGE, LC_MESSAGES, LC_TIME ===
* '''LANG''', '''LANGUAGE''', '''LC_MESSAGES''', and '''LC_TIME''' - are used by Gramps to determine which language file(s) should be loaded. See [https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap07.html locale] for a general discussion of '''LANG''', '''LC_MESSAGES''', and '''LC_TIME'''. Note that in addition to setting date formats (which are overridden in Gramps with Preferences settings) '''LC_TIME''' also sets the language used for words in dates like month and day names and ''in the context of dates'' words like ''about'', ''between'', and ''before''. '''LANGUAGE''' is a comma-separated list of language codes (''not locales'', though certain languages like pt_BR or cn_TW are regional variants) that sets a preference-ordered list of desired translations. It will override '''LANG''' but not '''LC_MESSAGES''' or '''LC_TIME'''.

{{man note|macOS|Because of the way launching with Finder works, the environment variables for the Gramps.app bundle are hard-coded in <code>Gramps.app/Contents/Resources/gramps_launcher.py</code>. If for some reason you need to change them, edit the file with TextEdit; be sure to save it back as plain text. See as well [[Run_GRAMPS_in_another_locale#Change_Mac_OS_X_application_defaults|setting locale]] for an alternative to using the '''LANG''' and '''LANGUAGE''' environment variables.}}

===GRAMPSI18N===
* [[Translating_Gramps#.24GRAMPSI18N_.28for_your_locale.29| $GRAMPSI18N (for your locale) ]] - The LANG assumes the Gramps translations are installed globally. If this is not the case, you need to [[Translating_Gramps#.24GRAMPSI18N_.28for_your_locale.29|give Gramps the directory]] where the translations will be found. This can be used to temporarily [[Howto:Change_the_language_of_reports|change the language for Reports]] being generated.

A translation is called <code>gramps.mo</code>, you can find it in Linux with the locate command. For example, if you have Swedish in directory <code>/home/me/gramps/mo/sv/gramps.mo</code>, you can direct Gramps there using:
GRAMPSI18N=/home/me/gramps/mo LC_ALL=C.UTF-8 LANG="sv" python3 gramps

===GRAMPSDIR===
* The environment variable GRAMPSDIR is the path to your [[Translating_Gramps#gramps.sh|Gramps directory]].

===GRAMPS_RESOURCES===
* The environment variable GRAMPS_RESOURCES is the path to Gramps built-in resources files. You should only change this if you are using Gramps from source code or a custom environment. An indicator that you need to set this variable is if you receive one of the following errors:
** ''Encoding error while parsing resource path''
** ''Failed to open resource file''
** ''Resource Path {invalid/path/to/resources} is invalid''
** ''Unable to determine resource path''

Example [[Linux:Build_from_source#Running_from_a_tarball_release|usage]]:
GRAMPS_RESOURCES=/home/username/gramps/branches/maintenance/gramps52/build/t PYTHONPATH=$GRAMPS_RESOURCES:$PYTHONPATH ./gramps

{{-}}
{{man index|Gramps 5.2 Wiki Manual - Keybindings|Gramps 5.2 Wiki Manual - User Directory|5.2}}
{{languages|Gramps_5.2_Wiki_Manual_-_Command_Line}}
{{grampsmanualcopyright}}

[[Category:Documentation]]

Team

2024-07-06T01:22:51Z

Awg: /* Package Maintainers */

= Administration =

;Treasurer: Brian Matherly
;Architect: Nick Hall
;Webmaster: Sam Manzi
;Gramps Web Lead: David Straub

= Package Maintainers =

;Apple MacOS: [[User:Jralls|John Ralls]]
;Microsoft Windows: Paul Culley - [[User:Prculley|wiki]] • [https://gramps.discourse.group/u/prculley Discourse]
;PortableApps: [https://portableapps.com/development/outdated John T. Haller]
;Debian (Linux): [[User:RossGammon|Ross Gammon]]
;Flatpak (Linux): [[User:OzarkShepherd|Scott Mackay]]
;Other Distributions: The following page might be useful if you want to know what version of Gramps is being distributed where, to contact the person/team, and see what patches they might have added: https://repology.org/project/gramps/packages

= Developers =
;Original author: Donald N. Allingham

;Contributors: [[Gramps_{{man version}}_Wiki_Manual_-_About|"About" credits for the Gramps {{man version}} version]]

= [[Portal:Translators|Translators]] =

{{Developers/box-header|''Existing Translations and name of active translator if any.''|Gramps translations}}

= See also =
* [[Contact]]

[[Category:Documentation]]
[[Category:Community/General]]

Addon:DynamicWeb report

2023-06-24T23:53:33Z

Awg:

{{Third-party plugin}}
{{man warn|Warning:|DynamicWeb may have performance issues for Family trees with more than 5000 people. 
* See '''[[#Optimizations_for_big_databases|Optimizations for big databases]]''' section below.}}

[[File:DynamicWeb-tree1.png|thumb|right|400px|DynamicWeb report, tree view]]
[[File:DynamicWeb-person-1.png|thumb|right|400px|DynamicWeb report, person view]]
[[File:DynamicWeb-index-1.png|thumb|right|400px|DynamicWeb report, persons index]]
[[File:DynamicWeb-surnames-1.png|thumb|right|400px|DynamicWeb report, surnames index]]
[[File:DynamicWeb-tree-2.png|thumb|right|400px|DynamicWeb report, tree view]]

The {{man label|Dynamic Web Report}} Addon for Gramps creates interactive web pages of the family tree database, and provides the user with options that allow a wide range of customization.

This addon is based on the [[Gramps_{{Version manual}}_Wiki_Manual_-_Reports_-_part_7#Narrated_Web_Site|Narrative Web Report]] native Gramps report.

== Usage ==

The report is available from the menu {{man menu|Reports > Web Pages > DynamicWeb}}

== Features ==

* Browsable and zoomable bi-directional family tree view.
**This graphical family tree can be printed using the SVG format.
**It can be zoomed (like google map) in order to print 20 generations or more.
**It can show descendants or ancestry (or both), as a tree or as concentric circles.
**Possibility to use the mouse or a context menu for navigation in the tree.
* A search form allows to perform a textual search for up to 3,000 data (individuals, places, sources, media) objects. [https://gramps.discourse.group/t/dwr-report-what-happened-to-media-search-field/1500/10 The Search is not shown when the object count is so high that it might impact the server performance.]
* Indexes can be sorted and filtered.
* Clickable pictures:
**The clickable regions correspond to the Gramps database media references regions. See: [http://belissent.github.io/GrampsDynamicWebReport/reports/report_001/media.html?mgid=O0010 demo]
* Based on client-side Javascript:
**No impact on server resources.
**The web pages can be browsed on a regular web site or from your local computer.
**The generated site is smaller, and contains less files (compared to static HTML pages).

== Demos ==

* [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/person.html?igid=I0044 Example using the default style]
* [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/tree_svg.html?igid=I0044 Example of graphical family tree] - [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/tree_svg.html?igid=I0044&svgshape=4&svgbk=0 example bis] - [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/tree_svg.html?igid=I0177&svgshape=0&svgbk=7 example ter]
* [http://belissent.github.io/GrampsDynamicWebReport/reports/report_001/person.html?igid=I0044 Example using another style] (‘Mainz’ style of the narrative web report)
* [http://belissent.github.io/GrampsDynamicWebReport/reports/report_001/media.html?mgid=O0010 Example of clickable picture]
* Indexes:
*: Surname index: [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/surnames.html?citn=0 Example 1] - [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/surnames.html?citn=1 Example 2]
*: Persons index: [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/persons.html?citi=0 Example 1] - [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/persons.html?cit1=1 Example 2]
*: Places index: [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/places.html?citp=0 Example 1] - [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/places.html?citp=1 Example 2]
*: Media index: [http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/medias.html Example]
* [http://belissent.github.io/GrampsDynamicWebReport/reports/report_004/person.html?igid=I0044 Example with minimal features] (without private data, notes, sources, addresses, gallery, places, families, events)

{{-}}
== Help for the report generation ==

[[File:DynamicWeb-conf-0.png|thumb|right|450px]]

=== Configuration before the report generation ===

The "Dynamic" aspect of this report is very handy when coming to the report configuration. Many configuration parameters could be modified ''after'' the report generation, directly on the Web site. These parameters, accessible to any user of the Web site, are detailed in the section [[#Configuration_by_the_Web_site_users|Configuration by the Web site users]].

The {{man label|Dynamic Web Report}} dialog window has nine tabs each are reviewed below.

==== Tab {{man label|Report}} ====

* {{man label|Destination}} (<code>~/yourhomedirectory/<Family Tree Name>_dynamicweb</code> by default):
*, The destination directory for the web files.
{{man warn|Files erased and overwritten|The report generation does not erase any file in the destination directory Only the files that need to be regenerated are overwritten.}}
* {{man label|Store web pages in archive}} (Disabled by default): This option could be used for 2 purposes:
** Generate an file that could be easily downloaded from the Web site:
**: The archive could be be in formats: <code>.tar.gz</code> or <code>.zip</code>
** Simplify the upload of the Web site to your internet provider:
**: If you have trouble transferring the files to an external web host, you can create a single gzip'd tar file to more easily upload the data. The large number of files and directories in this web output may make it difficult to transfer the files to an external web host. Gramps has the capability of saving all of your Narrative Web files in one compressed archive using the gzip and tar formats (casually known as a ‘tarball’). This single file can quickly be transferred to your server and uncompressed on the website host. '''Unfortunately not all web servers support saving web files in this way, so contact your hosting provider for more information.'''
* {{man label|Web site title}} (<code>My Family Tree</code> default): The title of the web site. You can enter a custom site title in this option. '''It is strongly suggested to change this from the default'''
* {{man label|Filter}}: Any person matching this filter who is not excluded due to the privacy rules, will be included in the output. Choose between:
** '''Entire Database''' (Default)
** Descendants of active person
** Descendant families of active person
** Ancestors of active person
** People with common ancestor with active person
* {{man label|Filter Person}} (active person by default): The center person for the report.
* {{man label|Name format}}: Select the format to display the names
* {{man label|Name format (short)}}: Select the format to display the names, in the graphical tree only.
* {{man label|Web site template}}: The report provides two built-in style sheets for you to choose from to determine the appearance or your web pages. Choose between [[http://belissent.github.io/GrampsDynamicWebReport/reports/report_000/index.html '''Default''']], or [[http://belissent.github.io/GrampsDynamicWebReport/reports/report_001/index.html '''Mainz''']].
* {{man label|Copyright:}} ('''Standard copyright''' by default): When creating a public a web site it is important to specify the copyright conditions under which you are publishing your data. International copyright law reserves all rights of your data to your discretion. You own the data and individuals must have your permission if they wish to reuse that data. In genealogical research sharing data with other researchers is a common practice. Other options include the Creative Commons licenses, offering a wide range of use restrictions or none at all. Learn more about the Creative Commons at http://creativecommons.org/

==== Tab {{man label|Privacy}} ====

{{man warn|Please note that compliance with privacy laws and individuals' privacy concerns is as a researcher your responsibility.|The Gramps project cannot be held responsible for privacy law compliance or other privacy issues.}}

Privacy of personal information is an important issue. Gramps provides tools and settings that give you control over the privacy of your data.

* {{man label|Include data marked private}} (disabled by default): Whether to include private objects. If your intention is to provide a complete record of your research, checking this box will include all entries marked '''private''' along with the rest of your database.
* {{man label|Export notes}} (Enabled by default): Whether to include notes.
* {{man label|Export sources}} (Enabled by default): Whether to include sources.
* {{man label|Export addresses}} (Enabled by default): Whether to include addresses.
* {{man label|Living People}}: How to handle living people. You can control the display of sensitive information based on whether or not an individual is currently alive. However, since Gramps is a research tool, it is likely that there are individuals with no known date of death in your database. To deduce if an individual is ''possibly still alive'' Gramps employs an algorithm that compares death dates, birth dates, baptism/christening dates, death dates of ancestors and birth dates of ancestors. The algorithm assumes that each individual is ''possibly still alive'' unless the cross-referenced dates make the individual's ''possibility of being alive'' unlikely.
**'''Exclude''' (Default): Excludes all information of all individuals who are ''[[Gramps_{{Version manual}}_Wiki_Manual_-_Probably_Alive|possibly still alive]]''
**'''Include Last Name Only'''
**'''Include Full Name Only'''
**'''Include''': Include all information of all individuals even if they are ''possibly still alive''
* {{man label|Years from death to consider living}} (<code>30</code> by default): This option is inactive if the "Living People" option is set to '''Include'''. {{man warn|Some countries have laws that specify a certain number of years after death before an individual's information can be published. Here you can specify the number of years after death needed to comply with such laws.}}

==== Tab {{man label|Options}} ====

* {{man label|Include repository pages}} (disabled by default)
* {{man label|Include images and media}} (enabled by default)
* {{man label|Images and media}}: Three possibilities are proposed for integrating media in the Web site. See '''[[#Media_files_organization|Media files organization]]''' section below.
* {{man label|Print the notes type}} (enabled by default)
[[File:DynamicWeb-map-1.png|right|400px]]
* {{man label|Print place pages}} (enabled by default)
* {{man label|Include Place map on Place Pages}} (disabled by default): Whether to include a place map on the Place Pages, where Latitude/ Longitude are available.
* {{man label|Include a map in the individuals and family pages}} (disabled by default) Whether to include a place map on the pages, where Latitude/ Longitude are available.
* {{man label|Map Service}} (Google by default): Choose your choice of map service for creating the Place Map Pages
** '''Google''' (default)
** OpenStreetMap
* {{man label|Google map API key}}: The access to the Google Maps API requires an application key. See [[https://developers.google.com/maps/documentation/javascript/get-api-key Google Maps documentation]]

==== Tab {{man label|Advanced}} ====

* {{man label|Character set encoding}}: The encoding to be used for the web files
** '''Unicode UTF-8 (recommended)''' (Default)
** ISO-8859-1
** ISO-8859-2
** ISO-8859-3
** ISO-8859-4
** ISO-8859-5
** ISO-8859-6
** ISO-8859-7
** ISO-8859-8
** ISO-8859-9
** ISO-8859-10
** ISO-8859-13
** ISO-8859-14
** ISO-8859-15
** koi8_r
* {{man label|Include family pages}} (disabled by default)
* {{man label|Include GENDEX file (/gendex.txt)}} (disabled by default): This option creates a GENDEX file placed at the top of the website. You can see sites which support this format and read more about it at the [http://en.wikipedia.org/wiki/GENDEX GENDEX Wikipedia article])(checkbox unchecked by default)
* {{man label|Enable page configuration}} (enabled by default): This enables the configuration after report generation, see '''[[##Configuration_by_the_Web_site_users|configuration by the Web site users]]''' section below. This configuration is accessed with the cogwheel button on the pages top-right. It allows to configure the layout without having to export the report again. It is very helpful to find the convenient layout without re-exporting the report each time.
* {{man label|Include half and/ or step-siblings on the individual pages}}, {{man label|Use tabbed panels instead of sections}}, {{man label|Show last modification time}}, {{man label|Insert sources author in the sources title}}, {{man label|Suppress Gramps ID}}: See the '''[[##Configuration_by_the_Web_site_users|help for the configuration by the Web site users]]''' section below.

==== Tab {{man label|Indexes}} ====

For the options below, see the '''[[#Configuration_by_the_Web_site_users|help for the configuration after report generation]]''' section.

* {{man label|Default format for the surnames index}}
* {{man label|Default format for the persons index}}
* {{man label|Default format for the families index}}
* {{man label|Default format for the sources index}}
* {{man label|Default format for the places index}}
* {{man label|Include dates columns on the index pages}}
* {{man label|Include a column for partners on the index pages}}
* {{man label|Include a column for parents on the index pages}}
* {{man label|Include a column for media path on the index pages}}
* {{man label|Include references in indexes}}

* {{man label|Default number of entries in the indexes}} (<code>10</code> by default): 
The number of entries per page in the index tables is memorized by the browser for each user and each table.
This value is the initial default value before the users select their own preference.

==== Tab {{man label|Pages}} ====

* '''''Header / footer''''': The Gramps notes used as header / footer could include special features, described in the '''[[#Tab_Custom_pages|custom pages]]''' section below.
* '''''Brand name / icon''''': The gramps note used could embed an image or any other special field described in the '''[[#Tab_Custom_pages|custom pages]]''' section below. When no brand name/icon is used, the Gramps icon is used. Specify an empty note for disabling the Gramps icon.

==== Tab {{man label|Trees}} ====

Most of these configuration parameters could also be tuned after report generation, see '''[[#Configuration_by_the_Web_site_users|configuration by the Web site users]]''' section.

*{{man label|Colors}}:
*: The gradient colors are used for all gradients (based on generation, time period, or age).
*: The gender colors are set in the Gramps Prefrences (in Edit menu).
*: The {{man label|Color scheme classic view}} : It is hardcoded in Gramps. The colors are those used in the Chart view, for the "Descendant Fan", when configuring background to ''Color scheme classic view''
*: The {{man label|Color scheme classic report}}: Same as ''Color scheme classic view''.
*{{man label|Duplicates}}: For people appearing several times in the tree (for example, when both parents share a common ancestor).

==== Tab {{man label|Custom pages}} ====

It is possible to add custom pages built from a note. These pages could be used for:
* A customized home page
* A contact page
* A download page
* Etc.

These pages have the following options:
* {{man label|Title for the custom page}}
* {{man label|Menu for the custom page}} (enabled by default): allows to have a page without any menu.
* {{man label|Note for the custom page}}: This note could include
** Text formating
** Links to other Gramps objects
** External HTTP links
** Relative HTTP links: They are given as regular HTTP links, but in the form <code>relative://<relative path></code>
** Special fields: These fields are given as text in the note and are replaced in the generated report.
**: Export date: <code>__EXPORT_DATE__</code>
**: GRAMPS homepage: <code>__GRAMPS_HOMEPAGE__</code>
**: GRAMPS version: <code>__GRAMPS_VERSION__</code>
**: Number of families: <code>__NB_FAMILIES__</code>
**: Number of persons: <code>__NB_INDIVIDUALS__</code>
**: Number of media objects: <code>__NB_MEDIA__</code>
**: Number of sources: <code>__NB_SOURCES__</code>
**: Number of repositories: <code>__NB_REPOSITORIES__</code>
**: Number of places: <code>__NB_PLACES__</code>
**: Search form: <code>__SEARCH_FORM__</code>
**: Embedded image: <code>__MEDIA_<Gramps ID>__</code> (for example: <code>__MEDIA_O0011__</code>)
**: Embedded image thumbnail: <code>__THUMB_<Gramps ID>__</code>

==== Tab {{man label|Pages selection}} ====

Allows to enable, disable and order pages.

=== Media files organization ===

There 3 possibilities for using the media files in the report:
# '''''Copy, rename files with an internal Gramps identifier''''': The media files are copied at every report generation, in the directory "image", and their names and changed into a unique obfuscated name. This behavior is identical to the [[Gramps_{{Version manual}}_Wiki_Manual_-_Reports_-_part_7#Narrated_Web_Site|Narrative Web Site report]].
* '''''Copy, keep file names unchanged''''': The media files are copied at every report generation, in the directory "image", but their names kept intact. The files that are in the same directory are copied into the same directory. The directory names are replaced by unique obfuscated names.
* '''''Do not copy, reference existing files''''': The media files are not copied. The relative path from the generated report to the media files is used. Therefore, the relative path from Web report to the media object shall stay the same between local computer and the web server where the web site is uploaded. '''On Windows''': The report shall be generated on the same disk drive where the media files are located.
*: For example:
*:: The media files are located in the directory: <code>C:\Users\Mewtwo\genealogy\media\</code>
*:: The report is generated in the directory: <code>C:\Users\Mewtwo\genealogy\reports\DynamicWeb</code>
*:: Then the relative path is: <code>..\..\media</code>
*:: Therefore, on the web server, the media files and report shall be located in something like: <code>http://my.web.site.com/path/to/report/media</code> and <code>http://my.web.site.com/path/to/report/reports/DynamicWeb</code>

=== Optimizations for big databases ===

The report was tested with a [[Gramps_Performance#Genealogical_datasets|database with over 120,000 people]] without blocking issue.

Nevertheless, some users could have performance issues.

The technology used for this report (client-side Javascript) is not designed for managing big amounts of data.

This could lead to performance issues, for databases over 5000 people, when the configuration is not properly set. The following tunings could be used:
* The optional index columns should be discarded
* The indexes should be displayed as lists and not as tables

Another possibility is to use only a portion of the Family Tree database. Generating the report with a smaller filter enhances the performances and provides a smoother experience for the Web site users.

{{man warn|Do you really want to use the entire Family Tree database ?|Be aware that if you select the '''Entire Database''' filter option for your Family Tree database that very big files will be generated (depending on the size of your Family Tree database). It is recommended to start with a smaller filter (for example: ancestors of a certain person) to simplify the output while you learn about the Dynamic Web report.}}

Moreover, when rendering large datasets, the report disables some fancy features for better performances.

Then again, exporting a portion of the database helps.

== Help for the Web site users ==

{{-}}
=== Configuration by the Web site users ===

[[File:DynamicWeb-conf-1.png|right|thumb|450px]]

Some configuration parameters are accessible after the report generation, using the cogwheel button at the top-right of the pages.

This cogwheel button is enabled in the {{man label|Advanced}} tab, described [[#Tab_Advanced|above]]'''.

* {{man label|Use a table format for the index}}, for the {{man label|surnames}}, {{man label|persons}}, {{man label|families}}, {{man label|sources}} or {{man label|places}} indexes:
**When enabled, the indexes are shown as tables. These tables could be sorted by any column, and filtered.
**When disabled, the indexes are shown as lists. When possible, these lists are indexed alphabetically. The lists could also be sorted by name, date, etc. depending on the type of data shown.
* {{man label|Include columns on the index pages}} for {{man label|dates}}, {{man label|partners}}, {{man label|parents}}, {{man label|media path}}:
**Includes the corresponding columns in the indexes, '''when the indexes are shown as lists'''.
* {{man label|Include references in indexes}}:
**When enabled, the references between objects are shown in the indexes, '''when they are shown as lists'''..
**For example, objects citing a source are shown in the sources index.
* {{man label|Include Place map on Place Pages}}:
**Whether to include a place map on the Place Pages, where Latitude/ Longitude are available.
* {{man label|Include a map in the individuals and family pages}}:
**Whether to include a place map on the pages, where Latitude/ Longitude are available.
* {{man label|Include half and/ or step-siblings on the individual pages}}
* {{man label|Insert sources author in the sources title}}:
**The source author is always shown with the source title. This covers the case when source titles are too generic, like ''"baptize registry"'' for example.
* {{man label|Use tabbed panels instead of sections}}:
**Changes the layout of the pages. With tabbed panels, the pages are more compact. With sections, all the data is visible at the same time (no need to switch between tabs).
**Note: the sections are collapsible.
* {{man label|Show last modification time}}:
**Adds a modification date/time in the page footer.
* {{man label|Suppress Gramps ID}}:
**Allows to hide the Gramps ID. The Gramps ID is an identifier for each object stored in the Family Tree database. It could be used to precisely identify an element (person, family, source, etc.).

* {{man label|Restore default settings}}:
**Restores the settings used when the report was generated.
**This button also resets the user preferences, like the number of items per pages in the index tables.

{{-}}

=== Graphical tree options ===

[[File:DynamicWeb-conf-2.png|right|thumb|450px]]

The Graphical aspect of the tree could be modified, depending on users preferences.
* {{man label|SVG tree graph type}}
** {{man label|Ascending tree}}: Only ancestors of the chosen person are shown
** {{man label|Descending tree}}: Only descendants of the chosen person are shown
** {{man label|Descending tree with spouses}}: Descendants of the chosen person are shown, along with their spouses
** {{man label|Ascending and descending tree}}: Ancestors and descendants of the chosen person are shown
** {{man label|Ascending and descending tree with spouses}}: Ancestors and descendants of the chosen person are shown, along with their spouses
* {{man label|SVG tree graph shape}}
** {{man label|Vertical (↓)}}: Ancestors on the top of the page, descendants on the bottom of the page
** {{man label|Vertical (↑)}}: Ancestors on the bottom of the page, descendants on the top of the page
** {{man label|Horizontal (→)}}: Ancestors on the left of the page, descendants on the right of the page
** {{man label|Horizontal (←)}}: Ancestors on the right of the page, descendants on the left of the page
** {{man label|Full Circle}}: Chosen person is in the center opf the page
** {{man label|Half Circle}}: Chosen person is in the bottom-center of the page. '''This graph shape is not available when displaying both ancestors and descendants'''.
** {{man label|Quadrant}}: Chosen person is in the bottom-left of the page. '''This graph shape is not available when displaying both ancestors and descendants'''.
* {{man label|SVG tree parents distribution}}, {{man label|SVG tree children distribution}}
** {{man label|Size proportional to number}}: The size allocated to each individual depends on how many ancestors/descendants there are. This improves the readability.
** {{man label|Homogeneous distribution}}: The size is allocated homogeneously to each individual.
* {{man label|Background}}
* {{man label|Ancestors}}: Number of ancestors generations.
* {{man label|Descendants}}: Number of descendants generations.
* {{man label|Show duplicates}}: Outlines the people appearing several times in the tree (for example, when both parents share a common ancestor).
* {{man label|Restore default settings}}:Restores the settings used when the report was generated.

{{-}}

=== Graphical tree navigation ===

[[File:DynamicWeb-tree-3.png|thumb|right|450px|Tree view example]]

* Use the <code>mousewheel</code> to zoom in and out.
* Use the mouse <code>drag and drop</code> to move the graph.
* Use the mouse <code>left-click</code> to center the graph on a person.
* Use the mouse <code>right-click</code> to open a context menu. This menu gives access to:
** The person page,
** The persons related to this person (parents, children, siblings, souses).
* Use <code>Shift + left-click</code> to go to the person page (same as using the context menu from the <code>right-click</code>).

{{-}}

=== Map navigation ===

[[File:DynamicWeb-map-2.png|thumb|right|450px|Map example]]

* The mouse <code>left-click</code> expands the map full-screen (or restores it back).

{{-}}

== Issues ==

Issues and features requests are managed in the [[Using_the_bug_tracker|Gramps bug tracking system]]

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Reports]]