# Kst Extensions

&kst; extensions are a powerful way to add functionality to &kst;. They can, for example, add elements to the &kst; user interface. They are usually designed to accomplish specific tasks which aren't of general use to the &kst; community.

To load or unload extensions in &kst;, select Settings Extensions.... A dialog will be presented which allows you to load or unload installed plugins.

Extensions Dialog

## The ELOG Extension

The ELOG extension allows event monitors to create logbook entries on a server running the Electronic Logbook (ELOG) application. The created logbook entries can be used, for example, to remotely monitor &kst; events or to produce periodic data reports. For information on configuring and maintaining an ELOG server, please see the official ELOG Homepage. To enable the ELOG extension in &kst;, select Settings Extensions... and ensure that ELOG Extension is checked.

### Server and Logging Settings

Server and logging settings should be configured before an entry is added to a logbook. To configure logging settings, select Settings ELOG... or click the Configure... button in the ELOG Entry dialog accessed from either File Add ELOG Entry... or the Event Monitor dialog if ELOG functionality is enabled for an event monitor object. The following dialog should be displayed:

Event Monitor Server Settings
Event Monitor Server Settings

Descriptions of the settings in this dialog follow.

Configuration, Save, and Load

  The Configuration drop down list contains a list of saved ELOG server configurations. To load a set of configuration settings, select an item from the list and click the Load button. To save the current configuration settings in this dialog into a slot, select the desired slot and click the Save button.

  Saving settings into a slot overwrites any existing settings in that slot.

IP address and Port number

  Enter the IP address of the machine running the ELOG server application. The port number that the ELOG server listens on is configurable through the server, but by default it is 8080, so if you are unsure, enter 8080 as the port number.

Logbook

  Each ELOG server can contain one or more logbooks, so the name of the logbook to write entries to must be specified. Ensure that the spelling of the logbook name is correct.

User name, User password, and Write password

  Depending on the how the ELOG server application is configured, these settings may or may not be necessary. If they are, enter the correct login credentials in the appropriate textboxes.

Capture size

  Use this list box to select the size, in pixels, of the &kst; screen capture to attach (if specified).

Submit as HTML text

  If this checkbox is selected, HTML tags may be used in the logbook entry.

Suppress e-mail notification

  If the logbook is configured to send e-mail notifications of new entries, selecting this checkbox will disable the notifications. Note that this option is not related to &kst;'s own e-mail notification setting for event monitors.

Apply

  Click the Apply button to apply the entered settings.

Update

  Click Update to update the ELOG Event Entry dialog.

Close

  Click Close to exit the dialog.

### Add an ELOG Entry

To add an entry to the logbook, choose File Add ELOG Entry... This brings a dialog allowing the user to provide information for attributes as well as entering the contents for the log message. The types of attributes depend on the logbook you specified. The screenshot below shows one example of possible required attributes.

Adding an Entry
Adding Entry

Logged Information

  Use the three checkboxes at the bottom to select the type of information to be logged.

  - Include Kst capture specifies that a screen capture of the currently active window should be included in the entry.

  - Include Kst configuration file specifies that `*.kst` save file should be attached to the entry.

  - Include Kst debugging information is checked, a copy of the debug log will be attached to the entry as well.

Configuration...

  Clicking Configuration... brings the ELOG Configuration dialog. See the Server and Logging Settings section for details.

Submit

  Click Submit to submit the log entry.

Cancel

  Click Cancel to close the dialog without posting the log entry.

When the ELOG functionality is enabled for an Event Monitor object, clicking the Configure... button in the New Event Monitor dialog will bring the ELOG Event Entry dialog. In this dialog, the user can enter information for logbook attributes; again, the types of attributes depend on the logbook configured in the ELOG configuration dialog.

Event Monitor Logging Settings
Event Monitor Logging Settings

Logged Information

  See explanation above.

Configuration...

  See explanation above.

Test

  This button is used to test the ELOG configuration. If the user-specified logbook is configured correctly, clicking Test will post a test message:Test of Event ELOG Entry in the logbook.

Close

  Click Close to close the dialog.

### ELOG Browser

To view existing logbooks through Kst, choose File Launch ELOG Browser....

Launch ELOG Browser
ELOG Browser

To quickly view the ELOG browser and add an entry to a logbook, just click the ELOG Browser in the toolbar to launch the ELOG browser and Entry Icon to add an ELOG entry.

### Using the ELOG Class in KstScript

Alternatively, you can use the ELOG class provided in KstScript to enter and submit messages in a logbook and change the server and logging settings. See details in the ELOG class documentation.

#### Adding an ELOG entry through KstScript

    elog = new ELOG(); 			//construct a new ELOG object
    elog.port = 8080; 			//specify the port
    elog.hostname = "localhost"; 		//specify the hostname;
    elog.logbook = "demo"; 			// specify the logbook;
    elog.text = "message contents"; 	//enter the message;
    elog.addAttribute("Author", "Kst");
    elog.addAttribute("Type", "Routine");

    elog.submit();

## KstScript

KstScript is a JavaScript binding for &kst;. It aims to offer full control over all aspects of &kst;. To enable KstScript, select Settings Extensions... and ensure that JavaScript Extension is checked.

### Running a KstScript

There are three ways to to run a KstScript.

- from the command line when starting &kst;:

      kst -E js:"loadScript('myscript.js')"

- using kstcmd. kstcmd is a JavaScript interpreter which connects to your &kst; session. It can be run from an external terminal, or from within &kst; itself by selecting Tools Show JavaScript Console.

      kstcmd
      Attached to Kst session kst-17704
      kst> loadScript('myscript.js')

- from the menu once &kst; is loaded: File LoadJavaScript

Note that with the first two methods, any KstScript command, or collection of KstScript commands can be substituted for the loadscript command.

### KstScript Examples

KstScript gives &kst; a powerful programming interface. Chiefly, it can be used to construct smart macro functions for common tasks. We will first look at a basic example illustrating how to control &kst; through KstScript, and then we will look at an example of a macro function.

#### A simple KstScript

Here we have the hello world of KstScripts: plot a curve of random numbers.

    // simple.js: A simple KstScript demo.
    // Generates a new plot with a curve of random numbers.

    // grab the window
    var w = Kst.windows[0];

    // add a plot to the window
    var p = new Plot(w);

    // create new (editable) vectors.
    // these could also be loaded from files.
    var xv = new Vector(); var yv = new Vector();

    xv.tagName = "time"; yv.tagName = "signal";

    // make their length 100.
    xv.resize(100); yv.resize(100);

    // fill in their values.
    for (var i = 0; i < 100; i++) {
            xv[i] = i; //index
            yv[i] = Math.random(); //uniformly distributed between 0 and 1.
    }

    // create a curve from x and y
    var c = new Curve(xv,yv);
    c.tagName = "signalvstime";

    // put the curve in our new plot
    p.curves.append(c);

    // label the x-axis of our plot
    p.xAxis.label = "Time (s)"

This script can be run using any of the methods from . Here is a screenshot of &kst; after entering the commands using the embedded console method.

Simple Output

In the &kst; UI, objects are not labelled by the variable names which we use in our KstScript, but are are referred to by their Tag Name (or "Unique Name"). If you do not manually set the tagName attribute of new objects, then when you look things up in the data manager you will find cryptic names like anonymous vector 1, or, . This is the reason why we received several undefined messages in the screenshot above. If you ever plan to use the UI to work with objects you have created with a KstScript, you will want to set their tagName property. You can also use tag names within KstScript itself. For example, after setting the tagName of our new curve we could have called

    p.curves.append("signalvstime");

#### Writing, Including, and Calling Functions

As with any JavaScript environment, you can write and call functions with KstScript. Additionally, KstScript possesses a means for a KstScript to load functions from disk. Consider the following example:

    // subroutines.js

    function takeSpectraOfTimePlots() {
    //takes all of the plots in the first window which have an x-axis of "Time (s)"
    // and generates power spectra for their curves, which it dumps into a single new
    // plot.
            var w = Kst.windows[0];
            var p = new Plot(w);
            p.xAxis.label = "Frequency (Hz)"

            for (var ip = 0; ip < w.plots.length; ip++ ) {
                    cp = w.plots[ip]; //current plot
                    if (cp.xAxis.label == "Time (s)") {
                            for (ic = 0; ip < cp.curves.length; ic++) {
                                    plotSpectrum(p,cp.curves[ic].yVector)
                            }
                    }
            }
    }

    function plotSpectrum(p,v) {
    //creates a power spectrum for the vector v and displays it in plot p. Assumes
    //the vector is data sampled at 1Hz.
            ps = new PowerSpectrum(v, 1);
            ps.tagName = v.tagName + "-PS";
            c = new Curve(ps.xVector,ps.yVector);
            c.tagName = ps.tagName + "-C";
            p.curves.append(c);
    }

This example contains two functions: `takeSpectraOfTimePlots()` and `plotSpectrum(p,v)`. takeSpectraOfTimePlots() is a macro function which will generate spectra for all of the plots in the first window which have "Time (s)" as their x-axis. In this example, we can see the power of KstScript for such tasks.

The following script loads these routines from the `subroutines.js`. It uses the `simple.js` of the previous section to generate a noise plot with a time axis, and then calls takeSpectraOfTimePlots() to find its spectrum. Notice that `subroutines.js` is loaded using `loadScript()`, the same call that we used from the command line in .

    // callsubs.js
    // demonstrate calling subroutines

    loadScript('subroutines.js');
    loadScript('simple.js');

    takeSpectraOfTimePlots();

A screenshot of &kst; after executing these commands is shown below.

CallSubs Output

### More KstScript Documentation

Complete documentation on the KstScript classes is given in Appendix D.