Tutorial 1 - Building the CustomerList Print Template

The CustomerList report is a simple dump of the customer IDs, company names and phone numbers. We will start assembling it with the creation of the Print Template. Print Templates make up the Presentation Layer of Scribe, and are vehicles for displaying data prepared by the Business Logic Layer - executable flowcharts.

Select Print Templates entry in the Application Launchpad window and click on the Launch button (or just double-click the Print Templates entry). Scribe will open a new ("UNTITLED") print template Workspace window:

The two buttons on the toolbar that are of interest to us at this point are Grid and Page layout . When these buttons are pressed, the following page control panels are displayed:

The grid establishes spacing between adjacent print lines, and location of the fields which, when brought into the Workspace, align themselves along the grid lines. The default grid spacing (in pixels) can be changed by either choosing one of the standard densities, or by typing new values in the H and V fields. (Another way of setting the grid density to a non-standard value is by dragging the grid in the panel.) The shade of gray of grid lines and the Workspace background are for visual aid purposes only during the template editing, and do not affect the appearance of the printed page.

The Page Layout panel sets the page orientation (portrait/landscape), paper format and page margins. Together, the grid density and page layout establish the basic characteristics of the Print Template that must be shared by all templates used within the same report.

Now, let us have a look at the Palette window. At the bottom of the window is a scrollable view with components that can be dragged into the Workspace. We will use the Title component to create a header segment with the report column headings. Drag Title into the Workspace and drop it at the location shown in the figure:

After setting the Title field to the new name, you can change the font; to do so select the text in the field first, and then select Format > Font > Show Fonts... menu item; this will bring up the Font Panel:

The panel is preset to the font of the currently selected text; we will change the font size to 10 by selecting the new size and pressing the Set button. Note that the Font Panel stays on the screen after setting the font; you can close it or just let it slide under the Workspace window when it becomes main window again.

The next component to add to the template is the underline:

Continue to drag-and-drop Title fields and underlines until the following picture appears:

Now we can bring in a field of another type: Page #, which is a system field. System fields get their content automatically in the course of the report generation; Page # field keeps track of the sequential number of the currently printed page. All system fields are located in the Name column of the Palette and can be dragged into the Workspace:

Resize the field to make it shorter (2 grid positions) and change font size to Sans Serif Regular 10.

At this point, we are ready to create the first segment of the Print Template - the Header segment. Print Templates consist of one or more segments - groupings of the print fields that are handled as one unit during the page formatting. Header segments are printed once per page, or once per lifetime of the template (this is covered in Segment Separator and Print component on-line manual).

Drag the Separator component from the Palette into the Workspace and drop it beneath the underlines:

To make the created segment a Header, click anywhere on the background within the segment, and set the property in the Inspector:

We can now add data-carrying fields to our Print Template. Let us have another look at the Palette window. Initially, its Source and Fields columns are empty; to populate the Source column with tables and views available in the database we first have to select the database schema where these objects are stored. Press the Set button (located on the Palette window) to display the list of database connections and schemas available to Scribe:

Select the connection and schema from the list (note that Scribe Personal works with only one connection at a time, so there will be only one entry in the Connection column; Scribe Enterprise will show all connections set by the Administrator). Double-click on Northwind schema, or just press the Select button; the Palette window will show all tables available in Northwind schema (and clicking on a source, e.g. the Customers table will show the fields available in the Customers table):

Drag the CustomerID field of Customers table into the template:

Set the font to Sans Serif Regular 10 (the same font that was used in the headings) following the same routine (double-click the field's text to select it, bring up the Font Panel and set the font). The only difference is that the selected text in CustomerID field remains non-editable: names of table fields cannot change.

Bring in the CompanyName and Phone fields, place them under their respective headings, resize and set to the same font. You should now have the Print Template similar to this one:

The second segment, containing the table fields, must be printed every time the new set of customer data is retrieved by the Report Procedure. The procedure will make a call on this Print Template on every pass through the retrieval loop, so this segment must be designated as the "Body" of the template. To make the created segment a Body, click anywhere on the background within the segment, and set the property in the Inspector:

To preview the created template, press button; the produced image should look like this:

It is now time to save the Print Template. Scribe uses a hierarchical naming convention, similar to the directory/file tree structure used by the operating systems like Windows and Linux. In Scribe, all report components (Print Templates, Procedures etc.) are given unique names within a multi-level directory tree; e.g. Print Template named Query/CustomerList belongs to the "Query" tree branch.

Select Template > Save... menu item, and type in the template name and description into the panel as in the figure below:

Technically, our work of creating the Print Template is complete. However, before proceeding to the next Tutorial, it is worth exploring some features that "fell through the cracks", because they were not needed in this exercise.

Every print field has a data type associated with it. The data type is set in the Inspector that fine-tunes parameters and visual attributes of the fields; for the Title fields (the ones that were used in the header segment of the template) that data type is set to Text, and cannot change. The data type of table fields that were used in the Body segment is derived from the table metadata and cannot be changed in the Inspector either.

However, instead of dragging the table fields into the template, we could make use of the dynamic Print Field components. Dynamic fields can be assigned any data type and name (see the Dynamic Print Field on-line manual for detailed description), and are functionally equivalent to the database table fields in that they can be assigned the desired data type in the Print Template, and be fed the required content from the Report Procedure. The only difference between them and the database fields, in this context, is in the way the template fields are linked to the report procedure variables.

This happens in the Report Procedure; when the Print Template is used there, its fields will have to be linked with the procedure variables to ensure the flow of data from the procedure to the template. The linkage will be done automatically if the procedure variables have the same names as the template fields; otherwise manual dragging of variables into the Print Template Inspector will be required. And since the same table fields that are used in the Print Template will be retrieved in the Report Procedure, the names will match, and the linkage will be quick and simple.

Another parameter that was left to its default state and therefore not covered in this Tutorial is the template printing flag in the Print Template Inspector. The flag has two settings:

• Always start on the new page
• Start on the next available line

For the simple report that uses only one Print Template (the kind we are building now) the default ("Always start on the new page") is what we want: when the template kicks into action the first time in the report procedure, it will start printing on the new page. However, reports can use a number of dissimilar Print Templates (however, they must have the same grid and page size), and these templates may be designed to produce only portions of the printed page (e.g. template A prints Headers only, and templates B and C both produce multiple detail lines (Body)). In this case we would flag templates B and C as "start on the next available line" to avoid the needless page break after the Headers.