This not a complete guide, just some notes on pitfalls and possibilities!
I have added some special features which are marked with an asterix (*) below!
Variables can be defined and used when constructing a report. Variable names follow common rules,
shall consist of alfanumarical and underscore (_) characters. The value of a variable is retrieved
with '$' preceding the variable name.
1. <setvar name="..." value="..." />
The value part can contain arithmetic expressions such as "2*($n-1)+1".
There are some special values that can be used:
"@ID" will find the line "0 @xref@ xxx" of the current gedcom record and return "xref".
"@XXX" will find the first line containing the tag XXX (n XXX ...)
"@generation" will return the generation number, valid only when sortby="generation", see below.
The name part may also be a reference to a variable which then must contain a legitimate variable name,
e.g. <setvar name="dump" value="dval" /><setvar name="$dump" value="25" /> will result in
that variable dval will get the value 25.
(*) The value can specify @$nam which returns the value of the variable the name of which is $nam,
i.e. the value of tha variable nam. A side-effect used for debugging is that when 'dump' defined as above
is used in <setvar name="dz" value="@$dump" /> the variables defined so far are printed by ReportParserGenerate.php
to a file named 'my-errors.log' at the webtrees top. The first $dval entries are not printed. Example:
dwidth='200'
pwidth='436'
srcwidth='0'
srcleft='60'
sheight='15'
width='0'
width1='0'
width2='0'
explain='Förfäder i direkt linje samt deras familjer'
dump='dval'
dval='25'
In order to create text in the report the following xml elements are used.
2. <TextBox left="$lpos1" height="12" newline="1"> ... </TextBox>
The contents can be any valid xml elements and output should be within text boxes, see below
3. <Text style="name"> ... </Text>
The contents can be pure text or <var ... > (see next paragraph) or other xml elements that
print gedcom values, see below.
N.B. space characters are significant and sometimes(??) new lines also. However tab characters
in the beginning of a line are ignored!
4. <var var="..." />
This will output the text (or numerical value) of the named variable. Here the name can be
given in another variable, as <var var="$dump" /> which will output the value of the variable
dval which is 25 in the example above. However, if a variable is not defined it will print
the name of the variable. If dval had not been set the output would be dval!
5. <if condition="..."> ... </if>
The condition can be specified almost as expected with the special trick that '>' must be
written as 'GT', '<' as 'LT', '&&' as 'and', and '||' as 'or'. Spaces may be needed for separation.
E.g. "$n GT 7" or "($n GT 0)and $x==0".
A report will collect data from several individuals or families. I have found two useful constructs
here, <Relatives ...> and <List ....>.
6. <Relatives id="$pid" group="$relatives" maxgen="$maxgen" sortby="$sortby"> ... </Relatives>
This will create a loop to find relatives to the individual $pid. In each iteration focus is set
on one individual and his/her gedcom record is easily available. Example:
<SetVar name="sex" value="@SEX"/>
<SetVar name="mid" value="@ID"/>
<SetVar name="generation" value="@generation"/>
group can specify one of
child-family Parents and siblings
spouse-family Spouses and children
direct-ancestors Direct line ancestors
ancestors Direct line ancestors and their families
descendants Descendants
all All
maxgen will limit the number of generations to include, not valid for ...- family
sortby will sort the result according to
generation by generation number, start person is generation 1, increased by 1 both up and down
NAME by name
BIRT:DATE by birth date
DEAT:DATE by death date
other do not sort
7. <List list="individual" filter1="BIRT:PLAC CONTAINS $birthplace"
filter2="BIRT:DATE GTE $birthdate1"
filter3="BIRT:DATE LTE $birthdate2"
filter4="NAME CONTAINS $name"
sortby="$sortby">
...
</List>
This will create a loop with the individuals (or families) that pass the filters, possibly
one to nine filters named filter1 to filter9.
Possible values for sortby are NAME, BIRT:DATE, DEAT:DATE, MARR:DATE or CHAN (change time).
8. <Facts ignore="$ignore" families="1"> ... </Facts>
For the current individual or family, loop over the tags not listed in $ignore.
Focus is set on the found tag. Subrecords can be accessed directly, e.g."SOUR".
Now variables @fact and @desc are available, @fact is the tag name and @desc is
the rest of the line (n TAG ...). N.b. the same tag name can occur many times.
When the focus is set on one individual, family or a fact it is time to create some output to the report.
This should occur within a TextBox and inside a Text area. It seems that output can be generated without
fulfilling this but don't rely on that!
9. <GetPersonName id="" select="combined" />
Outputs the name of the current individual if id= is missing or is an empty string, otherwise
it will show the first (birth) name of the individual whose xref is given as the id string.
(*) select can be used to print the latest name ("latest") or a combination of latest name
and the surname part of the birth (first) name: "Mary Johnsson b. Svensson" where 'b.' stands
for 'born'. This is a common way to write names in Sweden!
10. <GedcomValue tag="MARR:PLAC" />
Will output the value of the subrecord of the record currently in focus. The tag may be
as above if a family is selected. Many other records can have tag="SOUR:DATA:TEXT" and so on.
11. <RepeatTag tag="XXX">
If the currently selected record has subrecords with tag XXX they are handled in a loop.
Text can for example be produced with <Text><br />XXX=<GedcomValue tag="XXX" />. </Text>.
12. <Gedcom id="xid"> ... </Gedcom>
Can be used to switch focus to another gedcom record. Useful to be able to print parents
of a selected induvidual, or children, or ... it can also select subrecords of the corrent
record.