ImplementingResponseFrames

Implementing Response Frames

Introduction

Response frames are frames that can be used to present the user with a form to complete. This form can then be processed by a program external to Telstar. The results of the external program are automatically passed back to Telstar for presentation to the user etc.

Frame Definition

The response frame has a type of response (see Frames) e.g.

"frame-type": "information",

In addition the response-data and response-action elements should also be completed. Below is an example of a response frame used for the Telstar weather page.

"response-data": {
    "response-fields": [
        {
            "vpos": 8,
            "hpos": 4,
            "required": true,
            "length": 16,
            "type": "alphanumeric",
            "auto-submit": false,
            "password": false
        }
    ],
    "response-action": {
        "exec": "/opt/telstar/volume/telstar-openweather-linux-amd64",
        "args": [
            "myopenweatherapikey"
        ],
        "post-action-frame": {
            "page-no": 290,
            "frame-id": "c"
        }
    }
},

response-data

The response-data section above shows the definition for a single response field. This field will be presented to the user for completion at positions vpos, hpos on the frame. The field has the required attribute set to true which means that it must be completed in order to continue and the field's type is alphanumeric. Other possible field types include numeric and alpha.

The length of the field is set at 16 which means that a maximum of 16 characters can be entered. If the auto-submit had been set to true then entering the 16th character would have either moved the cursor to the next field, had there been one, or in this case where there are no other fields, submit the form.

Setting password to true would ensure that it is not displayed on the screen as it is entered.

response-action

The response-action section of the frame definition determines what happens when the user submits the form. In the example above, the exec setting causes a binary file (telstar-openweather-linux-amd64), stored in the containers volume directory, to be executed with a single argument (myopenweatherapikey). This program outputs a collection of pages in json format. Any application or script that is executed should output either a single page or multiple pages. These will get captured by Telstar and placed into temporary store.

In the case above post-action-frame is set to 290b, in this example frame 290b is output by the program telstar-openweather-linux-amd64 along with 290c, 290d and so on. These contain the weather forcast and are captured by Telstar and placed in temporary store. The user is then directed to 290b and is presented with the weather.

The binary file telstar-openweather-linux-amd64 is a custom program designed to retrieve weather information from the Openweather service. When implementing response frames this would be replaced with whatever action was required. This could be a binary program as in the above example, a python program or perhaps a bash script.

Adding the External Program to the Container

To copy a custom program or script file to the container for use with a response frame, the following Docker copy command can be used:

docker cp mycustomprogram mycontainername:/opt/telstar/volume

The above command assumes that the volume path is set at its default value. See Configuration Options.