Include-Text Field

GoFiler Legato Script Reference

Legato v 1.5d

Application v 5.25a

Table of Contents	< < Previous	Next >>

Chapter Twenty — PageView Integration (continued)

Include-Text Field

Overview

This section describes the field interface for the Include-Text field type. When encountered during a publish or field update function, and the included file has a .ls extension, the field processor will call the associated script. The script can then return HTML data to be incorporated into the referencing file.

Field Syntax/Parameters

Syntax

Parameters

File

A name of the script file. If the filename is not qualified, processor will scan for the file in th following order: referencing file’s folder; the user extensions folder; the application script extensions folder; and, finally the application scripts folder.

Date

This value is used by the field processor to indicate whether and field is out of date. It will contain the modified date and time of the script and is superfluous to script include fields.

Size

This value is used by the field processor to indicate whether and field is out of date. It will contain the size the script and is superfluous to script include fields.

Name

The name of the function to call to generate the data for the script. Avoid using the name ‘main’ since it typically has no parameters. See Remarks below.

Range

String data that is passed to the target script.

Options

String data that is passed to the target script. This is specifically setup for resources and editing. The values will be a combination of ‘NoResources’ and ‘AllowEdit’.

Data

String data that is passed to the target script.

Note that the Include-Text field must also have a pair closing /Include-Text field.

Script Prototype

As a field is processed during insert or update, the specified hook is called using the name provided in the Text-Include field:

Prototype

string name(string reference, string options, string range, string data) { ... }

Parameters

reference

A string containing the qualified name of the referencing file.

options

A string containing the options value from the referencing field.

range

A string containing the range value from the referencing field.

data

A string containing the data value from the referencing field.

Return Value

The script hook is expected to return a string with properly formatted HTML code or simple PCDATA. If the type is not a string, it will be converted to string format. This value is then placed in the include are of the referencing file.

Remarks

If the script contains or encounters a runtime error, it will insert a script error with the associated syntax error code. It is generally a good idea to use ‘main’ to establish a test jig for debugging purposes rather than trail and error during field publish.

With the exception of displaying a progress window, scripts should avoid displaying data or querying the user since it will halt the field update process.

Depending on the application, the include-text field can be added or edited using functions located on the Document ribbon.

Example:

The following is a simple example of a script hook on a include-text field. First the reference:

<!-- Field: Include-Text; File: Field Include%2DText 01.ls; Date: 2017%2D02%2D16T12:29:24; 
     Size: 1628; Options: AllowEdit; Name: myhook; Range: 123%2D456; Data: Some Data -->

Then the sample hook:

string myhook(string reference, string options, string range, string data) { 

    string       s1;

    s1  = "<P STYLE=\"font: 10pt Sans-Serif; margin-top: 3pt; margin-top: 6pt; ";
    s1 += "border: 1pt blue solid; padding: 3pt\">";
    s1 += "<B>Run Date:</B> " + GetLocalTime(DS_MONTH_DAY_YEAR | 
                                             DS_DATE_AT_TIME | DS_HHMMSS_24) + "<BR>\r";
    s1 += "<B>Parameters:</B><BR>\r";
    s1 += "&nbsp;&nbsp;&nbsp;&nbsp;Reference: " + reference + "<BR>\r";
    s1 += "&nbsp;&nbsp;&nbsp;&nbsp;Options: " + options + "<BR>\r";
    s1 += "&nbsp;&nbsp;&nbsp;&nbsp;Range: " + range + "<BR>\r";
    s1 += "&nbsp;&nbsp;&nbsp;&nbsp;Data: " + data + "<BR>\r";
    s1 += "<B>Script:</B><BR>\r";
    s1 += "&nbsp;&nbsp;&nbsp;&nbsp;Parent: " + GetScriptParent() + "<BR>\r";
    s1 += "&nbsp;&nbsp;&nbsp;&nbsp;Script Name: " + GetScriptName() + "<BR>\r";
    s1 += "&nbsp;&nbsp;&nbsp;&nbsp;Script File: " + GetScriptFilename() + "<BR>\r";
    s1 += "&nbsp;&nbsp;&nbsp;&nbsp;Script Folder: " + GetScriptFolder() + "</P>";

    return s1;
    }

When the field is updated, one would have something like this (additional data added):