<chapter id="extensions">
<title>Kst Extensions</title>
<para>
&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.
</para>
<para>
To load or unload extensions in &kst;, select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Extensions...</guimenuitem></menuchoice>. A dialog will be presented which allows you to load or unload installed plugins.
</para>
<screenshot>
<screeninfo>Extensions Dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-extensions-dialog.png" format="PNG" />
</imageobject>
</mediaobject>
</screenshot>
<sect1 id="extensions-elog">
<title>The ELOG Extension</title>
<para>
The ELOG extension allows <link linkend="data-types-eventmonitors">event monitors</link> 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 <ulink url="http://midas.psi.ch/elog/">ELOG Homepage</ulink>. To enable the ELOG extension in &kst;, select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Extensions...</guimenuitem> </menuchoice> and ensure that <guilabel>ELOG Extension</guilabel> is checked.
</para>
<sect2 id="extensions-elog-settings">
<title>Server and Logging Settings</title>
<para>
Server and logging settings should be configured before an entry is added to a logbook. To configure logging settings, select <menuchoice><guimenu>Settings</guimenu> <guimenuitem>ELOG...</guimenuitem></menuchoice> or click the <guibutton>Configure...</guibutton> button in the <guilabel>ELOG Entry</guilabel> dialog accessed from either <menuchoice><guimenu>File</guimenu><guimenuitem>Add ELOG Entry...</guimenuitem></menuchoice> or the <link linkend="data-types-eventmonitors">Event Monitor dialog</link> if ELOG functionality is enabled for an event monitor object. The following dialog should be displayed:
</para>
<screenshot>
<screeninfo>Event Monitor Server Settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-extensions-elog-serversettings.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Event Monitor Server Settings</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
Descriptions of the settings in this dialog follow.
</para>
<variablelist>
<varlistentry>
<term>
<guilabel>Configuration</guilabel>, <guibutton>Save</guibutton>, and <guibutton>Load</guibutton>
</term>
<listitem>
<para>
The <guilabel>Configuration</guilabel> 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 <guibutton>Load</guibutton> button.
To save the current configuration settings in this dialog into a slot, select the desired slot and click the
<guibutton>Save</guibutton> button.
</para>
<caution>
<para>
Saving settings into a slot overwrites any existing settings in that slot.
</para>
</caution>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>IP address</guilabel> and <guilabel>Port number</guilabel></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Logbook</guilabel></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>User name</guilabel>, <guilabel>User password</guilabel>, and <guilabel>Write password</guilabel></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Capture size</guilabel></term>
<listitem>
<para>
Use this list box to select the size, in pixels, of the &kst; screen capture to attach (if specified).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Submit as HTML text</guilabel></term>
<listitem>
<para>
If this checkbox is selected, HTML tags may be used in the logbook entry.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Suppress e-mail notification</guilabel></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Apply</guilabel></term>
<listitem>
<para>
Click the <guibutton>Apply</guibutton> button to apply the entered settings.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Update</guilabel></term>
<listitem>
<para>
Click <guibutton>Update</guibutton>
to update the <link linkend="extensions-elog-entry"><guilabel>ELOG Event Entry</guilabel> dialog</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Close</guilabel></term>
<listitem>
<para>
Click <guibutton>Close</guibutton> to exit the dialog.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="extensions-elog-entry">
<title>
Add an ELOG Entry
</title>
<para>
To add an entry to the logbook, choose <menuchoice><guimenu>File</guimenu><guimenuitem>Add ELOG Entry..</guimenuitem></menuchoice>.
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.
</para>
<screenshot>
<screeninfo>Adding an Entry</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-extensions-elog-addentry.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Adding Entry</phrase>
</textobject>
</mediaobject>
</screenshot>
<variablelist>
<varlistentry id= "logged-info">
<term>Logged Information</term>
<listitem>
<para>
Use the three checkboxes at the bottom to select the type of information to be logged.
<itemizedlist>
<listitem><para>
<guilabel>Include Kst capture</guilabel> specifies that a screen capture of the
currently active window should be included in the entry.
</para></listitem>
<listitem><para>
<guilabel>Include Kst configuration file</guilabel>
specifies that <filename>*.kst</filename> save file should be attached to the entry.
</para></listitem>
<listitem><para>
<guilabel>Include Kst debugging information</guilabel> is checked, a copy of the
<link linkend="settings-debuglog">debug log</link> will be attached to the entry as well.
</para></listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry id="configuration">
<term><guilabel>Configuration...</guilabel></term>
<listitem><para>
Clicking <guilabel>Configuration...</guilabel> brings the <guilabel>ELOG Configuration</guilabel> dialog. See the <link linkend="extensions-elog-settings">Server and Logging Settings</link> section for details.
</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Submit</guilabel></term>
<listitem><para>
Click <guilabel>Submit</guilabel> to submit the log entry.
</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Cancel</guilabel></term>
<listitem><para>
Click <guilabel>Cancel</guilabel> to close the dialog without posting the log entry.
</para></listitem>
</varlistentry>
</variablelist>
<para>When the ELOG functionality is enabled for an <link linkend="data-types-eventmonitors">Event Monitor object</link>, clicking the <guilabel>Configure...</guilabel> button in the <guilabel>New Event Monitor</guilabel> dialog will bring the <guilabel>ELOG Event Entry</guilabel> 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.
</para>
<screenshot>
<screeninfo>Event Monitor Logging Settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-extensions-elog-loggingsettings.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Event Monitor Logging Settings</phrase>
</textobject>
</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
<term>Logged Information</term>
<listitem>
<para>
<link linkend="logged-info">See explanation above</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Configuration...</guilabel></term>
<listitem><para>
<link linkend="configuration">See explanation above</link>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Test</guilabel></term>
<listitem><para>
This button is used to test the ELOG configuration. If the user-specified logbook is configured correctly, clicking <guilabel>Test</guilabel> will post a test message:<quote>Test of Event ELOG Entry</quote> in the logbook.
</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Close</guilabel></term>
<listitem><para>
Click <guilabel>Close</guilabel> to close the dialog.
</para></listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="extensions-elog-browser">
<title>ELOG Browser</title>
<para>
To view existing logbooks through Kst, choose <menuchoice><guimenu>File</guimenu><guimenuitem>Launch ELOG Browser...</guimenuitem></menuchoice>.
</para>
<screenshot>
<screeninfo>Launch ELOG Browser</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-extensions-elog.png" format="PNG" />
</imageobject>
<textobject>
<phrase>ELOG Browser</phrase>
</textobject>
</mediaobject>
</screenshot>
<tip>
<para>
To quickly view the ELOG browser and add an entry to a logbook, just click the <inlinemediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-extensions-elogbrowsericon.png" format="PNG" />
</imageobject>
<textobject>
<phrase>ELOG Browser</phrase>
</textobject>
</inlinemediaobject>
in the toolbar to launch the ELOG browser and
<inlinemediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-extensions-elogentryicon.png" format="PNG" />
</imageobject>
<textobject>
<phrase>Entry Icon</phrase>
</textobject>
</inlinemediaobject>
to add an ELOG entry.
</para>
</tip>
</sect2>
<sect2 id="extensions-using-elog-class">
<title>Using the ELOG Class in KstScript</title>
<para>
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 <link linkend="class_ELOG">ELOG class documentation</link>.
</para>
<example id="Elog-class-eg">
<title>Adding an ELOG entry through KstScript</title>
<programlisting>
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();
</programlisting>
</example>
</sect2>
</sect1>
<sect1 id="extensions-kstscript">
<title>KstScript</title>
<para>
KstScript is a JavaScript binding for &kst;. It aims to offer full control over all aspects of &kst;. To enable KstScript, select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Extensions...</guimenuitem></menuchoice> and ensure that <guilabel>JavaScript Extension</guilabel> is checked.
</para>
<sect2 id="kstscriptrunning">
<title>Running a KstScript</title>
<para>
There are three ways to to run a KstScript.
</para>
<itemizedlist>
<listitem> <para>
from the command line when starting &kst;:
<screen><userinput><command>kst -E js:"loadScript('myscript.js')"</command></userinput></screen>
</para> </listitem>
<listitem> <para>
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 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Show JavaScript Console</guimenuitem></menuchoice>.
<screen><userinput><command>kstcmd</command>
</userinput>Attached to Kst session kst-17704
kst> <command>loadScript('myscript.js')</command>
</screen>
</para> </listitem>
<listitem> <para>
from the menu once &kst; is loaded: <menuchoice><guimenu>File</guimenu><guimenuitem>LoadJavaScript</guimenuitem></menuchoice>
</para> </listitem>
</itemizedlist>
<para>
Note that with the first two methods, any KstScript command, or collection of KstScript commands can be substituted for the loadscript command.
</para>
</sect2>
<sect2 id="kstscriptexamples">
<title>KstScript Examples</title>
<para>
KstScript gives &kst; a powerful programming interface. Chiefly, it can be used to construct <quote>smart</quote> 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.
</para>
<sect3 id="kstscriptexample">
<title>A simple KstScript</title>
<para>
Here we have the <quote>hello world</quote> of KstScripts: plot a curve of random numbers.
</para>
<para> <screen>
// 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)"
</screen></para>
<para>
This script can be run using any of the methods from <xref linkend="kstscriptrunning"/>. Here is a screenshot of &kst; after entering the commands using the embedded console method.
</para>
<screenshot>
<screeninfo>Simple Output</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-extensions-kstscriptexample.png" format="PNG"/>
</imageobject>
<textobject>
<phrase></phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
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 <quote>anonymous vector 1</quote>, or, <quote></quote>. This is the reason why we received several <quote>undefined</quote> 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
<screen>
p.curves.append("signalvstime");
</screen>
</para>
</sect3>
<sect3 id="kstscriptsubroutines">
<title>Writing, Including, and Calling Functions</title>
<para>
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:
</para>
<para> <screen>
// 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);
}
</screen> </para>
<para>
This example contains two functions: <command>takeSpectraOfTimePlots()</command> and <command>plotSpectrum(p,v)</command>. 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.
</para>
<para>
The following script loads these routines from the <filename>subroutines.js</filename>. It uses the <filename>simple.js</filename> of the previous section to generate a noise plot with a time axis, and then calls takeSpectraOfTimePlots() to find its spectrum. Notice that <filename>subroutines.js</filename> is loaded using <command>loadScript()</command>, the same call that we used from the command line in <xref linkend="kstscriptrunning"/>.
</para>
<para> <screen>
// callsubs.js
// demonstrate calling subroutines
loadScript('subroutines.js');
loadScript('simple.js');
takeSpectraOfTimePlots();
</screen> </para>
<para>
A screenshot of &kst; after executing these commands is shown below.
</para>
<para>
<screenshot>
<screeninfo>CallSubs Output</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="Screenshot-kst-extensions-kstscriptsubroutinesexample.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>
</para>
</sect3>
</sect2>
<sect2 id="kstscriptmoreinfo">
<title>More KstScript Documentation</title>
<para>
Complete documentation on the KstScript classes is given in <link linkend="script-chapter">Appendix D</link>.
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:true
sgml-parent-document:("index.docbook" "book" "chapter")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
