This section is not complete. It will be worked on as time goes on. At this time the best bet is to check out the examples provided with the distribution.
Both the invoices and reports use the same mechanism for their generation. In simple terms they are xml files residing in the directory /opt/ah3/reports. The invoice is just a report this has the defined name of Invoice. Ah3 will treat this report special in that when the user requests to preview or print the invoice this is the report which will be used. Keep in mind that the name of the report is not the file name but the name defined within the report definition. From no on through this document, only the term report will be used. It's use can be for either a report or the invoice.
In the following examples to overcome formatting issues, there is a space embedded in the ]]< sequences. If you want to copy and paste example code, you would do better going to the source invoice.xml than this document.
The biggest difference between an invoice and a report is that an invoice only can only have one input defined and it must be named invoice. This input will be provided by ah3.
Other reports can have multiple inputs and they will be presented with a query dialog to get the required information from the user before the report is generated.
Each report file is comprised of different blocks. One or more of wach block can be used depending on the report being generated.
Input blocks are single XML elements using the input tags. These elements define the inputs which will need to be provided by either the program or the user. Each input item has a name, a label, a defult value and a type attribute. The name attribute will be used to reference the item from the other sections of the report. The label is the text to present to the user when querying for a value.
Default values are provided with the attribute default. These can be pretty much any string, but the type will determine the appropriate values as well as any specially interpreted values.
For example, in the supplied invoice.xml file, only one input is defined:
The type defines the expected value of the item. It can be one of the following values:lineedit: Simple text with no interpretation.
password: Like the lineedit type except the entered text will be masked.
double: A floating point number. A min attribute and a max attribute can be provided to bound the acceptible range
integer: Just like the double type except only integer values will be accepted.
yesno: Provides a pulldown asking for Yes or No. It will return a character of 'Y' or 'N' when referenced in the report.
truefalse: Like the yesno type, this provides a pulldown asking for Yes or No. It will return a value of 0 or 1 when referenced in the report.
date: Provides a specialized edit field for dates. The defualts ot today and tomorrow and yesterday can be provided as well as any valid date.
Data Source blocks defined using data_source elements. Each data source must have a unique name defined using the attribute name. The body of the element should be a CDTATA text element comprising of the sql select statement to use for selecting the data for the source.
Example 4-2. Data Source Element
<data_source name="customer">
<![CDATA[
select name, addr, city, state, zip,
home_pn, work_pn
from customers where ident =
(select customer from workorders where ident = ::input:invoice:)
] ]>
</data_source>
Note that in input source invoice was referenced from within the sql statement.
The remainder of the report is defined by one or more sections using a section element or a banner element. Each section will define what data should be presented in the report. Banner elements define grapics to be displayed on a report. Banner elements have no body as all of their information is in the attribute fields.
Each section can generate a block of text, data from the database or an image. In the former two, data can be specified from either an input argument, fields from the datasources or a configuration parameter. Images are always hard coded at this point using the path name to the image file on the disk.
Banner elements place an image on the page with no wrapping of text around them. They are equivelent to a single column section.
Example 4-3. Banner Element Containing an Image.
<banner width="500" height="111" img="file:///path/to/image.gif" />
Caveat: It will be rare when a report with a graphic looks exactly like what gets printed on a piece of paper. It will probably server the user the best to set the height and width of the banner image to fit the piece of paper then let the preview look like it will.