Rangecast FAQ
[FAQ-1183] View Scripting Language


Page Type: REFERENCE


OVERVIEW

It is possible to create and save customized views that are constructed as a series of rules. These rules can be based on such properties as channel ID, jurisdiction, type of agency, etc, and define how channels will be presented on the player.


BACKGROUND

Views are player configurations that organize channels in particular ways (for example, including only certain channels in the player, grouping channels into buttons, setting buttons to levels of priority, etc.)

The user can select among various Views using a drop-down on the Channels Panel.

Some Views are created automatically by the system (for example, 'All Channels' which places every available channel on its own button, and various arrangements that show only police or fire traffic, or only channels from a single county, or group channels into buttons based on the specific jurisdiction and agency type.)

Additional customized Views can be created using a scripting language. This document provides an introduction and outline of that language.


EXPECTED PROBLEMS

The scripting language creates Views in the context of a World. If a channel is not available within a World, then it cannot be accessed through any View within that World.

In concept, a World is a set of channels that the player receives notifications about, and Views organize how those notifications are used. But if the player is not being notified about activity on a channel, it cannot be accessed without changing Worlds.


REFERENCE

1) WHERE SCRIPTS ARE PLACED

Scripts can be entered in three places.

a) In the hub administrative pages of the hub originating content. If a script is stored at a hub that operates scanners, then every user who receives content from those scanners will be given Views described by scripts stored at that hub.

b) In the hub administrative pages of the hub distributing content. If a script is stored at a hub that licenses users, then every user who utilizes that license will be given Views described by scripts stored at that hub.

(Note that for customers who both operate their own scanners and license their own users, the last two options are essentially identical. The distinction matters in circumstances where audio content recorded at one hub is distributed through another hub's license.)

c) In the player. Scripts can be directly entered and immediately applied within the browser. In addition, a user can save a configuration including their script (it will be stored as a custom World that includes the script, and therefore will include Views described by that script.)

When creating scripts, even if you intend to store through the hub administrative system (best in nearly every circumstance where you want to add a View to users' default options), it is highly recommended that you initially write and test your script in the player. This method provides instant feedback, and is by far the easiest way to try out your ideas. When you are happy with your script, you can copy-and-paste it into the hub administrative system.

Within the hub administrative system, select the option Scripts. A text box will open, where you can view/edit your scripts. When finished, press Save Script to save your work.

It is also possible, within hub administration, to write scripts in the programmer. Select the Constellation option in navigation (upper-left) and scroll to the end of the page. There will be a text entry form for scripts. Add your script, then press Apply Changes, and go to Save Options - there Save to commit this change to the system.

Within the player, go to Options. The player must be in Advanced mode to access this feature. Scroll down to Content Selection / Changes and select the option "Advanced View Configuration (Scripting)". A text box will appear, where you can enter your rules. Press Apply Changes, and your views will be created and instantly available.

(Note that views created in the player are not automatically saved, but this is a good laboratory space for developing your scripts.)


2) GENERAL FORMAT OF SCRIPTS

Scripts define Views, in one or more lines of programming code.

The first line always specifies the name of the View, and defines the initial starting case (including all channels, including no channels, or copying another View.)

Every channel in your World is then processed according to the subsequent rules, starting with the second line, and continuing to the last rule. These rules can change the state of a channel (e.g. priority, regular scan, shown but off, not shown) or assign the channel to a button (buttons can be named, and can include many channels.) If several rules affect the channel, the rules are processed in sequence, and the channel will be presented according to its final state after processing all rules.

Your script can create many views. Each View begins with a special line giving the name and initial state, and continues with all following lines until you start the next View.


3) INITIAL LINE (CREATING A VIEW)

The first line of script, when creating a View, may look like this:

view Example

This creates a view with the name Example, and with (by default) all channels on their own buttons, in the normal scan state.

If you want to limit your view, you might write something like this:

view Example < NV

This will creates a view with the name Example, limited to only channels where the jurisdiction information listed as within Nevada. Each Nevada channel will be on its own buttons, in the normal scan state.

Or you could write:

view Example < NV01 NV03

This will do something similar, but limited to two counties in Nevada. Rangecast uses a geocoding format with two capital letters for the state code (standard postal codes), followed by two characters for the county, and two characters for the city. (The county and city fields are usually, but not always, numeric.)

For reference, geocodes can be found in the programmer, the jurisdiction name and geocode for every channel is shown in the right column. Or you can use our geocode reference database here: https://www.rangecast.com/system/geocode.php

As illustrated in the example above, you can list a series of conditions that are OR'd together. A channel will be included if it meets any of the listed criteria.

If you want to create a view limited to fire channels:

view Example < F

A list of agency code types is available


[FAQ-1029] Reference list of Agency Codes used by RadioReference, HPDB, RCHAN

This is a list of the Agency Codes used by RadioReference, and in the Home Patrol Database (HPDB), and in Rangecast RCHAN files.




You can combine these limitations. For example, if you wanted all fire channels from one county plus all channels (of whatever type) from another county, you can use a plus symbol to limit a specific criteria in some way:

view Example < NV01+F NV15

Once you have a View, you can create another View that starts out as an exact copy (and then following rules will make customizations.) If you've already created Example, you can do this:

view Another Example < Example

(View names can include spaces.)

To create a view that starts with all channels hidden (invisible / not available) use the special word "none". Following rules may place specific channels into a scan state.

view Example < none



4) ACTION RULES

The most common rules do something to particular channels. For example:

off R

will put all Railroad channels (type R) on their own buttons, and with those buttons in the OFF state (visible and available on the player, but set to not play traffic.)

The first word of an action rule is one of these states:

priority - priority mode (will play ahead of other traffic in Monitoring mode)
scan - normal scan state
low - low priority state (more likely to be skipped, if needed, to stay near realtime)
off - available but set to not play traffic
hide - not shown on the player (channel will be hidden in this View)

If two rules both act on a channel, then the last rule that "does something" to it will win. For example, this two line sequence will result in railroad channels being in priority state:

off R
priority R

You can use "all" to affect all channels. For example, this will turn all channels off, and then put the railroad channels in normal scan state:

off all
scan R

If you want to combine channels onto a single button, you place the name of the button in quotes, as shown here:

scan "Railroad" R

You can also specify multiple types of channels to be treated in the same way, as in:

scan "Two Counties" NV01 NV07

The name in quotes can include some special keywords, which always have a leading percentage sign. For example, this will take all fire channels, and put them on buttons that have the name of the town:

scan "%city" F

So this single rule can create many buttons, since there will be a button for every town with fire channels.

Note that whenever two or more channels are given identical button names, these channels will be combined onto a single button with that name (you will not get multiple buttons with the same name.) So this is a way to combine channels onto a single button.

You can use multiple keywords, as in:

scan "%state %city" F

which will create buttons with both the state and city names (which may be important in communities where the same city name is found on both sides of a river that defines a state boundary.)

You can also combine keywords and literal text, as in:

scan "%city FD" F

Available keywords include:

%state (two-letter state code)
%county
%city
%agency (agency type such as Police)
%agency123 (same, but with subdivisions into Dispatch, Tactical, and Talk)
%a (agency type expressed as a single letter, for compactness)
%a123 (agency type with subdivision expressed as a two-digit code, for compactness)
%freq (frequency of channel)
%cid (channel ID from database)
%gid (group ID from database)
%sid (system ID from database)
%geo4 (geocode of channel, to county level of precision)
%geo6 (geocode of channel, to city level of precision)

In addition, the special keyword "%touch" will apply the action to all buttons that include any channel matching the criteria. For example, this will put all buttons with any railroad channel into priority:

priority "%touch" R

And the special keyword "%label" is replaced with the current label. So for example, if a fire channel happens to be on a button labeled "West" when this rule is encountered:

scan "Monroe %label" F

... then the button will be renamed to "Monroe West".

Note: if a button is created, but when the rule processing is complete, no channel remains on the button (every channel on that button was affected by a subsequent rule that placed the channel elsewhere), then the empty button will be omitted from the View.

The special keyword set combines scan and finish. This command places the matching channels on buttons according to the usual rules, and immediately finishing the processing of these channels, so following rules cannot affect the placement. For example,

set MA0401 "BOSTON FIRE" F
scan "%city"

... will put the Boston Fire channels on a single button, and then arrange everything else onto buttons by town name.



5) AVAILABLE CRITERIA

In rules, when expressing criteria for matching channels, we have encountered jurisdiction (e.g. NV) and agency type (e.g. R). The available types of criteria include:

State (e.g. NV)
County (e.g. NV01)
City (e.g. NV0103)
Agency type (e.g. F or F1)
Channel ID (e.g. C123456)
Group ID (e.g. H01234)
System ID (e.g. S00292)
Frequency or Talkgroup (e.g. 10012)

Channels are indexed in a system/group/channel hierarchy, with the codes for each level listed in the programmer. By referencing a group or a system, all channels in that set can be acted upon at once.

For an example of a simple View with four channels (only) shown in scan state:

view Example < none
scan C123456 C051774 T019446 T282175


6) SEQUENCING OF BUTTONS

There is a way to affect the positioning of a button on the display, when the player is in grid mode (buttons in rows and columns.) The button table is fluid and responsive, meaning that the number of columns is not fixed, but will vary in response to screen size. To understand how to affect the ordering, the way buttons are sequenced must be understood. Buttons are normally sorted alphabetically (but if single channels are not given short names, and are on their own buttons, then the broadcast frequency will be shown as an identifier.) It is possible to apply a "sortkey" to a button, and if this is done, this text is prepended to the button name for the purposes of sorting buttons alphabetically. For example, if we have buttons with these names:

Alpha 123
Beta
Gamma 7

... and we give these (respectively) sortkeys 5, 31, and 33, then they will sort in this order:

Beta
Gamma 7
Alpha 123

... because for sorting purposes, these are the names sorted, and this is an alphabetic sort (by first column, then second column, etc, with a numeral ranked before a letter):

31Beta
33Gamma 7
5Alpha 123

In general, a simple approach is to use a standard length (like two characters), with the first character used to group related buttons, and the second character used to sequence the buttons within a group. If multiple buttons are given the same sortkey, they will be ordered alphabetically within that set of buttons.

With this background, a sortkey can be specified on a rule line like this:

scan /44 "Boston Fire" MA0401

This sortkey will be applied to the Boston Fire button created there. If keywords are used (like %city) that create multiple buttons, the same sortkey will be given to all.

Some substitutions are available in sort keys. For example %a is replaced with the agency code, so if you enter this command:

scan /1%a all

... then channels will be arranged by agency type (alphabetic sequence - e.g. E emergency management before F fire before G federal before H hospitals, etc)

The %o substitution creates an agency sequence where police is placed before fire.


7) GENERAL RULES

Some rules affect the processing flow of channels. For example, if you want to block all railroad channels -- exclude them from your View:

block R

When railroad channels are processed, if this rule is encountered, the channel will be hidden (not presented on any button). This is a terminal action, meaning that following rules will NOT be processed for this channel. You can write the rest of the script assuming that railroad channels have been taken off the table, and will not be shown.

You can also limit the channels presented to a specific type, for example this will only pass fire channels (this is equivalent to blocking everything that's not a fire channel):

only F

For all these rule types, you can also do the usual combinations of criteria, such as

only NV01+F NV15

Similar in concept, if you want to finish processing of a channel -- not blocking it, but leaving it in the current state at that point in the rules:

finish F

Then you can write the rest of the script while knowing that fire channels are fixed to whatever state they were in at that point, and will not be affected by following rules.

The complement is a rule that only continues the script for matching channels (in this example fire), while processing terminates immediately for everything else:

continue F


8) SPECIAL PURPOSE RULES

A few special purpose rules are available while affect the View in some broad sense, but don't act on particular channels.

The width command sets the width (in pixels) of the buttons, when presenting in Grid format (a table of buttons in rows and columns.) For example,

width 160

Another option is to specify a fixed number of columns in the button layout, e.g.

columns 5

The newlines command will force a line break in the buttons in certain positions. One or more break points are specified, and these are placed into the sorted list when sequencing buttons. When a newline is encountered, a new line is started in the button display. Note that the command is "newlines" (plural) even if only one value is given.

For example, if you've used Sortkeys to arrange buttons, with the first character defining related groups of buttons, and the second character used to position buttons within a group (such as sortkeys 11, 12, 13, 21, 22, 23, 24, 31, 32) then this command will force each related group to start on its own row on the button display.

newlines 1 2 3

You can change the name of a button. For example, this will rename a button named ABC with DEF without any other modifications. Note that the new name is in quotes (just like the format in a normal rule like "scan"), and the old name is given after without quotes.

change "DEF" ABC


9) GLOBAL RULES

A few special rules can be included that have a global effect -- on ALL views, instead of helping shape a single view. For clarity, these rules should be placed at either the beginning of the script (before any view command is given) or the end of the script (after all view rules).

In the main display area, channels are described with three lines of text, corresponding to the system, group, and particular channel. (All channels are indexed into a three-level hierarchy.) There is a text name associated with each of these levels. You can replace the text that is shown, based on the system ID, group ID, or channel ID:

name S00292 Better Name for System

Note that since the three lines of text correspond to each level of the hierarchy, you cannot replace entirely how a specific channel is described. For example, if two channels are in the same system in the channel database, then the first line of text will be the same for both channels. You can modify this text, but you cannot modify it uniquely for one of the channels without also affecting how the other is described.

In the player, channels also have a "short name", which is used on buttons in the default "All Channels" view, and anywhere else that a channel appears by itself without an assigned button name.

For example, this simple rule - which places all railroad channels on their own single-channel buttons - will give these channels buttons showing their default short name:

scan R

The "short name" is not a property of a particular View, but is used for the channel throughout the player. Normally you would set short names through a user interface in the programmer, but this can also be done in a script (usually selectively, as it's tedious to list out many channels this way). Note that if a channel has had no short name assigned, then the frequency of the channel is used as a default short name, as it is compact and usually unique within a view.

To set a short name, you must use the channel ID to identify the channel:

short C123456 Short Name

(Short names can contain spaces.)

You can also set matching channels to their default frequency values with the "unlabel" command, e.g.

unlabel F

Or you can set matching channels to their channel ID with the "cid" command, e.g.:

cid all

Finally, we will describe the "subst" command. If used, this should be placed at the beginning of the script (before the first view is defined. The subst command changes the text that is used for generating button names via keyword replacements such as "%city".

For example, Ohio has multiple communities named Springfield within different counties. So to distinguish the communities, you may enter a rule like this:

subst OH0305 Springfield Township


CITATIONS

INDEX


Images shown - [block]