Sednterp User Modules

Sednterp Web and Desktop can load user created modules, written in HTML and Javascript. Both Sednterp Web and Desktop provide an editable display which the user has complete control of and platform tools to help create the module in the form of developer tools. The Sednterp distribution comes with an example module which can be edited so users can use it as a base to create their own modules.

This page shall provide documentation on how to create a user module from scratch.

The basic underlying tool you will need to know is JavaScript, you should not need to be an expert but some underlying fundamentals should be enough to create your own module.

First to create your own module you will need to place it in modules/QtScript under where you have Sednterp installed on your system. If you used the windows installer to install Sednterp you will most likely be able to find it in C:\Program Files\Sednterp

Therefore you should be saving your created modules in C:\Program Files\Sednterp\modules\QtScript

Your module file will be broken up into two parts JavaScript and HTML for the UI.

Part one: JavaScript

JavaScript is the language you will use that will do all most all of the heavy lifting in your module before we get started on Sednterp specific features of JavaScript here a few links for referencing basic vanilla JavaScript.

JavaScript Tutorial

JavaScript Reference

Your JavaScript module will need to include the following 6 different functions

 /* Required Accessor Functions */
 function getModuleName()
 {
   return "ModuleName";
 }
 function getModuleVersion()
 {
   return "20120604";
 }
 function getModuleInteractionXml()
 {
   return "No Interactions";
 }
 function getModuleDate()
 {
   return "2010/06/22";
 }
 function getModuleUI()
 {
   return "qt_sednterp.ui";
 }
 function getModuleHTMLUI()
 {
   return "./modules/QtScript/module1.html";
 }

This is all you should need for Sednterp to recognize your module and try to load it.

When creating your own module you will need to edit this code. The function getModuleName tells sednterp the name of your unique module, the function getModuleVersion tells sednterp the version number of the module, getModuleHTMLUI tells sednterp the full path location of your HTML Module UI you need to be careful when you set it otherwise your module will not load properly in the desktop version of sednterp. The module path should relative location of HTML file from the location where Sednterp is installed on your system. The other functions don't have a particular use yet however they are still necessary for sednterp to run your module so just leave them as the are.

Here is a copy of an example module for you to play with, the accompanying HTML UI will discussed in part two.

Copy the following JavaScript text into a plain text editor and save it to the directory module/QtScript

// Viscosity of water at 20*c
var N_20_W = 1.002;
// Density water at 20*C (Rho)
var Density_20_Water = 0.998234;
var Rho_Water = Density_20_Water;
// Viscosity of water at 20C (Vis)
var Viscosity_20_Water = 0.01002;
// PI as defined in original sednterp
var PI = 3.1415926536;
function getModuleName()
{
   return "ExampleModule";
}
function getModuleVersion()
{
   return "20120215";
}
function getModuleInteractionXml()
{
   return "No Interactions";
}
function getModuleDate()
{
   return "2010/06/22";
}
function getModuleUI()
{
   return "qt_sednterp.ui";
}
function getModuleHTMLUI()
{
   return "./modules/QtScript/module1.html";
}
function _RhoTKell(T)
{
   T       = parseFloat(T);
   var denom = 1 + 0.01687985 * T;
   var term1 = 999.83952 + 16.945176 * T;
   var term2 = (0.0079870401 * T) * T + 0.000046170461 * T * T * T;
   var term3 = 0.00000010556302 * T * T * T *
       T - (((2.8054253 * Math.pow(10, -10)) * T) * T * T * T * T);
   return 0.001000028 * (term1 - term2 + term3) / denom;
}
function _calculateDensityAtT(T, Density)
{
   Density = parseFloat(Density);
   return Density * _RhoTKell(T) / _RhoTKell(20);
}
function correctBufferDensityAtT_Heavy(density, temperature, D2O, D2O18, H2O18)
{
   density = parseFloat(density.VALUE);
   var T = parseFloat(temperature.VALUE);
   D2O       = parseFloat(D2O.VALUE);
   D2O18     = parseFloat(D2O18.VALUE);
   H2O18     = parseFloat(H2O18.VALUE);
   var delrho   = 0;
   var rhowater = _calculateDensityAtT(T, Density_20_Water);
   if (D2O > 0)
       delrho = delrho + D2O * (_CalcRhoD2OAtT(T) - rhowater);
   if (D2O18 > 0)
       delrho = delrho + D2O18 * (_CalcRhoD2O18AtT(T) - rhowater);
   if (H2O18 > 0)
       delrho = delrho + H2O18 * (_CalcRhoH2O18AtT(T) - rhowater);
   var obj = new Object();
   obj.NAME = "qtCorrectedDensity";
   obj.VALUE = density * rhowater / Density_20_Water + delrho;
   return obj;
}
function _CalcRhoD2OAtT(T)
{
   return 1.10602 * (1 - 1.0555 * Math.pow((T - 11.24), 2) *
                     (1.74224 + 482.502 / (T - 11.24 + 77.861)) * 0.000001);
}
function _CalcRhoD2O18AtT(T)
{
   return 1.21691 * (1 - 1.0555 * Math.pow((T - 11.46), 2) *
                     (1.74224 + 482.502 / (T - 11.46 + 77.861)) * 0.000001);
}
function _CalcRhoH2O18AtT(T)
{
   return 1.11255 * (1 - Math.pow((T - 4.305), 2) *
                     (1.74224 + 482.502 / (T - 4.305 + 77.861)) *
                     0.000001);
}

Part two: HTML UI

The HTML should be standard HTML it can include script in the head of the document and can be created any way you want, for example you could create it using Dreamweaver or many of the other tools out there to create HTML files. For the purpose of this tutorial I will show you how to do it without such tools.

Before going further here are a few help full links you can use as a reference for HTML

W3C HTML Documentation

HTML tutorial for Beginners

Basic HTML template

Copy the following HTML text into a plain text editor and save it to the directory module/QtScript

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<script type="text/javascript"> 
$(document).ready(function(){
      query1.prepare("SELECT * FROM version");
      query1.exec();
      query1.next();
      $('#dbversion').append(query1.valuetoString(0));
      $('#width').append(graphics.maximumWidth() + "px");
      $('#height').append(graphics.maximumHeight() + "px");
      graphics.changeWindowSize(1000, 850)
      var graph = $.jqplot ('uic_graph', [[3,7,9,1,4,6,8,2,5]]);
});    
function callFunction()
{
 var density = new Object();
 density.NAME = 'density';
 density.VALUE = $('#density').val()
 var temperature = new Object();
 temperature.NAME = 'temperature';
 temperature.VALUE = $('#temperature').val();
 var D2O = new Object();
 D2O.NAME  = "D2O";
 D2O.VALUE = $('#D20').val()
 var D2O18 = new Object();
 D2O.NAME = "D2O18";
 D2O.VALUE = $('#D2018').val()
 var H2O18 = new Object();
 H2O18.NAME = $('#H2018').val()
 var returnValue = correctBufferDensityAtT_Heavy(density, temperature, D2O, D2O18, H2O18);
 $('#ui_qtCorrectedDensity').val(returnValue.VALUE);
}
</script>
</head>
<body>
 <p>DatabaseVersion: </p>
 <textarea id="dbversion" readonly="readonly" rows=1.5 cols=20> </textarea>
 <p>Desktop Height: <textarea id="height" rows=1.5 cols=10> </textarea> </p>
 <p>Desktop Width:  <textarea id="width" rows=1.5 cols=10> </textarea> </p>
 <form id="CalculateMe" class="correctBufferDensityAtT_Heavy">
   <p>Correct Buffer Density at T heavy:</p>
   <p>Inputs:</p>
    <p>density = </p><input class="input" id="density"/> 
    <p>temperature = </p><input class="input" id="temperature"/>
    <p>D20 = </p><input class="input" id="D20"/>
    <p>D2018 = </p><input class="input" id="D2018"/>
    <p>H2018 = </p><input class="input" id="H2018"/>
   <p>Output:</p>
    <p>  qtCorrectedDensity = </p><input class="output" id="ui_qtCorrectedDensity" readonly="readonly"/>
  </form>
  <nowiki><div id="uic_graph" title="graph"></div>
 <button onclick="javascript:callFunction()">Calculate</button>
</body>
</html>

Follow the instructions on the following bitcwiki page to open your newly created module.

Modules

Once rendered successfully with JavaScript module the your UI should look like the following image and work perfectly.

Sednterp Developer Tools

Developer tools are provided in the Sednterp Desktop application automatically, similar functionality maybe offered in the Sednterp Web application but this would depend on the browser you employ to view the web version, therefore I will only discuss the developer tools that come with desktop application.

Load a user module and right click on the module display like so and click "Inspect", you should see the following dialog appear. If you are familiar with the developer tools offered with Google chrome this dialog should look familiar.

For more on how to use the developer tools check out this this great overview by Google Developer Tools Documentation

How to Access the Sednterp Database

The module provides you with two JavaScript objects you can use to query the sednterp database called "query1" and "query2".

For complete documentation on the query objects consult Sednterp Database Query Objects

These 2 objects are regular JavaScript objects that allow you preform any SQLite command on the Sednterp database. For more on SQLite visit [SQLite Documentation]. The query objects in the web version of Sednterp are limited in scope compared to the desktop application currently this will probably change in the future as web application is developed further. But you can currently get any information from the web application out of the database that you can from the desktop application though for security reason you cannot commit any changes to the web application using the query object as you can with the desktop.

Here is an example of the query object in use.

> query1.prepare("SELECT * FROM version")
true
> query1.exec()
true
> query1.next()
true
> query1.valuetoString(0)
"20120320"

Communicating with active Sednterp Script Module

The module provides you with a XML interface object called "procs", that allows you to use calculations from the calculation module Sednterp main is running for it's call calculations. To use the interface you may need to know a little bit about XML.

The latest release of the Sednterp module script is located here. The functions can be referenced using XML, the standard XML will look as follows

<?xml version="1.0" encoding="UTF-8"?>
<SEDNTERP TYPE="Input">
 <MODULE NAME="MainScreen" VERSION="moduleVersion" DATE="2010/06/22"/>
 <EXECUTE function="functionName"/>
 <INPUT NAME="inputName" VALUE="inputValue"/>
</SEDNTERP>

So when trying access a function from Sednterp Main module file you will need to construct your XML package and then deliver it using the procs object. Take a look at following example for a demonstration.

> var xmlpayload = '<?xml version="1.0" encoding="UTF-8"?>' +
                   '<SEDNTERP TYPE="Input">' +
                   ' <MODULE NAME="MainScreen" VERSION="20120806" DATE="2010/06/22"/>' +
                   ' <EXECUTE function="calculateVBarAtT"/>' +
                   ' <INPUT NAME="Vbar" VALUE=".73"/>' +
                   ' <INPUT NAME="T" VALUE="25"/>' +
                   '</SEDNTERP>';
> procs.submitFromWeb(xmlpayload)
 "<SEDNTERP TYPE="Output">
  <MODULE VERSION="20120806" NAME="MainScreen" DATE="2010/06/22"/>
  <OUTPUT NAME="qtSampleVbar" VALUE="0.732125"/>
  </SEDNTERP>"

Depending on the function you execute you may receive back hundreds of outputs in an array or just as seen in the example above. You can parse through the returned XML using JavaScript or jquery very easily. Take a look at jquery attr function for one way to parse through the XML.

Module Window Graphics options

The module provides you with a graphics object that allows you to change the size and location of the module window as well tells how large you can make the module window. The object is called "graphics", for more information how to use this object, take a look the following page.

Sednterp Graphics Object

JavaScript Libraries included with Sednterp

These libraries are available for use without any user intervention.

jQuery:

jQuery is a JavaScript library that is available for use with Sednterp, you do not need to include it in your HTML UI file, actually it is recomended that you do not because A: it will most likely not load properly on the web version, B: it will be just another file you will have have to keep track of with your module if you link it locally, C: because it is already provided for use when you load your module.

For more about jQuery visit:

jQuery Documentation

jQuery UI

jqPlot:

jqPlot is a JavaScript library that is available for use with Sednterp for creating graphs, chart, etc, it also automatically provided in both Sednterp web and desktop applications to learn about how to use jqplot visit:

jqPlot Documentation