Wiki

Clone wiki

telstar-server / telstar_plugins

Telstar Plugins

Please note TELSTAR as an application is still under development and subject to change.

Whilst there are several ways to add frames to a TELSTAR based videotex system, one such way is to use the telstar.frame object in conjunction with a plugin programmed in python.

Telstar plugins are simply python files that contain one or more functions. These functions can be called from Telstar at specific points in the servers life cycle. Each funtion is decorated with a specific Telstar decorator to indicate when it should be run. For example the following example a function is decorated with the @telstar.init decorator which means that it will be called before the server starts but only if the --init command line argument has been specified.

Plugins are stored in the plugin directory which, by default is the /opt/telstar/volume/plugins directory within the container. Creating the persistent Docker volume during initial configuration (see above) means that the /opt/telstar/volume/plugins directory will be mapped to the pluging directory of the volume thereby allowing plugins to be persisted irrespective of the state of the Telstar container.

Creating a Plugin to Add Content

To create a plugin called my_plugin create a folder in the plugins directory within the running container called my_plugin (see Deploying Plugins below). e.g.

    /opt/telstar/volume/plugins/my_plugin

Within the newly created plugin directory (my_plugin in this example) create a file called __init__.py. The example shown below will create the following frame.

example_plugin 500.png

Note: there is no harm in running this plugin function multiple times, it will simply update the database each time it is run as there can only be one frame with the ID 101a. It will not create extra frames.

# /opt/telstar/volume/plugins/example_plugin/__init__.py

import os
import telstar
import ntpath

logger = telstar.getlogger(__name__)

@telstar.init
def initialise(*args):

    page_no = 101
    frame_id = "a"

    try:
        # system settings are available from args[0]
        settings = args[0]

        # create the data access layer
        dal = telstar.Dal(settings["dbcon"])

        logger.info('Creating an example frame')

        title = "{0}Welcome to Telstar Videotex\r\n\r\n".format(telstar.k_controls["double_height"])
        content = []
        content.append("{0}{1}\r\n".format(telstar.k_controls["mosaic_yellow"], telstar.k_separator_graphics["dots"]))
        content.append('{0}This is a sample page created using a'.format(telstar.k_controls["alpha_cyan"]))
        content.append('{0}frame document and whilst it is a very'.format(telstar.k_controls["alpha_cyan"]))
        content.append('{0}simple example, there are other ways.'.format(telstar.k_controls["alpha_cyan"]))
        content.append('{0}to accomplish the same thing.\r\n'.format(telstar.k_controls["alpha_cyan"]))

        content.append('{0}One such way is to use the videotex'.format(telstar.k_controls["alpha_magenta"]))
        content.append('{0}editor at... \r\n'.format(telstar.k_controls["alpha_magenta"]))
        content.append('{0}          {1}https//:edit.tf\r\n\r\n'.format(telstar.k_controls["alpha_yellow"], telstar.k_controls["flash"]))
        content.append('     Press 9 for System Information')

        # create a default routing table
        routing_table = telstar.frame_document.create_default_routing_table(page_no)

        # create a new frame document
        frame_doc = telstar.frame_document.create_doc(page_no=page_no, frame_id=frame_id,
                                                  frame_type=telstar.InformationFrame,
                                                  content_data=content, content_type="markup",
                                                  title_data=title, title_type="markup",
                                                  author_id="example-plugin", routing_table=routing_table,
                                                  static_page=True,
                                                  )

        # determine whether we are using the primary or secondary data collection
        is_primary = settings["dbcollection"] == "primary"

        # store in the database
        dal.insert_document(frame_doc, is_primary)

    except Exception as ex:
        logger.exception(ex)

In this example __init__.py includes a function called initialise which is decorated with the •telstar.init decorator. As previously stated this function will be automatically run just before the videotex server starts as long as the --init command line argument is specified.

Once the frame has been created it can be accessed by navigating to page 101 using a vidoetex client.

Using the Edit.tf Videotex Editor

The https//:edit.tf video text editor can be used to create pages for a telstar based system Telstar. The editor is access via a web browser and the edited data is available in the url.

edit.tf.700.png

Note that the editor is designed for both teletext and interactive videotex which means that it allows for up to 25 lines of 40 character text. However, interactive videotex such as Prestel and Telstar use 24 lines by 40 characters. this means that the last row will not be displayed. In additiona Telstar software makes use of the first row (row 1) for the header which means anything placed in that row will be overwritten. Within the Telstar system messages are normally placed in row 24 and navigation is usually displayed on row 23. This means that in most cases rows 2 to 22 are available for content.

The following example plugin creates the frame shown below directly from the url of the edit.tf editor.

main_index_plugin.png

# /opt/telstar/volume/plugins/example_plugin/__init__.py

import os
import telstar
import ntpath

logger = telstar.getlogger(__name__)

@telstar.init
def initialise(*args):

    # Create the frame 101b
    page_no = 101
    frame_id = "b"

    try:
        # system settings are available from args[0]
        settings = args[0]

        # using the edit.tf url for the data
        content = "https://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uiDDuyINu_llXLlyBAgQMkE6LXpoIM6IgrxYNSRFpAp2Hpp37sOxBh3ZECBAgQIECAEgQad3TLy3Yemnfuw7EG7L35oMO7Ig75cPTRl5LkCBAgQIEDNBCq05M6LTpoJM6NPpTYNSTPnAoe_bww7vKDDuyIECBAgBIEGLrz07svPmg3Ze_NcDOhI1SnFQTMPTLz6IKHLTjy80CBA0QR59aLSnTYs6ogkzo0-lNg1JM-cgQIECBAgQIECBAgQIEDVBUpQY0aTDQUotCfSqUwU3Dq38kHLfhyIOWXhv5dOaBAgBIEGblv2oJGnPo74fPNBF3Z9mHdkXIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQIqZdmXnvzdO-HllE4d2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA"

        # create the data access layer
        dal = telstar.Dal(settings["dbcon"])
        logger.info('Creating an example frame')

        # Create a custom header row, the letters in square brackets define the colours
        # this example defines the header as 'PRESTEL' with each colour being different
        header_text = "[G]P[R]R[C]E[B]S[W]T[M]E[R]L"

        # create a default routing table
        routing_table = telstar.frame_document.create_default_routing_table(page_no)

        # create a new frame document
        frame_doc = telstar.frame_document.create_doc(page_no=page_no, frame_id=frame_id,
                                                      frame_type=telstar.InformationFrame,
                                                      content_data=content, content_type="edit.tf",
                                                      title_data="", title_type="",
                                                      author_id="example-plugin", routing_table=routing_table,
                                                      static_page=True, header_text=header_text
                                                      )

        # determine whether we are using the primary or secondary data collection
        is_primary = settings["dbcollection"] == "primary"

        # store in the database
        dal.insert_document(frame_doc, is_primary)

    except Exception as ex:
        logger.exception(ex)

Note that in this example a custom header row is created.

In each of the plugins described above, the standard default routing table was used. This default setting sets things up so that if a user is viewing page 9 and presses 1, page 91 will be selected. If the page exists it will be loaded in place of page 9. For further details on routing see Routing.

Using Plugins as part of a Cron Job

Plugins are ideal to update frames periodically. For example where data is being supplied by a news feed of some kind. By using the decorator telstar.cron instead of the decorator telstar.init as used in the above examples a simple cron job can be set up to run the plugin. For example the following Docker command will run all plugin methods that are decorated with the decorator telstar.cron.

$ docker run -d --network telstar-network -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar cron

If only a specific plugin was required to run e.g. myplugin then the following command can be used.

$ docker run -d --network telstar-network -v telstar-volume:/opt/telstar/volume johnnewcombe/telstar cron myplugin

Note that in each of the above cases only the methods marked with the decorator telstar.cron will be run. In addition, the --rm (remove) flag is not specified, this means that when the container ends, it remains avalable in order that the logs can be viewed.

Deploying Plugins

Telstar Plugins need to be copied to the /opt/telstar/volume/plugins directory within the running Telstar container.

The example Docker command below assumes the current directory contains one or more plugins to be deployed and that the running container is called telstar-server.

docker cp . telstar-server:/opt/telstar/volume/plugins

Updated