Difference between revisions of "Gramps 4.1 Wiki Manual - Reports - part 2"

From Gramps
Jump to: navigation, search
(The Substitution Keys)
m (Protected "Gramps 4.1 Wiki Manual - Reports - part 2": outdated user manual ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite)))
 
(40 intermediate revisions by the same user not shown)
Line 47: Line 47:
  
 
== The Substitution Keys ==
 
== The Substitution Keys ==
 
 
{| {{prettytable}}
 
{| {{prettytable}}
 
|-
 
|-
Line 104: Line 103:
  
 
=== Default displayed formats ===
 
=== Default displayed formats ===
{|
+
{| {{prettytable}}
 
|-
 
|-
|$n $s
+
!$n $s
 
|Names will be displayed as set in 'Name format:' on the Display tab in Gramps preferences
 
|Names will be displayed as set in 'Name format:' on the Display tab in Gramps preferences
 
|-
 
|-
|$B $D $M $V
+
!$B $D $M $V
 
|Places will display the Place title by default
 
|Places will display the Place title by default
 
|-
 
|-
|$b $d $m $v $T
+
!$b $d $m $v $T
 
|Dates will be displayed as set in 'Date format:' on the Display tab in Gramps preferences
 
|Dates will be displayed as set in 'Date format:' on the Display tab in Gramps preferences
 
|-
 
|-
|$e $t
+
!$e $t
 
|Events will display the description by default
 
|Events will display the description by default
 
|}
 
|}
  
 
----
 
 
=== Deprecated variables ===
 
=== Deprecated variables ===
  
Line 188: Line 185:
 
Format strings are used to display names and dates differently than those assigned under Gramps Preferences. Here is the syntax for a format string:
 
Format strings are used to display names and dates differently than those assigned under Gramps Preferences. Here is the syntax for a format string:
  
$''<span style="background: #c0c0c0">key</span>''(format string)
+
$''{{man label|key}}''(format string)<br />
    where: ''<span style="background: #c0c0c0">key</span>'' is one of the following characters: 'nsijbmBMdvDVauet'
+
where: ''{{man label|key}}'' is one of the following characters: 'nsijbmBMdvDVauet'
  
 
A format string is any text, separators or format codes (defined below) to display information about the person.
 
A format string is any text, separators or format codes (defined below) to display information about the person.
Line 195: Line 192:
 
=== Formatting names ===
 
=== Formatting names ===
  
For names ($n $s) you may use the following formatting codes to display the name differently.
+
For names <code>($n $s)</code> you may use the following formatting codes to display the name differently.
  
{|
+
{| {{prettytable}}
 
|-
 
|-
|t
+
!t
 
|Title
 
|Title
|
+
!f
|f
 
 
|Given name
 
|Given name
 
|-
 
|-
|x
+
!x
 
|Common name. Call name if existing, otherwise first first name
 
|Common name. Call name if existing, otherwise first first name
|
+
!c
|c
 
 
|Call name
 
|Call name
 
|-
 
|-
|n
+
!n
 
|Nick name
 
|Nick name
|
+
!s
|s
 
 
|Suffix
 
|Suffix
 
|-
 
|-
|l
+
!l
 
|Surname
 
|Surname
|
+
!g
|g
 
 
|Family nickname
 
|Family nickname
 
|}
 
|}
  
These codes can be uppercased to uppercase the result.
+
These codes can be upper-cased to uppercase the result.
  
{|
+
For example:
 +
{| {{prettytable}}
 
|-
 
|-
|Example code
+
!Formatting code
|Displays
+
!Displays
 
|-
 
|-
 
|<pre>$n(L, f) ($n(c)), $n(L, f){ ($n(c))}
 
|<pre>$n(L, f) ($n(c)), $n(L, f){ ($n(c))}
Line 236: Line 230:
 
Janice Ann Adams</pre>
 
Janice Ann Adams</pre>
 
|}
 
|}
 +
{{man note|Note:|If you want to print a character 'c' within the format string (or any one of the other format codes), you will need to first add a <code>'&#92;'</code> in front of it. See [[#Control Variables|Control Variables]] for more.}}
  
 
+
{{man note|Note:|The curly brackets <code>{ }</code> are used to hide information. Here it is used around <code>' ($n(c))'</code> to not display <code>' ()'</code> if the person does not have a call name. See [[#Grouping|Grouping]] for more.}}
<blockquote>Note:
 
If you want to print a character 'c' within the format string (or any one of the other format codes), you will need to first add a '&#92;' in front of it. See [[#Control Variables|Control Variables]] for more.</blockquote>
 
 
 
<blockquote>Note:
 
the curly brackets { } are used to hide information. Here it is used around ' ($n(c))' to not display ' ()' if the person does not have a call name. See [[#Grouping|Grouping]] for more.</blockquote>
 
 
 
----
 
  
 
=== Formatting Dates ===
 
=== Formatting Dates ===
 +
For all of the date variables <code>($b $d $m $v)</code> you may use the following formatting codes:
  
For all of the date variables ($b $d $m $v) you may use the following formatting codes:
+
{| {{prettytable}}
 
 
{|
 
 
|-
 
|-
|yyyy
+
!yyyy
 
|The year as a four digit number
 
|The year as a four digit number
|
+
!yyy
|yyy
 
 
|The year, with a minimum of three digits
 
|The year, with a minimum of three digits
 
|-
 
|-
|yy
+
!yy
 
|The year, from 00 to 99
 
|The year, from 00 to 99
|
+
!y
|y
 
 
|The year, from 0 to 99
 
|The year, from 0 to 99
 
|-
 
|-
|mmmm<BR>
+
!mmmm<BR>
MMMM
+
'''MMMM'''
 
|The full name of the month<BR>
 
|The full name of the month<BR>
 
The full name IN CAPS
 
The full name IN CAPS
|
+
!mmm<BR>
|mmm<BR>
+
'''MMM'''
MMM
 
 
|The abbreviated name of the month<BR>
 
|The abbreviated name of the month<BR>
 
The abbreviated name IN CAPS
 
The abbreviated name IN CAPS
 
|-
 
|-
|mm
+
!mm
 
|The month, from 00 to 12
 
|The month, from 00 to 12
|
+
!m
|m
 
 
|The month, from 0 to 12
 
|The month, from 0 to 12
 
|-
 
|-
|dd
+
!dd
 
|The day, from 00 to 31
 
|The day, from 00 to 31
|
+
!d
|d
 
 
|The day, from 0 to 31
 
|The day, from 0 to 31
 
|-
 
|-
|o
+
!o
 
|The date type (modifier)
 
|The date type (modifier)
|
+
!
|
 
 
|
 
|
 
|}
 
|}
  
{|
+
For example:
 +
{| {{prettytable}}
 
|-
 
|-
|Example code
+
!Formatting code
|displays
+
!displays
 
|-
 
|-
 
|<pre>$b(mmm-dd yy)
 
|<pre>$b(mmm-dd yy)
Line 306: Line 288:
 
|}
 
|}
  
{{man note| For date types (modifier) |Only "Before", "After", and "About" are supported at this time.  all others will not display anything.<BR>
+
{{man warn| For date types (modifier) |Only "Before", "After", and "About" are supported at this time.  all others will not display anything.<BR>And for date span and date ranges, only the starting (first) date is displayed.}}
And for date span and date ranges, only the starting (first) date is displayed.}}
 
 
 
----
 
  
 
=== Formatting Places ===
 
=== Formatting Places ===
 +
For all of the place variables <code>($B $D $M $V)</code> you may use the following formatting codes:
  
For all of the place variables ($B $D $M $V) you may use the following formatting codes:
+
{| {{prettytable}}
 
 
{|
 
 
|-
 
|-
|e
+
!e
 
|Street
 
|Street
 
|
 
|
|l
+
!l
 
|Locality
 
|Locality
 
|-
 
|-
|c
+
!c
 
|City
 
|City
 
|
 
|
|u
+
!u
 
|County
 
|County
 
|-
 
|-
|s
+
!s
 
|State
 
|State
 
|
 
|
|p
+
!p
 
|Postal Code
 
|Postal Code
 
|-
 
|-
|n
+
!n
 
|Country
 
|Country
 
|
 
|
|t
+
!t
 
|Title
 
|Title
 
|-
 
|-
|x
+
!x
 
|Longitude
 
|Longitude
 
|
 
|
|y
+
!y
 
|Latitude
 
|Latitude
 
|}
 
|}
These codes can be uppercased to uppercase the result.  
+
These codes can be upper-cased to uppercase the result.  
  
{|
+
For example:
 +
{| {{prettytable}}
 
|-
 
|-
|Example code
+
!Formatting code
|displays
+
!displays
 
|-
 
|-
 
|<pre>$B
 
|<pre>$B
Line 359: Line 338:
 
Carmel, IN, USA</pre>
 
Carmel, IN, USA</pre>
 
|}
 
|}
 
----
 
  
 
=== Rules for format strings. ===
 
=== Rules for format strings. ===
  
{|
+
* Anything will print inside a format string
|-
+
* You need to use [[#Control Variables|Control Variables]] to display things like <code>')'</code> and format codes
|1
+
* Separators can be within format strings.
|Anything will print inside a format string
+
* At least ONE format code has to display something for the ENTIRE format string to display
|-
 
|1a
 
|you will have to use [[#Control Variables|Control Variables]] to display things like ')' and format codes
 
|-
 
|2
 
|Separators can be within format strings.
 
|-
 
|3
 
|At least ONE format code has to display something for the ENTIRE format string to display
 
|}
 
 
 
----
 
  
=== Examples ===
+
For examples:
 
+
{| {{prettytable}}
{|
 
 
|-
 
|-
|code
+
!Formatting code
|gives
+
!displays
 
|-
 
|-
 
|<pre>$n(f l)
 
|<pre>$n(f l)
Line 392: Line 356:
 
{d. $d $D</pre>
 
{d. $d $D</pre>
 
|<pre>Edwin Michael Smith
 
|<pre>Edwin Michael Smith
b. 1961-05-24 at San Jose, Santa Clara Co., CA</pre>The person is still alive (or has no information present) so the line was removed.
+
b. 1961-05-24 at San Jose, Santa Clara Co., CA</pre>{{man label|The person is still alive (or has no information present) so the line was removed.}}
 
|}
 
|}
 
 
  
 
== Control Variables ==
 
== Control Variables ==
Line 403: Line 365:
 
For example the dollar character '$' is used to note the start of a variable. If you wish to print a dollar character you would use a control character like '&#92;$'
 
For example the dollar character '$' is used to note the start of a variable. If you wish to print a dollar character you would use a control character like '&#92;$'
  
Control Variables
+
{| {{prettytable}}
 
+
!Control Variables
{|
+
!Result
 +
|-
 +
!&#92;$
 +
|Displays a single <code>'$'</code>
 +
|-
 +
!&#92;&#92;
 +
|Displays a single <code>'&#92;'</code>
 +
|-
 +
!&#92;(
 +
|Displays a single <code>'('</code>
 +
|-
 +
!&#92;)
 +
|Displays a single <code>')'</code>
 
|-
 
|-
|&#92;$
+
!&#92;{
|Displays a single '$'
+
|Displays a single <code>'{'</code>
|
 
|&#92;&#92;
 
|Displays a single '&#92;'
 
 
|-
 
|-
|&#92;(
+
!&#92;}
|Displays a single '('
+
|Displays a single <code>'}'</code>
|
 
|&#92;)
 
|Displays a single ')'
 
 
|-
 
|-
|&#92;{
+
!&#92;<
|Displays a single '{'
+
|Displays a single <code>'<'</code>
|
 
|&#92;}
 
|Displays a single '}'
 
 
|-
 
|-
|&#92;<
+
!&#92;>
|Displays a single '<'
+
|Displays a single <code>'>'</code>
|
 
|&#92;>
 
|Displays a single '>'
 
 
|}
 
|}
  
Basically anything that comes after a '&#92;' will be printed.
+
Basically anything that comes after a <code>'&#92;'</code> will be printed.
  
----
+
{{man note|Note:|When you are inside a format string, you may need to use this to display a character that would normally be a format code.}}
Note:
 
When you are inside a format string, you may need to use this to display a character that would normally be a format code.
 
  
{|
+
For example:
 +
{| {{prettytable}}
 
|-
 
|-
|Example:
+
!Formatting code:
|would give
+
!displays
 
|-
 
|-
 
|<pre>$b(m hi mom)
 
|<pre>$b(m hi mom)
 
$b(m hi \mo\m)</pre>
 
$b(m hi \mo\m)</pre>
 
|<pre>5 hi 5o5
 
|<pre>5 hi 5o5
5 hi mom</pre>
+
5 hi mom</pre>{{man label|As this person was born on the fifth month.}}
 
|}
 
|}
 
as this person was born on the fifth month.
 
  
 
== Grouping ==
 
== Grouping ==
  
There are instances where you do not want certain text to be displayed. Take the example:
+
There are instances where you do not want certain text to be displayed.  
  
{|
+
Take the example:
 +
{| {{prettytable}}
 
|-
 
|-
|Code
+
!Formatting Code
|Only date is known
+
!Only date is known
|Only place is known
+
!Only place is known
 
|-
 
|-
|<pre>died on $d at $D</pre>
+
|<code>died on $d at $D</code>
|<pre>died on 1975-06-26 at </pre>  
+
|<code>died on 1975-06-26 at</code>
|<pre>died on at Reno, Washoe Co., NV</pre>
+
|<code>died on at Reno, Washoe Co., NV<code>
 
|-
 
|-
| colspan="3"|Neither of these are very acceptable.
+
|}
 +
Neither of these displayed results are very acceptable.
 +
 
 +
But with groups (denoted by '''&#123;&#125;'''), you can optionally print information if a variable within contains information.
 +
 
 +
{| {{prettytable}}
 
|-
 
|-
| colspan="3"|But with groups (denoted by {}), you can optionally print information if a variable within contains information.
+
!Formatting Code
 +
!Only date is known
 +
!Only place is known
 
|-
 
|-
| colspan="3"|For example:
+
|<code>died{ on $d}{ at $D}</code>
|-
+
|<code>died on 1975-06-26</code>
|Code
+
|<code>died at Reno, Washoe Co., NV</code>
|Only date is known
 
|Only place is known
 
|-
 
|<pre>died{ on $d}{ at $D}</pre>
 
|<pre>died on 1975-06-26</pre>
 
|<pre>died at Reno, Washoe Co., NV</pre>
 
 
|}
 
|}
 +
Which is a more preferable displayed result than in the first example.
  
which is what we want.
 
 
----
 
 
=== Rules for groups ===
 
=== Rules for groups ===
  
Line 489: Line 448:
 
Groups can also be nested. If this happens (like below), the outer group will only display if there is at least one variable that displays something within the outer group or any of the sub groups.
 
Groups can also be nested. If this happens (like below), the outer group will only display if there is at least one variable that displays something within the outer group or any of the sub groups.
  
Groups can also be used to remove text.  If you wish to not display the entire line, '-' at the start of a line will remove the entire line from the display if the above rule is true.
+
Groups can also be used to remove text.  If you wish to not display the entire line, <code>'-'</code> at the start of a line will remove the entire line from the display if the above rule is true.
 
 
If you do not wish to have the display code above (for death information) displayed (the person is alive, or you do not yet know the information), modify the code to look like
 
<pre>-{died{ on $d}{ at $D}</pre>
 
  
----
+
If you do not wish to have the display code above (for death information) displayed (the person is alive, or you do not yet know the information), modify the code to look like:
 +
* <code>-{died{ on $d}{ at $D}</code>
  
 
=== Examples: ===
 
=== Examples: ===
 
+
This will hide <code>'('</code> and <code>')'</code> if the divorce information is not known (or still married).
This will hide '(' and ')' if the divorce information is not known (or still married).
+
* <code>m. $m $M {- ($v(yyyy))</code>
 
 
<pre>m. $m $M {- ($v(yyyy))</pre>
 
 
 
  
 
Only display some spouse information if married or remove the entire line if never married:
 
Only display some spouse information if married or remove the entire line if never married:
<pre>{$s $m(yyyy) {- $v(\(yyyy\))}}</pre>
+
* <code>{$s $m(yyyy) {- $v(\(yyyy\))}}</code>
  
 
== Attributes ==
 
== Attributes ==
 +
Attributes do not have a format string. Instead the attribute name is placed inside <code>[]</code>. Here is the syntax for an attribute:
  
Attributes do not have a format string. Instead the attribute name is placed inside []. Here is the syntax for an attribute:
+
$''{{man label|key}}''[attribute name]<br />
 +
where: ''{{man label|key}}'' is one of the following characters: 'au'
  
$''<span style="background: #c0c0c0">key</span>''[attribute name] where: ''<span style="background: #c0c0c0">key</span>'' is one of the following characters: 'au'
+
For example:
 
+
{| {{prettytable}}
Example:
+
!Formatting code
 
+
!displays
{|
 
 
|-
 
|-
 
|<pre>$a[Profession]
 
|<pre>$a[Profession]
Line 524: Line 479:
 
|}
 
|}
  
 
----
 
 
== Events ==
 
== Events ==
  
Events have the same starting structure as attributes, $e or $t and the event name in [] but events have an extra format string after the name to display the description, date, place, id, and attributes associated with it. Each of these items can be displayed with a , a 'n', 'd', 'D', 'i', and 'a' respectively in the format string. Here is the syntax for an event:
+
Events have the same starting structure as attributes, <code>$e</code> or <code>$t</code> and the event name in <code>[]</code> but events have an extra format string after the name to display the description, date, place, id, and attributes associated with it. Each of these items can be displayed with a , a 'n', 'd', 'D', 'i', and 'a' respectively in the format string. Here is the syntax for an event:
  
$''<span style="background: #c0c0c0">key</span>''[attribute name](format string) where: ''<span style="background: #c0c0c0">key</span>'' is one of the following characters: 'et'
+
$''{{man label|key}}''[attribute name](format string)<br />
 +
where: ''{{man label|key}}'' is one of the following characters: 'et'
  
 
=== Event format strings ===
 
=== Event format strings ===
Line 536: Line 490:
 
The Event format string is used to display information about the event. Here are the format codes to display parts of the event:
 
The Event format string is used to display information about the event. Here are the format codes to display parts of the event:
  
{|
+
{| {{prettytable}}
 +
!Formatting code
 +
!displays
 +
!
 +
!Formatting code
 +
!displays
 
|-
 
|-
|n
+
!n
 
|Description
 
|Description
 
|
 
|
|i
+
!i
 
|Event ID
 
|Event ID
 
|-
 
|-
|d
+
!d
 
|Event Date&#42;
 
|Event Date&#42;
 
|
 
|
|D
+
!D
 
|Event Place&#42;
 
|Event Place&#42;
 
|-
 
|-
|a
+
!a
 
|An attributes for the event&#42;&#42;
 
|An attributes for the event&#42;&#42;
 
|
 
|
Line 561: Line 520:
 
&#42;&#42;Attribute needs to have the attribute name in [] and are formatted as above.
 
&#42;&#42;Attribute needs to have the attribute name in [] and are formatted as above.
  
Example:
+
For example:
 
+
{| {{prettytable}}
{|
+
!Formatting code
 +
!displays
 
|-
 
|-
 
|<pre>$e[First Communion](d(yyyy-mm-d))
 
|<pre>$e[First Communion](d(yyyy-mm-d))
Line 572: Line 532:
 
2007 05/23 Grandmothers house</pre>
 
2007 05/23 Grandmothers house</pre>
 
|}
 
|}
 
  
 
And:
 
And:
 
+
{| {{prettytable}}
{|
+
!Formatting code
 +
!
 +
!displays
 
|-
 
|-
 
|<pre>$b(yyyy-Mmm-dd)
 
|<pre>$b(yyyy-Mmm-dd)
Line 585: Line 546:
 
|}
 
|}
  
 +
=== Notes for attributes and events: ===
  
----
+
Attribute and event names are mandatory. <code>'$a'</code> or <code>'$a[]'</code> will not display anything.
  
=== Notes for attributes and events: ===
+
Attributes and event names may have special characters within them. Most notably <code>']'</code> and <code>')'</code>. If this is the case, you will need to use [[#Control Variables|Control Variables]]
 
 
{|
 
|-
 
|1
 
|Attribute and event names are mandatory. '$a' or '$a[]' will not display anything.
 
|-
 
|2
 
|Attributes and event names may have special characters within them. Most notably ']' and ')'. If this is the case, you will need to use [[#Control Variables|Control Variables]]
 
|}
 
  
 
== Separators ==
 
== Separators ==
  
Separators are special 'text only' groups inside '&lt;' and '&gt;' that conditionally display a separator (like ', ' or ' - ') between two groups, variables, format codes or text.
+
Separators are special 'text only' groups inside <code>'&lt;'</code> and <code>'&gt;'</code> that conditionally display a separator (like <code>', '</code> or <code>' - '</code>) between two groups, variables, format codes or text.
  
 
Separators are displayed conditionally depending on these rules:
 
Separators are displayed conditionally depending on these rules:
 +
* A variable that does '''not''' display anything will remove itself and a separator that is to the left of it from the display line only.
 +
* If there is not a separator to the left, the same variable will remove itself and a separator that is to the right of it from the displayed line.
 +
* If there are two separators together, the left one will be removed from the display line and the right is kept.
 +
* Separators at the start or end of the display line (or format strings) are removed.
  
# A variable that does '''not''' display anything will remove itself and a separator that is to the left of it from the display line only.
+
Take this example formatting code:
# If there is not a separator to the left, the same variable will remove itself and a separator that is to the right of it from the displayed line. 
+
* <code>$s(f l s)&lt;, &gt;$m(yyyy)&lt; @ &gt;$M&lt; - &gt;$v(&#92;(yyyy&#92;))</code>
# If there are two separators together, the left one will be removed from the display line and the right is kept.
 
# Separators at the start or end of the display line (or format strings) are removed
 
 
 
=== Example: ===
 
{|
 
|-
 
|<pre>$s(f l s)&lt;, &gt;$m(yyyy)&lt; @ &gt;$M&lt; - &gt;$v(&#92;(yyyy&#92;))</pre>
 
|}
 
  
 
Here are some things that may happen:
 
Here are some things that may happen:
 
+
{| {{prettytable}}
{|
+
!Possibility
 +
!Outcome
 
|-
 
|-
 
|If '''none''' of the variables are known
 
|If '''none''' of the variables are known
Line 636: Line 586:
 
|the second separator will not display
 
|the second separator will not display
 
|}
 
|}
 
  
 
Separators can be inside format strings:
 
Separators can be inside format strings:
 +
* <code>$n(&lt;0&gt;T&lt; &gt;L&lt;, &gt;f&lt; &gt;s)</code>
  
$n(&lt;0&gt;T&lt; &gt;L&lt;, &gt;f&lt; &gt;s)
+
Unlike groups, separators can not cross over/out of format strings. So the separator <code>&lt;0&gt;</code> will NEVER display. No matter what is on the left hand side of the variable.
 
 
Unlike groups, separators can not cross over/out of format strings. So the separator &lt;0&gt; will NEVER display. No matter what is on the left hand side of the variable.
 
 
 
----
 
  
 
Here is a useful example:
 
Here is a useful example:
{|
+
* <code>{({b. $b}<, >{d. $d})}</code>
|-
 
|<pre>{({b. $b}<, >{d. $d})}</pre>
 
|}
 
  
 
This will:
 
This will:
{|
+
{| {{prettytable}}
|-
 
| Only print the outside () if either the birth or death date displays
 
|-
 
| Only displays the center separator if both dates are known.
 
 
|-
 
|-
| So here are some thing that could display
+
|Only print the outside () if either the birth or death date displays<br>
 +
Only displays the center separator if both dates are known.<br>
 +
So here are some thing that could display
 
{|
 
{|
 
|-
 
|-
| <pre>(b. 1970-4-8)</pre>
+
|<code>(b. 1970-4-8)</code>
| <pre>(d. 2012-3-9)</pre>
+
|<code>(d. 2012-3-9)</code>
| <pre>(b. 1970-4-8, d. 2012-3-9)</pre>
+
|<code>(b. 1970-4-8, d. 2012-3-9)</code>
| or the line does not print at all.
+
|or the line does not print at all.
 
|}
 
|}
 
|-
 
|-
Line 671: Line 612:
 
{|
 
{|
 
|-
 
|-
| <pre>()</pre>
+
|<code>()</code>
| <pre>(, )</pre>
+
|<code>(, )</code>
| <pre>(b.)</pre>
+
|<code>(b.)</code>
| <pre>(b., )</pre>
+
|<code>(b., )</code>
| <pre>(d.)</pre>
+
|<code>(d.)</code>
 
|-
 
|-
| <pre>(, d.)</pre>
+
|<code>(, d.)</code>
| <pre>(b. 1970-4-8, )</pre>
+
|<code>(b. 1970-4-8, )</code>
| <pre>(b. 1970-4-8, d.)</pre>
+
|<code>(b. 1970-4-8, d.)</code>
| <pre>(, d. 2012-3-9)</pre>
+
|<code>(, d. 2012-3-9)</code>
| <pre>(b., d. 2012-3-9)</pre>
+
|<code>(b., d. 2012-3-9)</code>
 
|}
 
|}
 
|}
 
|}

Latest revision as of 21:57, 5 February 2016

Gnome-important.png Special copyright notice: All edits to this page need to be under two different copyright licenses:

These licenses allow the Gramps project to maximally use this wiki manual as free content in future Gramps versions. If you do not agree with this dual license, then do not edit this page. You may only link to other pages within the wiki which fall only under the GFDL license via external links (using the syntax: [https://www.gramps-project.org/...]), not via internal links.
Also, only use the known Typographical conventions


Previous Index Next




Back to Index of Reports.

This section describes the substitution values that can be used in the different reports available in Gramps.

Substitution Values

Many of the graphical reports allow you to customize the information that is displayed on the reports. Variable substitution is the method that is used to substitute a particular symbol (key) for specific information about the person in the database.

For example:

Substitution Keys Will show as: (the person is alive)
Line 1 $n Line 1 Smith, Edwin Michael
Line 2 b. $b{ at $B} Line 2 b. 1961-05-24 at San Jose, Santa Clara Co., CA
Line 3 d. $d< at >$D Line 3 d.

In the next section a list of all available variables (The Substitution Keys) follows.

  • If you wish to display names, date, or place information differently, you may use Format Strings to accomplish this.
  • There are also Control Variables to display special characters (like the dollar sign).
  • You can also use Grouping to optionally display information. In the example above Line 2, uses grouping to display ' at ' only when the birth place is known.
  • Along with Events you can print almost anything.
  • Finally, Separators, to make your life complete. In the example above Line 3, uses this to display ' at ' only when both the birth date and place is known.

The Substitution Keys

Personal variables Marital variables
$n Displays the person's name $s Displays the name of the person's spouse
$i Displays the Gramps ID for the person. $j Displays the Gramps ID for the marriage.
$b Displays the person's date of birth $m Displays the marriage date of the person and the spouse.
$B Displays the person's place of birth $M Displays the place of the marriage of the person and the spouse.
$d Displays the person's date of death $v Displays the divorce date of the person and the spouse.
$D Displays the person's place of death $V Displays the place of the divorce of the person and the spouse.
$a Displays an attribute about the person.

see Attributes for more

$u Displays an attribute about the marriage.

see Attributes for more

$e Displays event information about the person.

See Events for more

$t Displays an event information about the marriage.

See Events for more

All of the Marital variables are defined by the person's preferred spouse in Gramps. If the person has never been married, then these variables will not display anything.

Other Substitution Keys

  • $T Displays Todays date.

Default displayed formats

$n $s Names will be displayed as set in 'Name format:' on the Display tab in Gramps preferences
$B $D $M $V Places will display the Place title by default
$b $d $m $v $T Dates will be displayed as set in 'Date format:' on the Display tab in Gramps preferences
$e $t Events will display the description by default

Deprecated variables

Some of the old variables were deprecated because Format Strings have replaced them. So here is a list of those variables and how to achieve their results:

Old Variable How to display it now What is displayed
$f $n Name - as by Gramps name display under Preferences
$n $n(g f) Name - FirstName LastName
$N $n(f, g) Name - LastName, FirstName (note the explicit comma)
$nC $n(g F) Name - FirstName LastName in UPPER case
$NC $n(F, g) Name - LastName in UPPER case, FirstName
$by $b(yyyy) Date of birth, year only
$dy $d(yyyy) Date of death, year only
$my $m(yyyy) Date of preferred marriage, year only
$p $s Preferred spouse's name as by Gramps name display under Preferences
$s $s(g f) Preferred spouse's name - FirstName LastName
$S $s(f, g) Preferred spouse's name - LastName, FirstName
$sC $s(g F) Preferred spouse's name - FirstName LastName in UPPER case
$SC $s(F, g) Preferred spouse's name - LastName in UPPER case, FirstName

Format Strings

Format strings are used to display names and dates differently than those assigned under Gramps Preferences. Here is the syntax for a format string:

$key(format string)
where: key is one of the following characters: 'nsijbmBMdvDVauet'

A format string is any text, separators or format codes (defined below) to display information about the person.

Formatting names

For names ($n $s) you may use the following formatting codes to display the name differently.

t Title f Given name
x Common name. Call name if existing, otherwise first first name c Call name
n Nick name s Suffix
l Surname g Family nickname

These codes can be upper-cased to uppercase the result.

For example:

Formatting code Displays
$n(L, f) ($n(c)), $n(L, f){ ($n(c))}
$s(f l s)
SMITH, Edwin Michael (), SMITH, Edwin Michael
Janice Ann Adams
Gramps-notes.png
Note:

If you want to print a character 'c' within the format string (or any one of the other format codes), you will need to first add a '\' in front of it. See Control Variables for more.

Gramps-notes.png
Note:

The curly brackets { } are used to hide information. Here it is used around ' ($n(c))' to not display ' ()' if the person does not have a call name. See Grouping for more.

Formatting Dates

For all of the date variables ($b $d $m $v) you may use the following formatting codes:

yyyy The year as a four digit number yyy The year, with a minimum of three digits
yy The year, from 00 to 99 y The year, from 0 to 99
mmmm

MMMM

The full name of the month

The full name IN CAPS

mmm

MMM

The abbreviated name of the month

The abbreviated name IN CAPS

mm The month, from 00 to 12 m The month, from 0 to 12
dd The day, from 00 to 31 d The day, from 0 to 31
o The date type (modifier)

For example:

Formatting code displays
$b(mmm-dd yy)
$m(yyyy/mmm/d)
$b(mmm-dd yy)
May-24 61
1995/May/27
Jun-04 85
Gnome-important.png
For date types (modifier)

Only "Before", "After", and "About" are supported at this time. all others will not display anything.
And for date span and date ranges, only the starting (first) date is displayed.

Formatting Places

For all of the place variables ($B $D $M $V) you may use the following formatting codes:

e Street l Locality
c City u County
s State p Postal Code
n Country t Title
x Longitude y Latitude

These codes can be upper-cased to uppercase the result.

For example:

Formatting code displays
$B
$B(c, s, N)
St Judes Hospital
Carmel, IN, USA

Rules for format strings.

  • Anything will print inside a format string
  • You need to use Control Variables to display things like ')' and format codes
  • Separators can be within format strings.
  • At least ONE format code has to display something for the ENTIRE format string to display

For examples:

Formatting code displays
$n(f l)
b. $b {at $B
{d. $d $D
Edwin Michael Smith
b. 1961-05-24 at San Jose, Santa Clara Co., CA
The person is still alive (or has no information present) so the line was removed.

Control Variables

Control variables allow you to print characters that are special to Substitution values within a display.

For example the dollar character '$' is used to note the start of a variable. If you wish to print a dollar character you would use a control character like '\$'

Control Variables Result
\$ Displays a single '$'
\\ Displays a single '\'
\( Displays a single '('
\) Displays a single ')'
\{ Displays a single '{'
\} Displays a single '}'
\< Displays a single '<'
\> Displays a single '>'

Basically anything that comes after a '\' will be printed.

Gramps-notes.png
Note:

When you are inside a format string, you may need to use this to display a character that would normally be a format code.

For example:

Formatting code: displays
$b(m hi mom)
$b(m hi \mo\m)
5 hi 5o5
5 hi mom
As this person was born on the fifth month.

Grouping

There are instances where you do not want certain text to be displayed.

Take the example:

Formatting Code Only date is known Only place is known
died on $d at $D died on 1975-06-26 at died on at Reno, Washoe Co., NV

Neither of these displayed results are very acceptable.

But with groups (denoted by {}), you can optionally print information if a variable within contains information.

Formatting Code Only date is known Only place is known
died{ on $d}{ at $D} died on 1975-06-26 died at Reno, Washoe Co., NV

Which is a more preferable displayed result than in the first example.

Rules for groups

A group will only display if there is at least one variable that displays something. So if a group only has text and/or variables where the information is not known, the entire group will not print.

Groups can also be nested. If this happens (like below), the outer group will only display if there is at least one variable that displays something within the outer group or any of the sub groups.

Groups can also be used to remove text. If you wish to not display the entire line, '-' at the start of a line will remove the entire line from the display if the above rule is true.

If you do not wish to have the display code above (for death information) displayed (the person is alive, or you do not yet know the information), modify the code to look like:

  • -{died{ on $d}{ at $D}

Examples:

This will hide '(' and ')' if the divorce information is not known (or still married).

  • m. $m $M {- ($v(yyyy))

Only display some spouse information if married or remove the entire line if never married:

  • {$s $m(yyyy) {- $v(\(yyyy\))}}

Attributes

Attributes do not have a format string. Instead the attribute name is placed inside []. Here is the syntax for an attribute:

$key[attribute name]
where: key is one of the following characters: 'au'

For example:

Formatting code displays
$a[Profession]
$a[Social Security Number]
$a[Total \$ bequeathed]
Programmer
7A3-29-F1C6
3.00USD

Events

Events have the same starting structure as attributes, $e or $t and the event name in [] but events have an extra format string after the name to display the description, date, place, id, and attributes associated with it. Each of these items can be displayed with a , a 'n', 'd', 'D', 'i', and 'a' respectively in the format string. Here is the syntax for an event:

$key[attribute name](format string)
where: key is one of the following characters: 'et'

Event format strings

The Event format string is used to display information about the event. Here are the format codes to display parts of the event:

Formatting code displays Formatting code displays
n Description i Event ID
d Event Date* D Event Place*
a An attributes for the event**

*These variables can themselves have format strings. Date and a place can be formatted with format string as defined in Format strings.

**Attribute needs to have the attribute name in [] and are formatted as above.

For example:

Formatting code displays
$e[First Communion](d(yyyy-mm-d))
$e[Bar Mitzvah](n< at > D)
$e[Birth](d(yyyy mm/dd) D)
2009-11-6
Jerry's Bar Mitzah at Opas house
2007 05/23 Grandmothers house

And:

Formatting code displays
$b(yyyy-Mmm-dd)
$M
is the same as
$e[Birth](d(yyyy-Mmm-dd))
$t[Marriage](D)

Notes for attributes and events:

Attribute and event names are mandatory. '$a' or '$a[]' will not display anything.

Attributes and event names may have special characters within them. Most notably ']' and ')'. If this is the case, you will need to use Control Variables

Separators

Separators are special 'text only' groups inside '<' and '>' that conditionally display a separator (like ', ' or ' - ') between two groups, variables, format codes or text.

Separators are displayed conditionally depending on these rules:

  • A variable that does not display anything will remove itself and a separator that is to the left of it from the display line only.
  • If there is not a separator to the left, the same variable will remove itself and a separator that is to the right of it from the displayed line.
  • If there are two separators together, the left one will be removed from the display line and the right is kept.
  • Separators at the start or end of the display line (or format strings) are removed.

Take this example formatting code:

  • $s(f l s)<, >$m(yyyy)< @ >$M< - >$v(\(yyyy\))

Here are some things that may happen:

Possibility Outcome
If none of the variables are known None of the separators will display
If only one variable is known Only that variable will print. No separators will print.
If only the spouse's name is not known The first separator will not display
If only the marriage date is not known The first separator does not display. We will be left with:

Jane Doe< - >{ … }And only the divorce date needs to be known to print the second separator.

If only the divorce date is not known the second separator will not display

Separators can be inside format strings:

  • $n(<0>T< >L<, >f< >s)

Unlike groups, separators can not cross over/out of format strings. So the separator <0> will NEVER display. No matter what is on the left hand side of the variable.

Here is a useful example:

  • {({b. $b}<, >{d. $d})}

This will:

Only print the outside () if either the birth or death date displays

Only displays the center separator if both dates are known.
So here are some thing that could display

(b. 1970-4-8) (d. 2012-3-9) (b. 1970-4-8, d. 2012-3-9) or the line does not print at all.
We will not see things like:
() (, ) (b.) (b., ) (d.)
(, d.) (b. 1970-4-8, ) (b. 1970-4-8, d.) (, d. 2012-3-9) (b., d. 2012-3-9)

Back to Index of Reports.


Previous Index Next