Custom Reports

Scripting Tutorial - Using The Script
Editor

If you've never used the script editor before, then this will
help you get used to how to get around in the editor and begin
writing scripts.

Please read this topic through completely before going on to the
writing tutorial. It
is important you understand this basic functionality of the script
editor and custom reports maintenance page first. Please note that
this information is also held elsewhere in the help system, but has
been collated together to assist with the writing tutorial.

Getting There

To start writing your own scripts you will need to
access the maintenance dialogue. To do this, either use
the Maintenance menu (top right), or click the Maint toolbar icon
(right). Either one will bring up the maintenance dialogue, as
shown below. Once that is done, you should select the Custom
Reports tab, as marked below.

Another way to access these reports is if you have
the startup panel when you first run the program (below right). If
you choose "Manage custom reports" from here, it will open the
maintenance dialogue and select the Custom Reports tab
automatically.

The list on the left contains all the scripts that
you have written. From here you can either create a new
script, select and edit and existing one in the list, or even
select and delete one from the list if you really want.

When the program is installed, several sample
scripts are also installed as plain text files. As they stand, they
are not usable directly by the program; you must manually 'install'
them into the program. There are some specific reasons why this is
not done automatically, but those reasons are beyond the scope of
this tutorial. To get those scripts installed into the program, see
Installing Sample Scripts
Into the Program below.

The Basics

When you start a new script, you will be asked for a name. There
are some restrictions on what characters the name can contain, but
you should be able to find a suitable name with ease. After that,
or if you choose to modify an existing script, the script
editor dialogue will open up.

What you see now should be what looks like a piece of paper with
feint vertical gridlines, and to its right, an empty box. The empty
box is where the script commands will go, and the page is where
that script will be rendered (drawn) so that you can see how it
will come out on the report (although the final report won't have
the gridlines, they are a guide which you will learn about in the
matching tutorial on How To Write
Scripts).

Note that the page on the left of the script editor dialogue
will take on the chosen printer settings; that is, it will be
scaled according to whether you have chosen A4 or LETTER paper
sizes, and will be orientated according to whether you have chosen
portrait or landscape. These paper settings must be set by choosing
Print Setup... from the File menu before opening the
maintenance dialogue. Note that while the page changes orientation
and the guidelines widen, they are still vertical.

You should also see two grey windows; one will almost certainly
be open, a window with a list of buttons down the left, titled
Control Panel. The other is most likely minimised, and is
titled Required Variables (although in its minimised state
you probably won't see the whole title). The control panel is the
place where all commands are inserted or edited; there are other
ways to get script in the box, but this is your first and foremost
place to do so and will help avoid mistakes in using the script
commands. The variables window is where you will enter temporary
values for variables your script requires so that you can check
that your script acts on the data as you expect.

To insert a raw script command, you click the relevant button
from the left of the control panel. Options appear in the right
half in most cases, which you adjust as you desire, then you click
Insert at the bottom (or Cancel). Even if the command doesn't
require parameters, you still have to click Insert for consistency.
Note that if you click another button from the left while you
already have a command entry in progress, it is equivalent to
clicking Cancel for the first command and then starting the new
one; nothing is inserted into the script until you click
Insert.

To delete a script line, click on the line in the box to the
right and press <Delete> (or use "Delete line" from the menu
that pops up if you right-click the selected line). Special rules
apply for deleting a LOOP, but that will not be dealt with here.
For the purposes of the How To Write Scripts
tutorial, do not click in the script box unless told to do so;
otherwise you risk changing the insert point, getting lines out of
sequence and getting the wrong results, which will only lead to
confusion. As you progress through that tutorial it will gradually
teach you how and why to change that insert point.

Editing a line of script is straightforward; double-click a line
(or use "Edit line" from the menu that pops up if you right-click
the selected line), and it will appear in the control panel as if
you had just selected the command from the control panel.
The Insert button has changed to Update, to replace the command
with the new parameters. Again, don't try this unless told to. If
you change your mind, clicking Cancel on the control panel will put
the line back in the raw script exactly as it was.

If you click Cancel on the script editor dialogue, if you have
made any changes to the script from when it was started / loaded,
then you will be asked if you want to abandon changes. If you say
Yes, the script will revert back to what it was when loaded; if
this was a new script you started, it will not be saved,
and will not be inserted into the list on the Custom
Reports maintenance page. If you say No, the editor will not be
closed and you can click OK instead. Clicking OK automatically
saves the updated script, and if this was a new script, its name is
inserted into the list on the Custom Reports maintenance page.
These scripts are saved as .CRS files in the Scripts subdirectory
below where you installed the program.

If, at any time during the How To Write Scripts
tutorial, you make a mistake, the easiest way to get out of it is
to abandon changes to your script (Cancel the editor dialogue and
select Yes when asked to abandon) and start a new script (or edit
the existing one if you had some of it saved).

The easiest way to get a sample script into the editor is to
right-click inside the raw script box on the right and select
Import Text from the popup menu. Now you can
select the script you want to insert. The file dialogue
defaults to the location of the installed sample scripts but you
could navigate to any folder.

There is another way to get script into the raw script box in
the editor, as we mentioned above. The raw script box supports
fully standard Copy, Cut and Paste commands just like your
favourite text / document editor, and the results are stored in
plain text if you copy or cut from the script. Note that the same
special rules apply to trying to Cut a LOOP command as for Delete.
Similarly, if you have plain text from another editor, you can
Paste it into the raw script box and the parser will try to
interpret it as script. If you look at the menu that appears when
you right-click in the raw script box, you will also see "Reformat
script". By choosing this, a very simple indentation scheme will be
used to make commands inside loops clearer.

Date Filtering

The script parser has some fairly good
filtering mechanisms in its commands that allow you to narrow down
the set of data returned. One of the most common types of filtering
you will want to do is to limit the report to a specific range of
dates. Although you could do this within the script, we have
provided a much simpler mechanism for this since it is so
commonplace. On the right of the Custom Reports maintenance page of
the maintenance dialogue you will see two date controls and a
checkbox saying All Entries. By default, this checkbox is switched
on. This means that any loops you write will use the full date
range supported by your database - that is, records returned in a
loop will be from ANY date that exists.

If, for example, you wanted to only list
data from October of last year, then you would want to limit the
filter accordingly. To do this, switch off All Entries, and the
date controls will become enabled. You can now select the start and
end dates (inclusive) to use when looping the database. The easiest
way to change these controls is to click the arrow, and a familiar
calendar window will pop up to allow you to select the exact date.
Alternatively, you can directly click in the control on one of the
three parts (month, date, year) with the mouse, and use the up /
down arrows on your keyboard to roll through the possible values.
Note that the up arrow increases the value and the down
arrow decreases it. You may find this odd to start with,
but it is perfectly logical when you think that the higher
arrow gives a higher value.

Scale View

By now you have probably opened the script
editor dialogue and seen the page. Note that when you do, by
default there should be no scroll bars (unless you opened a script
that gave a lot of data, in which case there would be vertical
bars) - specifically, no horizontal bar. This is because by
default, the [page] view is scaled so that the width you
get on the screen represents the full width of the page. What you
will not see until you can get a long script is that at the bottom
of that page is a broken line across, representing the page break -
the full height of the page. This is known as scaled view
and allows you to see the whole page at a glance. Of course, this
means that the output is going to be slightly squashed as it tries
to fit it all in. The smaller your screen resolution, the worse
this squashed effect will be.

To see the output actual size, i.e., as
close to the real size of text as it will print out as possible,
you can switch off this scaling using the Scale View checkbox on
the Custom Reports maintenance page. You can also make this change
by choosing Scale View from the Options menu within the script
editor dialogue itself. Either way, a horizontal scroll bar will
now be visible, since the physical page is larger than the window,
and you can scroll across to see the rest of the width of the
page.

Making Copies Of Scripts

Lastly, one of the controls on the Custom Reports maintenance
page we have thus far not mentioned is Copy. When you click this,
you must have an existing script selected. It will ask for a new
name (same rules apply as for starting a new script), and if you OK
that little window, then the script selected will be opened
straight into the editor ready to make changes. Note that this is a
copy of the script you selected - any changes you make
now, if you OK the script editor dialogue to save the changes, will
be saved in a new script with the new name you gave it -
it will not change the original script you selected. If
you Cancel the script editor dialogue and abandon changes, then it
will be as if you never clicked Copy - the duplicate of the script
will not be created, just as a new script is not created if you
cancel.

If you have got this far and everything is making good sense to
you then... what are you waiting for?! Go and read How To Write Scripts!