|
This is actually
more of a pre-processor than an actual script command. It tells the
scripter that some data is needed from the user. Once that data has
been assigned to the variable,
that variable can be used through the script to substitute what the
user chose for some literal text.
The usefulness of this
will become apparent if you try to create a script to print out,
say, all away talks being given by a certain brother. You could
write one script per brother, changing the name to look for in the
database each time. But hey, that wouldn't be very efficient!
Instead, use a variable to represent the brother's name, and thus
you only have one script. Every time the user runs it with a
different brother's name, it's the same script executing each time,
but it prints out different data.
Use the variable prompt edit box to
specify the text to be presented to the user for each variable
required (this will happen when you actually generate a custom
report itself). Use the variable name edit box to
specify the name that this piece of data will be known by in
the script from now onwards. It should be a single word.
You can use the droplist to select
some predefined variable names - AwaySpeaker, Congregation,
LocalSpeaker and LocalAndAwaySpeaker. These are
special because they will provide you droplists to select the
values to assign to the variables.
If you know ahead of time the preferred
choices that you want to choose from then you should fill in the
Optional set of values to use edit box. Each value
should be separated with a comma (,). These options will then
automatically show in the drop list for you to select from (similar
to AwaySpeaker and Congregation variables). Note,
if you specify only one optional value, then it will be treated as
a default value (see below) rather than an option for a drop
list.
The custom script editor will raise multiple
errors whenever unititialised variables have been used for LOOP and
IF criteria. Consider using default variable values to avoid this
issue. The first option specified for the VALUES parameter will
become the default. The editor will use ??? when nothing has been
specified for the VALUES parameter.
REQUIRES commands can appear anywhere in the
script, but logically they must appear BEFORE you try to use the
variable somewhere else, otherwise they will show ???. It would be
considered good practice, though, to declare them at the top of the
script, or at least before each section that uses them. But
you are not forced to. It just makes it easier to
maintain.
You won't be allowed to
duplicate an existing variable name. In order to actually use
your variable within the editor, you must update the value
that the variable refers to. This is
covered in the last section of this help topic.
Command
syntax
|
|
Setting a variable allows you to either
change the value of an existing variable conveniently, or to
actually declare and initialise a variable in one go. Variables
declared in this way will become available for inserting via the
control panel in later commands, and do not need to be declared
with REQUIRES; it is implicit. Variables appearing on the
right-hand side of the equals must have previously been set,
though. The value to assign to the variable is an expression, but it does not require
curly braces { and } around it. These variables have similar
properties to dynamic variables declared with REQUIRES.
Example:
$iNumBrothersAvailable = $iNumSpeakers +
$iNumReaders |
|
This changes how the text will
be displayed from this point on in the report. The settings
you make will remain in effect until you explicitly change
them. The program determines what the current settings are
from the current script line. There is a sample area showing
you what the new font settings would look like.
Although all of these options
come under the Font Change button, it does in fact cover five
separate script commands. These are:
Font (Command syntax)
Use the various options to set the font
size, typeface and style. There are 3 styles that can be
applied - bold / italic / underlined.
Align (Command
syntax)
Choose between left / centre / right to
change the way text is aligned in the future. Note that the TAB
command will only have an effect if left alignment is being
used.
Colour (Command
syntax)
Use the dropdown listbox to select the
colour of the text (see below).
Highlight (Command syntax)
Use the dropdown listbox to
select the background colour used for text. Note
that it only colours the back of the actual words,
and not the spaces above and below. It does, however,
colour the spaces between words on each line.
Banner (Command syntax)
Use the dropdown listbox to
select the background colour used for text and blank
lines. It differs from HIGHLIGHT in that it colours blank
lines. If you want text to appear transparent on a
non-white banner, then you must set the highlight to the same as
the banner colour. Note that separators show over the top of the
banner colour.
Note that you can
use a custom colour as well. You are not
tied down to the colours available from the list. To use a
custom colour, select (Custom) from the droplist
to display a colour dialogue:
Use the options and features available to
choose your desired colour. See the command syntax for details on how custom
colours are represented within the script.
The sample scripts provided
show all of these features being used. Use them to help you
understand all of these options. Only the settings that are
changed will get put into the script file.
|
|
|
This alters the gap after each line of text.
It's a bit like the blank command. You can select a value from
1.0 up to 2.0. 1.0 means single line spacing and 2.0 means double
line spacing (have a single blank between lines, as if BLANK had
been issued in between each EOL). 1.x is between the two
ofcourse.
Note that any banner colour will fill in the
gaps left by such spacing, just as it does for BLANK. Note that
line spacing does not affect separators - they always have the same
height.
|
|
Although you can select a value using the
drop list, you can also use expressions to calculate a value. For
example, if the brother generating the script wanted the page a
little more widely spread in terms of lines, you could use
something like this:
LINESPACING $iUserLineSpacing
(so the brother can enter a value between
1.0 and 2.0)
|
Command syntax
|
|
There are situations
where you might want to doing something like a
LOOP (see below) but using a simple set of user defined values,
or within a numeric range.
The following dialogue is displayed when
you click the button:
|
Variable to hold value at
each loop
Type in or select the variable that you want to use
to hold the loop iteration value. For example: |
Example 1 |
Use row
count
Set this option
if you would like to retain the number of rows within the loop.
This is probably more useful for when you are using a variable
containing an unknown set of options, or the numeric counter with a
dynamic set of values (as opposed to literal). For
example: |
Example 2 |
From options
list
You can loop a set of values by either using an existing variable
which contains a set of comma delimited values (see example 2) or a
user defined set of literal values (see example 1).
|
Counter
You might prefer to use a numeric counter. Basically, you set the
start, end and increment values as required.
|
Example 3
|
Note:
- You can omit the
increment; it defaults to 1.
|
- The start,
end and increment expressions are not limited to
whole numbers (integers); they can be floating-point numbers as
well. They can even go backwards using a negative ‘increment’
(decrement!). As long as you can get from the start to the end by
applying the increment, it will work.
- Plain counter loops are static loops. That means that
the start, end and increment expressions
are evaluated once at the beginning of the loop, using
current variable values, and the list of values that the loop will
walk is built in advance. Changing the value of variables used
within the start, end or increment
expressions during the loop will have no effect on how many loops
or what values are used in subsequent iterations.
|
Command
syntax |
|
This is
the most powerful script command that you will need to
use at least once in your custom reports. It
displays the loop dialogue
for you to create / modify a loop
command.
A LOOP is used to walk through a list of
rows in a specified database table one at a time until there are no
more. This allows you to embed FIELD commands to print out contents
of that row repeatedly.
There are quite a
few options on the loop dialogue, so there is a separate help
topic. It is important that you understand how to use the
loop script command correctly so please click on the
link if you have not already done so.
Command
syntax
|
|
This is the
second most powerful command that you may like to use in your
custom reports. It displays the IF dialogue
for you to add conditional processing to your
reports.
An IF is used to
allow the schedule to show different details based on different
results. Also, they can only be used inside an existing LOOP.
Under some
circumstances you may find that the IF command does not appear to
behave correctly. If this happens, try to refresh the script, as this usually resolves
most problems. When you are creating an actual document based on
this script, the IF command does not suffer this
anomaly.
An IF command can now contain expressions on
either side of a comparator, by embedding them within { and }. Such
expressions will be evaluated first and the result fit back into
the line, before the script engine tries to evaluate the IF. For
example:
IF ("$variable_name" > "{ $iRowCount / 2
}" )
IF ( "{ $variable_name + 1 }" > "5")
Command
syntax
|
|
This displays the above dialogue and is used to
print the contents of the current database row from the named
column (field). To get a 'current database row' you
must have issued a LOOP command. For nested LOOPs, this
always refers to rows being fetched by the innermost loop
as of the current script line. In other words, the current script line must be
within a set of LOOP / END_LOOP commands. Please view the
sample scripts to see how to use this script command
correctly. Since the result is a piece of text, it is
affected by any font, colour or alignment settings (and requires
EOL to be issued to show on the screen / report).
Use the dropdown list to select
the field you want printed out. Then select how
the field is to be interpreted. There are four ways to
interpret the field value:
Don't interpret (Command syntax)
This simply places the contents of the
field into the report with no modifications.
Time (Command syntax)
If the field holds the time as a text
string, then you can use this option. It will display the
time in the format specified in the programs general preferences. This
will either be 12 hour (the default) or a custom
format.
Short date / Long date / Custom
date (Command
syntax)
Select Short date/Long date to
interpret the text retrieved as a date in your PC's short or long
date format. If you just use the first choice (don't
interpret) to pull out a date field from the database, it will
be shown in the database's natural format. Select Custom date
if you want to specify yourself how the date is to be displayed in
the report. This will enable the edit box and dropdown list.
Use the edit box to specify the format string that you want to use
or use the dropdown list to choose from 13 predefined date formats.
You may alter a predefined format string after you have selected it
from the dropdown list. If you do this, the dropdown list will
automatically change to say User
Defined. If the days of the week
and months of the year format codes are used, they will show in the
same language as the program interface. Click on the link for
command syntax (above) to see how to specify the format
string.
Talk theme name (Command syntax)
Most of the tables only store the talk
number, so use this choice if you want to translate the talk number
into its associated theme.
String character
count (Command
syntax)
Only available when 'Save field contents
to variable' is selected, this fills the variable with the count of
characters in the field contents, rather than the contents
themselves. The result can thus be used in numeric comparisons.
Since talk theme numbers are normally translated into the
corresponding title by selecting 'Talk theme name' (see above), in
order to collect the character count for a talk number as a title
string you should also select 'Interpret as talk theme name
first'.
Save field contents to
variable (Command
syntax)
This option should be used by advanced custom script users. It
assigns the field value into an existing variable that you have
declared with the REQUIRES command (or you can
type in a new dynamic variable to use). There-after you can use
that variable (field value) at some other place in the report. It
has many uses! You might have to refresh the script to show any changes.
|
|
This is used to extract a single piece of data
from a single row of the database. It displays the regular LOOP /
Raw SQL dialogues with some extra controls:
|
Make sure the option
Simple field lookup to
variable is
ticked.
Then select the field you want to
lookup the value for from the droplist.
Finally, type in or select a
dynamic variable
to save the value of the field to. |
Note: You must be
comfortable with using the LOOP command with criteria (WHERE
clauses) to reduce the record set to one database row. Please read
up about LOOP's if you are unsure.
A lookup field can also be generated from a
raw SQL statement rather than a normal loop with WHERE criteria. A
similar set of lookup field controls appear on the dialog when you
ask to use raw SQL. Note, however, that the field list will be
empty until you enter a valid SQL SELECT statement. The list is
re-populated after a 2-second delay whenever you update the
SQL.
|
Command
Syntax |
|
This adds the specified
piece of text in the current font and colours to the report.
If you
select the Paragraph option, then the text will be
word wrapped. Use CTRL + Enter to insert a
new line into the paragraph (new lines are represented
with \r\n). The command syntax provides full
details.
If you
want to include speech marks in the text, you must use a special
text identifier: &speech . This must be in lowercase.
Every occurrence of &speech will get converted into a
speech mark.
You can
also put variables into these text
commands which have been declared using the REQUIRES command.
You can select a variable from the drop list. The variable will get
inserted into the text at the current cursor position. The other
controls become enabled after a variable has been chosen and the
Format as date setting has been selected (you can
only select this setting if the program thinks your variable
contains a date value). In this mode you can customise how the date
variable will look by using the date options. See Insert Date for more details about those options.
In this instance the formatting will be put directly into the text
as #SHORTDATE, #LONGDATE or
#CUSTOMDATE[format_string]. See
Literal Text,
Variables & Quotes for examples.
You can
include more than one date variable within the same line of text.
However, if you want to make any changes, you should re-select the
variable and then alter the settings accordingly. For details about
what variables are and how to use them, read the last section
below.
Text added
in this way will not be seen on the screen / report until you issue
an EOL command (unless an EOL is already there of course).
Command syntax
|
|
This adds an image into your
document. The following image file formats are supported: BMP, GIF
and JPG. There are two ways that you can use images in your
scripts.
Method 1:
Click the Browse button to
display a file dialogue. Navigate to the image and select it. NOTE:
You must have 'Get image filename from field contents' option
deselected for selecting a filename directly from
disk.
Method 2:
If you are inside a LOOP command, you can
set the Get image filename from
field contents option before
clicking Browse. Now, when you click Browse, a list of
fields are displayed for you. Select the field that contains the
image path and click Insert. More than
likely you will want to use the Location Map field
as it has been provided for this purpose.
You can also alter the image size by moving the scale
indicator or typing in a value. Using a scale under 100% will cause
your image to reduce in size from it's original state. Likewise,
using a scale greater than 100% will cause it to enlarge. The
default is 100%. Naturally, if you opted for method 2 and have
specified a field, then you must remember that all of the images
displayed will use the same scale factor. The images are aligned
using the current font alignment.
Reports with images can be printed or exported to
Word. However, please note that the CRS document only
references the images and does not embed them. So if you delete
the image files or move them then the script will not work
correctly. If you want to send a CRS with one or more image
commands to another user you should supply the images too and the
other user will have to alter the paths in the editor or else use
the same directory structure. Using the images from a directory
such as C:\ScriptImages is recommended to make this easier. An
alternative is to print the document as PDF (use something like
CutePDF) and email that or export it to Microsoft
Word.
Command syntax
|
|
This displays the above dialogue and is used to print
the congregation meeting time. There are two parts to this
dialogue which are detailed below. At the moment, it is required
that you call this command from inside an existing
LOOP so that you can get access to the
current row.
Congregation
Use the drop list to select the field
(from the current row) that specifies the congregation.
Or, if you want to use your own congregation, then you can simply
set the Use $LocalCong option. Setting that option
will disable the droplist of field names.
Date
Use the drop list to
select the field (from the current row) that specifies the meeting
date. Or, if appropriate, set the Use
Variable option and select one of the predefined date
variables: $Today, $NextYear and
$NextTwoYears.
Please view the sample scripts to see how to use this
script command correctly. Since the result is a piece of
text, it is affected by any font, colour or alignment settings (and
requires EOL to be issued to show on the screen /
report).
The program will filter out any fields which are of
an incorrect type. So it will only display text type fields
in the top dropdown list, and date type fields in the bottom
dropdown list.
Once you have specified these two items and pressed
Insert or Update, the program
takes the actual value of the congregation [field] and the date, and then works out what the correct meeting
time would be for that date at that congregation. If the date
is in the past, it will just use the "current" meeting time for
that congregation.
Command Syntax
|
|
This inserts today's date, range start date
or range end date using your PC's short or long date format.
Since the result is a piece of text, it is affected by any font,
colour or alignment settings (and requires EOL to be issued to show
on the screen / report). Select Custom date if you want to
specify yourself how the date is to be displayed in the
report. This will enable the edit box and dropdown list. Use
the edit box to specify the format string that you want to use or
use the dropdown list to choose from 11 predefined date formats.
You may alter a predefined format string after you have selected it
from the dropdown list. If you do this, the dropdown list will
automatically change to say User
Defined. If the days of the week
and months of the year format codes are used, they will show in the
same language as the program interface.
Note that the Range start and Range end
options will be disabled if you have selected "All Entries" on the
custom reports maintenance page. Also, if any report uses the
date range commands in the script, and you have selected "All
Entries", then the report will display "<No date range
specified>".
Click on the link for command syntax (below)
to see how to specify the format string.
Command Syntax
|
|
Tabs allow the next piece of text to be
indented, and more importantly, aligned to a common column within
the output. Tabs can be set to align on the left, on the right, or
centrally. They can be quoted either as an absolute column number
from the left of the drawing area, or as relative tabs from the
current position. Relative tabs are useful when you simply need
spacing rather than alignment.
Although you can choose a simple value using
either the slider or by typing in the number, you can also use
expressions to calculate a
value. If, for example, you were trying to break up rows of data
into three columns, you might use an expression such as:
4 + ( ($iRowNumber % 3) * 12)
to ensure that the data from consecutive
rows tabs across appropriately to each column.
|
The sample page view shows
vertical lines indicating all the available tab stops. Use
these to aid you in determining where an item of text should be
placed. Simply hover the mouse over a tab stop and a small
tool tip will display showing you its tab stop number.
Also, there is a tab ruler at the bottom of the editor showing the
tab stop positions and every other tab stop value is indicated,
like this: |
|
Command
Syntax
|
|
This issues a blank line with the same height as the
current font. Use the slider or type in a number to adjust the
number of blank lines to insert. Note that a blank line
will be coloured with any BANNER colour, but will
not be coloured with any text back colour.
Although you can choose a simple value using
either the slider or by typing in the number, you can also use
expressions to calculate a
value. If, for example, you were trying to let the report generator
control how many blank lines were used between blocks of
information, you might use something like this:
$iBlanksBetweenBlocks * 2
Command syntax
|
|
This draws a horizontal line
across the page in a certain style and for a certain percentage of
the page. The line drawn is always centred and uses the
current colour settings.
Use the slider or type in a
number to adjust the width of the separator. You can choose
from four available line styles - solid / dot / dash /
double. There are also three thicknesses to choose from
- thin / medium / thick.
Note that for double, the thickness controls
how far apart the double lines are; the double lines themselves are
always thin.
Command syntax
|
|
Do you find that some of your custom
report scripts are always the same? Perhaps you are using a header
with the Kingdom Hall address etc. and you put this at the top of
several reports.
If this is the case, then consider putting the script that gets
repeated everywhere into its own custom report. Then, you can use
the Insert Script INCLUDE facility to insert the
script at the cursor location.
|
You are presented with a list
of your existing scripts.
Select the one that you want to include and press the
Insert button. |
Command syntax |
|
There are no options for this command. It
has no effect on the actual report generated. It inserts a
blank line into the script file. Like this:
Use script spaces to break up
your script into sensible sections. It will help make your
script file easier to read and understand. You can also insert a
script space using CTRL + Space.
|
|
This places a comment into the
script file. It has no effect on the actual report generated.
Insert comments at appropriate places in your script file to
explain what the script is doing. For example, at the top of the
script file you could put a comment detailing what the script has
been designed for.
Comments are prefixed with "//". For
example, this is a valid comment:
// this is a comment
Note that you don't have to add the "//"
prefix if using the control panel; only if writing your own script
outside of the editor.
|
|
There are no options for this command.
Causes all pieces of text issued since the last EOL (or the
beginning of the script) to be output in the colours and fonts
selected. Note that if multiple ALIGN commands have been issued
since the last EOL (or script start), only the LATEST issued will
be in effect. You MUST use EOL to output text, it will not show
otherwise. Note that xxxFIELD and xxxDATE commands are also treated
as pieces of text in this way.
Command
syntax
|
|
This issues an end of page command. There
are no options for this command. A possible reason for using this
command is during a LOOP. Within the loop you could put an end of
page command at the bottom. That would ensure that each iteration
of the loop would start on a new page. The start of a new page is
indicated by a dashed line in the editor.
Command
syntax
|
