|
|
|
| About Scripts |
PLATO scripts are used to export data into lists and reports, and use data to build documents by means of simple text formatting or more complex formatting using XML, HTML, RTF, TeX, or virtually any other form of text-based markup. Scripts can also be used to perform global search and replacement of data throughout an entire database.
Each PLATO script has three basic elements: a type, a scope, and an output definition. An output definition consists of an output filename (and the means of handling the file--namely Plato or an external program) plus the markup necessary to format the output.
Type
A script's type defines what it will do. A script can be one of three types:
- Find specific objects within a database and display them in a folder
- Globally replace specific data within a database
- Export data from a database into formatted documents
Scope
A script's scope defines where it will draw data from. Scripts perform their action within a database, in one of the following contexts:
- An entire PLATO database
- A single defined folder within a database
- The folder currently open in a database
- The currently selected object in a database
Within a database or folder the scope can be further defined by:
- Listing specific object classes to operate upon to the exclusion of other object classes.
- Limiting the objects to act upon by specifying the object attributes and data that an object must contain.
- Specifying whether the script should descend recursively through nested folders.
- Specifying whether an object's child or parent cross references should be included in the scope.
Object classes the script will act on are selected by checking them off in the 'selected objects list.'
Find/Replace Criteria
Multiple find replace criteria can be specified.
Output
Script output can be sent to any of the following:
- A scratch folder within a PLATO database
- A file buffer keyed to the script, or an external file named by the script
Markup
If the action of a script is to produce reports or documents, the desired output format must be specified. This is done by creating and attaching markup. Markup must always be specified by the user, however several 'canned' output formats are provided with PLATO so the user can see how they are designed.
In general, markup describes how data from Plato is to be formatted within a document or spreadsheet. This process is a little like the 'mail-merge' feature in word processors.
Markup Post-Processing
If the output is sent to the file buffer or another file, the markup can invoke other applications to post-process the file. Post processing can be as simple as loading the output file into a word processor for further editing, or into a web browser for viewing. However, post processing can involve more complex operations, such as converting the output to another format and then loading it into a viewer or other application.
|
|
| Using the Script Editor |
|
|
| Figure 1: Script Editor Pane Elements |
|
The script editor is where scripts get put together. There are three important elements to the editor:- Pane Navigator The navigator displays the available editing panes; click on an entry to open the pane. The contents of the navigator will change depending on the script type because not all panes are pertinent to all script types. At the bottom of the navigator pane are the "save" and "save as new" buttons. The "save" button will only light up if you have made changes and the status bar is lit green. The "save as new" button is always available (so long as the status bar is lit green); pressing it will create a new script without altering the original script you created.
- Editing parameters pane The editing pane is where you select the script settings that will control the behavior of your script. There are six different editing panes:
- Script name/type Pertinent to all script types Set the type of the script, give it a name, and jot any notes to explain what it does.
- Script Scope Pertinent to all script types Define the script's input scope.
- Script Find/Replace Criteria Pertinent to all script types Develop more extensive scope criteria based on the contents of specific fields. You can also develop find and replace criteria here.
- Script Output Pertinent to the document creation type only Define where the script output goes.
- Script Output Format Pertinent to the document creation type only Select markup and autoenumerator criteria
- Script Messages Pertinent to all script types Contains the script validation messages. Whenever you make a change to a script it is validated and the messages are posted here. Error messages are posted in the orange pane and until they are corrected the status bar is lit red and you won't be allowed to save the changes.
- Status Bar The status bar indicates whether the script can be successfully used. If it can, the status bar is green. If not, the status bar is red and the messages pane will tell you what is wrong.
The following sections explain the different editing panes in detail.
|
|
| Script Name/type |
|
|
| Figure 2: Script Editor Name/type Pane |
|
This pane sets the script name and type. It also allows you to jot some notes about the script.- Script Name Mandatory setting. This is how the script will be identified in lists and menus.
- Script Type Mandatory setting. This defines how the script behaves. There are three types:
- find and display in folder The script type will collect all the objects that match the criteria given in the script scope and display them in a scratch folder. For this type there is also the option of attaching the script to a folder. This causes the script to run whenever the folder is opened and displays its results in the folder (instead of the usual scratch folder). See "Maintaining folders" for more detailed information.
- find and replace (no display) This script type collects all the objects that match the criteria given in the script scope and performs whatever change opertions are given in the 'find/replace' criteria. There is no display of the changed objects. This script type can be used to make extensive changes throughout an entire database without the usual field-level validation, so be very careful.
- create formatted document This script type will collect all the objects that match the criteria given in the script scope and run them through the markup specified in the "script output" pane to create a document.
- Script notes Optional setting This text box is available to jot any notes about the script. Such notes can be useful if you do not use the script very often and it is not obvious what the script does (without investigating the markup, etc.).
|
|
| Script Scope |
|
|
| Figure 3: Script Editor Scope Pane |
|
This pane sets the scope of the script. Scope here refers to the range and number of objects the script will process, so scope is about selecting objects for the script to process.- Data Source 'Source' means the location in which the script will begin its search for objects. There are four options:
- Database The script will scan the entire database. If it's a big database this is potentially the slowest option.
- Folder The script will scan a designated folder. For this option a secondary drop-down list will be displayed so that you can select a specific folder.
- Current folder The script will scan the folder that is currently open.
- Selected Object The script will act only on the object that's selected in the current folder. This option is best used in conjunction with the 'descend folders' option, below, and the selected object is a folder that contains other obects the script will act upon. However, this option may be used in conjunction with the 'document creation' script type to format the metadata and notes of a single object.
- Use Raw Data (don't expand) This setting determines whether the script will act on raw or field formatted data within an object. Normally you should not check this setting because the raw data may not be deciperable except to Plato's internal routines. The raw data for a cross reference attribute, for instance, will be a set of numeric coordinates rather than the descripton of the object you're used to seeing.
- Object Classes to Include For 'document creation' script types the values here will be automatically supplied by the script's selected markup. For the other two types you must select the object classes you want to the script to act on by checking the appropriate boxes.
- Descend Folders This setting determines whether the script will descend though nested folders. If you're using Plato to organize large documents it's often convenient to store parts of the document in seperate folders, and store all the folders in one master folder. The 'descend folders' option allows you to select only the master folder and have the script descend through all the nested folders to gather objects to format.
- Folder Levels This setting specifies how many levels of nested folders the script will descend. The maximum is 10.
- Descend Cross References This setting determines whether the script will also descend through cross references. Note that although 'descend folders' and 'descend cross references' may both be selected at the same time, cross references will be descended only when the encountered object is not a folder.
- Cross Reference settings Selects the cross reference settings for the script to use. If you haven't created any cross reference settings, press the browse button to open the cross reference settings pane and create some.
- Top Level object class The default setting is "any." Use a more specific setting when you want to force the cross reference hierarchy to begin with a particular object class.
|
|
| Find and Replace Criteria |
|
|
| Figure 4: Script Editor Find and Replace Pane |
|
This pane lets you further limit your scope by stipulating field content that must be found. It's split into two portions: a list of the criteria you've specified (on top) and a pane for editing each item on the list or adding new ones. What sort of criteria you may specify depends on the script type: for the "find and replace (no display)" type, "find and replace" criteria will apply. For the other types, only "find" criteria will apply. - Criteria list You can put as many items here as you want. When you scroll through the list, the data in the edit pane will always reflect the data for the item currently highlighted on the list. New items may be placed here by specifying the criteria in the edit pane and pressing the "add" button. To change an item already on the list, first select the item on the list, make any changes in the edit pane, and press the "change" button. To delete an item, select the item you want to delete and press the "delete" button.
- Criteria edit pane The edit pane contains the following fields:
- Object Class Select the pertinent object class here. Each find/replece criteria must apply to a single object class, however you may stipulate multiple criteria that together apply to multiple object classes.
- Select Action (and field) Select the appropriate action here. Available actions are:
- find Looks in all of an object's attributes but doen't look in notes. This action is not available to the "find and replace (no display)" script type
- find in field Looks only in a specified field (attribute). This action is not available to the "find and replace (no display)" script type
- find in note Looks only in an object's notes. This action is not available to the "find and replace (no display)" script type
- change Makes specified change in any attribute wherein the search text is found. This action is only available to the "find and replace (no display)" script type
- change in field Makes specified change on in the specified field (attribute). This action is only available to the "find and replace (no display)" script type
- Field list When the "find in field" or "change in field" action is selected, this field opens to allow you to select a field.
- Apply multiple criteria using operator If OR is selected, action will be performed if ANY of the criteria are met. If AND is selected, the action will be performed if ALL of the criteria are met. This selection is not available to the "find and replace (no display)" script type, which always uses to OR operator.
- Text to find This where you specify the text to be found. Some Plato macros can be used here.
- Change to Text placed in this field will REPLACE the found text.
|
|
| Script Output |
|
|
| Figure 5: Script Editor Output Pane |
|
This pane applies only to the script type "create formatted documents". It lets you determine where the output of the script will go. The following fields are available:- Destination Two choices: Plato's internal output window or an external program
- Plato Output Window Plato's output window can display text and RTF-formatted data and is ideal for a quick display of data. Data in the output window can be edited (though the window has minimal editing features). It can also be sent to an external program for editing.
- External program If 'external program' is selected, a drop down menu will appear to the right and allow you to select the program that will handle the output. When the script creates the output file Plato will not display it but will load the file into the designated program which will assume control.
- Output File Two choices: Plato standard output and external file
- Plato standard output Plato's standard output is a file in the output directory with a unique name tagged to the script that created it. The filename is in the form [unique script ID].[script output extension]. Here's a sample standard output file name:
20121223211345.out Standard output files can be loaded into Plato's output window or an external program. Be aware that that applications that require a dedicated file extenison for the files they process (such as TeX and LaTeX) will not recognize the standard output file because of its extension. - External file If 'external file' is selected, a field will appear to the right in which you may enter the name of the file that will contain the output. Be sure to include the path so that the file can be found later. This field will accept Plato subdirectory and internal variables but not Plato macros. To the far right of the field is a browse button; press this to browse files and paths.
|
|
| Output Format |
|
|
| Figure 6: Script Editor Markup Selection Pane |
|
This pane lets you select the markup to apply to the objects selected by the script, and is only visible to scripts of the "create formatted document" type. It has three components:- List of markup The window at the top of the pane lists all the markup contained in the database/class library. Select the markup you want to use by double clicking on a selection--an "x" will appear in the leftmost column. You may only select one set of markup.
- Invoke bookmarks check box Check this if there are bookmarks attached to the objects and there is formatting criteria for them in the markup. If the check box is unchecked bookmarks will be ignored.
- Autoenumeration selector If you want to autoenumerate the script output, select the appropriate autoenumeration markup here.
|
|
| Messages |
|
|
| Figure 7: Script Editor Message Pane |
|
This pane contains all the messages generated when the script is checked for errors. Scripts are checked interactively as you type or select/deselect things and the messages are posted here. Successful checks are in the top half; errors are posted in the orange pane at bottom. As long as errors persist, you won't be allowed to save the changes made to the script.
|
|
|