2.0/reports/report-template-terminology.xml

   1 <?xml version="1.0" encoding="utf-8"?>\r
   2 <chapter xml:id="template-terminology" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
   3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
   4     <info>\r
   5         <title>Template Terminology</title>\r
   6     </info>\r
   7     <para> </para> \r
   8     <simplesect xml:id="create-template-datatypes">\r
   9         <info>\r
  10             <title>Data Types</title>\r
  11         </info> \r
  12         <informalfigure> <para>The central column of the <guilabel>Database Source Browser</guilabel> lists\r
  13             <guilabel>Field Name</guilabel> and <guilabel>Data Type</guilabel> for the\r
  14             selected database table. </para>\r
  15             <para><mediaobject>\r
  16                 <imageobject>\r
  17                     <imagedata scalefit="0" fileref="../media/create-template-33.png"/>\r
  18                 </imageobject>       \r
  19             </mediaobject></para>   \r
  20         </informalfigure>\r
  21         <para>Each data type has its own characteristics and uses:</para>\r
  22         <informaltable>\r
  23             <tgroup cols="3" align="left" colsep="1" rowsep="1">\r
  24                 <colspec colnum="1" colname="type" colwidth="1.0*"/>\r
  25                 <colspec colnum="2" colname="description" colwidth="1.0*"/>\r
  26                 <colspec colnum="3" colname="notes" colwidth="2.0*"/>\r
  27                 <thead>\r
  28                     <row>\r
  29                         <entry>Data Type</entry>\r
  30                         <entry>Description</entry>\r
  31                         <entry>Notes</entry>\r
  32                     </row>\r
  33                 </thead>\r
  34                 <tbody>\r
  35                     <row>\r
  36                         <entry>id</entry>\r
  37                         <entry>Unique number assigned by the database to identify a\r
  38                             record</entry>\r
  39                         <entry>A number that is a meaningful reference for the database but not of much use to a human user.  Use in <guilabel>displayed fields</guilabel> when counting\r
  40                             records or in filters.</entry>\r
  41                     </row>\r
  42                     <row>\r
  43                         <entry>text</entry>\r
  44                         <entry>Text field</entry>\r
  45                         <entry>Usually uses the <guilabel>Raw Data</guilabel> transform.</entry>\r
  46                     </row>\r
  47                     <row>\r
  48                         <entry>timestamp</entry>\r
  49                         <entry>Exact date and time</entry>\r
  50                         <entry>Select appropriate date/time transform. <guilabel>Raw\r
  51                             Data</guilabel> includes second and timezone information, usually more than is required for a report.</entry>\r
  52                     </row>\r
  53                     <row>\r
  54                         <entry>bool</entry>\r
  55                         <entry>True or False</entry>\r
  56                         <entry>Commonly used to filter out deleted item or patron records.</entry>\r
  57                     </row>\r
  58                     <row>\r
  59                         <entry>org_unit</entry>\r
  60                         <entry>A number representing a library, library system, or\r
  61                             federation</entry>\r
  62                         <entry>When you want to filter on a library, make sure that the field\r
  63                             name is on an <guilabel>org_unit</guilabel> or <guilabel>id</guilabel> data type.</entry>\r
  64                     </row>\r
  65                     <row>\r
  66                         <entry>link</entry>\r
  67                         <entry>A link to another database table</entry>\r
  68                         <entry><guilabel>Link</guilabel> outputs a number that is a meaningful\r
  69                             reference for the database but not of much use to a human user. You\r
  70                             will usually want to drill further down the tree in the\r
  71                             <guilabel>Sources</guilabel> pane and select fields from the\r
  72                             linked table. However, in some instances you might\r
  73                             want to use a <guilabel>link</guilabel> field.  For example, to count the number of patrons who borrowed items you could do\r
  74                             a count on the <guilabel>Patron</guilabel> <guilabel>link</guilabel> data.</entry>\r
  75                     </row>\r
  76                     <row>\r
  77                         <entry>int</entry>\r
  78                         <entry>Integer</entry>\r
  79                         <entry/>\r
  80                     </row>\r
  81                     <row>\r
  82                         <entry>money</entry>\r
  83                         <entry>Number (in dollars)</entry>\r
  84                         <entry/>\r
  85                     </row>\r
  86                 </tbody>\r
  87             </tgroup>\r
  88         </informaltable>\r
  89     </simplesect>\r
  90     <simplesect xml:id="create-template-transforms">\r
  91         <info>\r
  92             <title>Field Transforms</title>\r
  93         </info>\r
  94         <informalfigure> <para>A <guilabel>Field Transform</guilabel> tells the reporter how to process a field\r
  95             for output. Different data types have different transform options. </para>\r
  96             <para> <mediaobject>\r
  97                 <imageobject>\r
  98                     <imagedata scalefit="0" fileref="../media/create-template-34.png"/>\r
  99                 </imageobject>\r
 100             </mediaobject></para></informalfigure>\r
 101         \r
 102         \r
 103         <formalpara><title>Raw Data</title><para> To display a field exactly as it appears in\r
 104             the database use the <guilabel>Raw Data</guilabel> transform, available for all data\r
 105             types.</para></formalpara>\r
 106         \r
 107         <formalpara><title><guilabel>Count</guilabel> and <guilabel>Count Distinct</guilabel></title><para> These transforms\r
 108             apply to the <guilabel>id</guilabel> data type and are used to count database\r
 109             records (e.g. for circulation statistics). Use <guimenuitem>Count</guimenuitem> to\r
 110             tally the total number of records. Use <guilabel>Count Distinct</guilabel> to count\r
 111             the number of unique records, removing duplicates. </para></formalpara>\r
 112         <para>To demonstrate the difference between <guilabel>Count</guilabel> and\r
 113             <guilabel>Count Distinct</guilabel>, consider an example where you want to know\r
 114             the number of active patrons in a given month, where <emphasis>active</emphasis>\r
 115             means they borrowed at least one item. Each circulation is linked to a Patron ID, a\r
 116             number identifying the patron who borrowed the item. If we use the <guilabel>Count\r
 117                 Distinct</guilabel> transform for Patron IDs we will know the number of unique\r
 118             patrons who circulated at least one book (2 patrons in the table below). If instead,\r
 119             we use <guilabel>Count</guilabel>, we will know how many books were circulated,\r
 120             since every circulation is linked to a patron ID and duplicate values are also\r
 121             counted. To identify the number of active patrons in this example the\r
 122             <guilabel>Count Distinct</guilabel> transform should be used.</para>\r
 123         \r
 124         <informaltable>\r
 125             \r
 126             <tgroup cols="3" align="left" colsep="1" rowsep="1">\r
 127                 <colspec colnum="1" colname="title" colwidth="2.0*"/>\r
 128                 <colspec colnum="2" colname="id" colwidth="1.0*"/>\r
 129                 <colspec colnum="3" colname="name" colwidth="1.0*"/>\r
 130                 \r
 131                 <thead>\r
 132                     <row>\r
 133                         <entry>Title</entry>\r
 134                         <entry> Patron ID</entry>\r
 135                         <entry> Patron Name</entry>\r
 136                     </row>\r
 137                 </thead>\r
 138                 <tbody>\r
 139                     <row>\r
 140                         <entry> Harry Potter and the Chamber of Secrets</entry>\r
 141                         <entry> 001</entry>\r
 142                         <entry> John Doe</entry>\r
 143                     </row>\r
 144                     \r
 145                     <row>\r
 146                         <entry> Northern Lights</entry>\r
 147                         <entry> 001</entry>\r
 148                         <entry> John Doe</entry>\r
 149                     </row>\r
 150                     <row>\r
 151                         <entry> Harry Potter and the Philosopher’s Stone</entry>\r
 152                         <entry> 222</entry>\r
 153                         <entry> Jane Doe</entry>\r
 154                     </row>\r
 155                     \r
 156                 </tbody>\r
 157             </tgroup>\r
 158         </informaltable> \r
 159         <informalfigure>\r
 160             <formalpara><title>Output Type</title><para> Note that each transform has either an <guilabel>Aggregate</guilabel> or\r
 161                 <guilabel>Non-Aggregate</guilabel> output type. </para></formalpara>\r
 162             \r
 163             <para> <mediaobject>\r
 164                 <imageobject>\r
 165                     <imagedata scalefit="0" fileref="../media/create-template-35.png"/>\r
 166                 </imageobject>\r
 167             </mediaobject></para>\r
 168         </informalfigure>\r
 169         <para> Selecting a <guilabel>Non-Aggregate</guilabel> output type will return one row of\r
 170             output in your report for each row in the database. Selecting an\r
 171             <guilabel>Aggregate</guilabel> output type will group together several rows of\r
 172             the database and return just one row of output with, say, the average value or the\r
 173             total count for that group. Other common aggregate types include minimum, maximum,\r
 174             and sum. </para>\r
 175         <para>When used as filters, non-aggregate and aggregate types correspond to <guilabel>Base</guilabel> and <guilabel>Aggregate</guilabel> filters respectively.  To see the difference between a base filter and an aggregate filter, imagine that\r
 176             you are creating a report to count the number of circulations in January. This would\r
 177             require a base filter to specify the month of interest because the month is a\r
 178             non-aggregate output type. Now imagine that you wish to list all items with more\r
 179             than 25 holds. This would require an aggregate filter on the number of holds per\r
 180             item because you must use an aggregate output type to count the holds.</para> \r
 181     </simplesect>  \r
 182 </chapter>\r