The ReaderwareAW Report Writer

The ReaderwareAW Report Writer allows you to easily define your own custom
reports in virtually any format, with images. You can view, print and save the output.

The input to the Readerware report writer is an HTML template which
defines the layout and formatting options. Readerware then
merges in your data to create an HTML file. As the output
is in HTML format you can view it any browser, print it or save the output to
a file and upload it to a web site.

Printing a custom report

The easiest way to get started is to use one of the templates that
are shipped with Readerware. To produce a report do the following:

Search to establish the content
for your report. The Readerware report writer uses the current search results
as input. So you could search for all titles to produce a full report,
search by a given author or category etc.

Open the Readerware Report Writer Window by selecting the File->Report
Writer menu item.

Select the Readerware basic image report, (BasicImageReport.html), from
the list. You will see the template displayed in the window, but instead of
data, you will see text like [[$ARTIST]], [[$TITLE]] etc.
The [[$----] fields identify which Readerware database fields
will be displayed and where.

Click on the Create Report button. Readerware will then populate
the report template with the contents of the current search results and
display the output in your browser. You can view, print or save the report from your browser.

That is how you print a report with the Readerware Report Writer.

Creating a report template

A ReaderwareAW Report Writer template file is in HTML format so you do
need to understand a bit about HTML to take full advantage of all the customization
and formatting options available.

The basic idea is that you simply create the HTML to produce the desired
report, but instead of using real data you use predefined ReaderwareAW
keywords that determine where ReaderwareAW will insert the data. Consider
the template for the basic table example:

This is fairly standard HTML, the interesting part is between the [[$BEGIN_READERWAREAW]]
and [[$END_READERWAREAW]] lines. These lines mark the section of code that
ReaderwareAW will duplicate, once for each CD to be displayed. You can
see that between these lines the HTML statements define a new row within
the table. So if you have five CDs in your result set, ReaderwareAW will
duplicate this section five times creating a five row table.

Within this section you can see several ReaderwareAW database column
names, for example [[$TITLE]] indicates this is where ReaderwareAW is to
place the CD title, ReaderwareAW simply substitutes these keywords with
the database values. That's really all there is to it. Here is the HTML
file that ReaderwareAW might generate from the above template

Accessing Disk and Track Information

Each CD in a ReaderwareAW database is made up of the basic CD information
like artist and title. It then has one or more disk entries depending on
the number of disks in the CD set, and each disk has 1 or more tracks.
If you want to display disk and track information in your report, you must include
a disk and track section in your template. ReaderwareAW will then automatically
handle any number of disks and tracks. The disk template section is repeated
for each disk and the track template section for each track, just like
in the example above.

The disk and track sections of the template are identified by special
keywords. For example:

The above is not a complete template, but it illustrates how you would
display disk and track information. The [[$BEGIN_READERWAREAW]] ... [[$END_READERWAREAW]]
identifies the complete ReaderwareAW template, this section will be duplicated
once for each CD you are displaying. There is HTML to display the CD cover
image, title and artist information.

The [[$BEGIN_READERWAREAW_DISKS]] ... [[$END_READERWAREAW_DISKS]] identifies
the section that will be duplicated once for each disk within each CD.
In this example it displays the disk number.

Finally the [[$BEGIN_READERWAREAW_TRACKS]] ... [[$END_READERWAREAW_TRACKS]]
identifies the section that will be duplicated once for each track, within
each disk, within each CD. This section displays track title information.
Note that this section is within the disk section of the template. This
is the normal way you would code this, you want the tracks listed for each
disk. If you use the tracks section on it's own, ReaderwareAW will display
track information for the first disk only.

There is an example template, awTrackReport.html included with the product.
This is a complete template that displays disk and track information.

Getting Started

You might want to start with one of the examples included with Readerware
and adapt them for you own use, or you can start from scratch.

To start with an existing template, select it in the report writer window.
Copy/Paste the template into a text editor like Notepad or TextEdit.

To install your template select the File->Install template menu item.

To remove a template you no longer use select the File->Remove template menu item.

If you develop custom reports that you think might be useful to other users,
please consider sending them in. They may be placed on the Readerware web
site where others can use and learn from them. Full credit will be given
to the author or you can remain anonymous if you prefer. Just e-mail any
templates to support@readerware.com.

You can browse user contributed templates in the Readerware Knowledge
Base.

Report Writer Templates

Report writer templates are standard HTML files with an embedded section
that is duplicated for each database record displayed. This section is marked
by the following statements:

[[$BEGIN_READERWAREAW]]
.
.
.
[[$END_READERWAREAW]]

Sometimes you need to display multiple records within the marked section. Consider
a two column table where you want each column to display a record from the database.
Effectively you want to duplicate a table row for each two records. You do this with the
[[$INCR_READERWAREAW]] statement. It tells ReaderwareAW to fetch the next record from
the database. For example:

IMG tag for the first image. Looks for the large image, if not found uses the normal image

[[$BESTIMAGE2]]

IMG tag for the second image. Looks for the large image, if not found uses the normal image

[[$USER1 - USER10]]

User defined fields

[[$ROWKEY]]

The Album ID, this is a unique ID alocated to each album automatically as it is added to the database

[[$DISKCOUNT]]

Number of discs

[[$ARTISTURL]]

Artist web site

[[$LOANTO]]

Loaned to

[[$LOANDATE]]

Loan date

[[$LOANDUE]]

Loan due date

[[$LASTLOANDATE]]

The last date this album was loaned out

[[$LOANCOUNT]]

The number of times this album has been loaned out

[[$CURRENTDATE]]

The current date

[[$TEMPLATESDIR]]

URL pointing to the templates directory

[[$TIMERTOP]]

Tells Readerware to add the album play timer to the top of the summary view

[[$TIMERBOTTOM]]

Tells Readerware to add the album play timer to the bottom of the summary view

All keywords must be in uppercase as shown above. They can be in any order,
but must appear between the [[$BEGIN_READERWAREAW]] and [[$END_READERWAREAW]]
lines otherwise they will be ignored.

Report Writer Disk Keywords

The following is a full list of the disk section keywords recognized by ReaderwareAW.
These will be replaced by the appropriate data from the database.

[[$DISKNUMBER]]

Disk Number

[[$DISKTITLE]]

Disk Title

[[$DISKSIDEBREAK]]

For LPs, the first track on side 2

[[$UNITNUM]]

Unit number, the changer number, book number etc. where this album is stored

[[$SLOTNUM]]

Slot number, the slot number, sleeve number etc. where this album is stored

[[$RUNNINGTIME]]

Disk running time

[[$USER1 - USER2]]

User defined disk fields

All keywords must be in uppercase as shown above. They can be in any order,
but must appear between the [[$BEGIN_READERWAREAW_DISKS]] and [[$END_READERWAREAW_DISKS]]
lines otherwise they will be ignored.

Report Writer Tracks Keywords

The following is a full list of the tracks section keywords recognized by ReaderwareAW.
These will be replaced by the appropriate data from the database.

[[$TRACKNUMBER]]

Track Number

[[$SIDEANDTRACKNUMBER]]

Display Side and Track Number for albums with a side break. i.e. A1, A2, B1 etc.

[[$TITLE]]

Track Title

[[$ARTIST]]

Track Artist

[[$COMPOSER]]

Track Composer

[[$CONDUCTOR]]

Track Conductor

[[$ORCHESTRA]]

Orchestra

[[$SOLOIST]]

Soloist

[[$WORK]]

Work

[[$WRITER]]

Track song writer

[[$RUNNINGTIME]]

Track running time

[[$FAVORITE]]

Favorite track

[[$PLAYLIST]]

Track on playlist

[[$BONUSTRACK]]

Bonus track, not on original album

[[$PLAYED]]

Number of times the track has been played

[[$BPM]]

Beats per minute

[[$COMMENTS]]

Comments

[[$MEDIAURL]]

Local copy of media

[[$USER1 - USER2]]

User defined track fields

All keywords must be in uppercase as shown above. They can be in any order,
but must appear between the [[$BEGIN_READERWAREAW_TRACKS]] and [[$END_READERWAREAW_TRACKS]]
lines otherwise they will be ignored. Normally the tracks section itself
is embedded within the disks section.

Keyword Modifiers

The following is a full list of the modifiers that can be applied to any of
the report writer keywords. These will modify the database values, i.e.
display the database value in uppercase.

-U

Display the value in uppercase

-L=n

Limit the value displayed to at most n characters

-S=n

Display the value starting at the nth character. This is relative to 0.

-Y

Used with date fields, this will display the year only instead of the full date.

-H

Hide if empty. Do not display anything if this field is empty. For example [[$IMAGE]] will display the default image if there is no cover art. [[$IMAGE-H]] will display nothing if there is no image.

-H=text

Display the specified text if the database field is not empty. If the field is empty, nothing is output. Suppose you want to display the release date in brackets, but you don't want to display empty brackets if there is no date. Use [[$DATE-H=(]][[$DATE]][[$DATE-H=)]]

The modifiers must immediately follow the report writer keyword. For example:

[[$ARTIST-U]]

This will display the artist in uppercase.

You can apply multiple modifiers to a keyword. For example:

[[$ARTIST-U-L=3]]

This will display the first three characters of the artist in uppercase.