/Custom ODB tree: Difference between revisions

From MidasWiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 1: Line 1:
<div style="column-count:4;-moz-column-count:4;-webkit-column-count:4">
{{Pagelinks}}
* [[Midas_documentation|Midas Documentation]]
* [[Feature_listing|Feature Listing]]
* [[Application_listing|Application Listing]]
* [[Online_Database|Online Database]]
</div>


= Links =
= Links =
Line 11: Line 6:
* mhttpd [[Custom Page]]
* mhttpd [[Custom Page]]
* mhttpd [[Status Page]]
* mhttpd [[Status Page]]
* [[Mhttpd.js|MIDAS Javascript Library]]
</div>
</div>


= Purpose =
= Purpose =
The <span style="color:purple; font-style:italic;">/Custom</span> ODB tree is required if the user wishes to create [[mhttpd]] custom pages. It contains essential data needed for [[mhttpd]] to display a custom page. The <span style="color:purple; font-style:italic;">/images</span> subtree is required if an imagefile (*.gif) is to be displayed on the custom page. Optionally, labels, bars and fills can be superimposed on the image.
The {{Odbpath|path=/Custom}} ODB tree is required if the user wishes to create [[mhttpd]] custom pages. It contains essential data needed for [[mhttpd]] to display a custom page. The {{Odbpath|path=/images}} subtree is required if an imagefile (*.gif) is to be displayed on the custom page. Optionally, labels, bars and fills can be superimposed on the image.


= Creating the /Custom tree =
= Creating the <span style="color:purple; font-style:italic;">/Custom</span> tree =
The <span style="color:purple; font-style:italic">/Custom</span> ODB tree is an optional tree that may be [[ODB#Creating ODB keys|created by the user]].  
The {{Odbpath|path=/Custom}} ODB tree is an optional tree that may be [[ODB#Creating ODB keys|created by the user]].  




Line 83: Line 80:
<div id="Custom-Button"></div>
<div id="Custom-Button"></div>
= Keys in the /Custom tree =
= Keys in the /Custom tree =
The optional ODB <span style="color:purple; font-style:italic;">/Custom</span> tree may contain
The optional ODB {{Odbpath|path=/Custom}} tree may contain any of the following:


*  links to '''local''' external files containing custom web pages created by the user (html/javascript files)
*  links to '''local''' external files containing custom web pages created by the user (html/javascript files)
*  links to '''local''' external files containing stylesheets (.css files)
*  keys containing the html/javascript code for [[Internal Custom Page|internal custom webpages]]  
*  keys containing the html/javascript code for [[Internal Custom Page|internal custom webpages]]  
*  custom password keys
<span style="color:purple; font-style:italic">/pwd</span> subtree used to contain custom password keys
*  <span style="color:purple; font-style:italic;">/images</span> subtree used to specify images for custom pages
*  <span style="color:purple; font-style:italic">/images</span> subtree used to specify images for custom pages
   
   
If keys are defined in this tree, except where [[#Key names|noted below]], the names of the keys will appear as '''''custom-buttons'''''  on the [[mhttpd]] [[Status Page]]. By clicking on one of these ''custom-buttons'', the custom page will be visible in a new frame (see also [[#Key names|Key names]]).  
If keys are defined in this tree, except where [[#Key names|noted below]], the names of the keys will appear as '''''custom-buttons'''''  on the [[mhttpd]] [[Status Page]]. By clicking on one of these ''custom-buttons'', the custom page will be visible in a new frame (see also [[#Key names|Key names]]).  


If the external HTML file is on a '''remote''' webserver, the link should be placed under the  [[/Alias ODB tree]] rather than the <span style="color:purple; font-style:italic;">/Custom</span> tree.
If the external HTML file is on a '''remote''' webserver, the link should be placed under the  [[/Alias ODB tree]] rather than the {{Odbpath|path=/Custom}} tree.


== Key names ==
== Key names ==
The user chooses the names of any keys in the <span style="color:purple; font-style:italic;">/Custom</span> ODB tree except for
The user chooses the names of any keys in the <span style="color:purple; font-style:italic;">/Custom</span> ODB tree except for
* the Key name "Status" is reserved (see [[Custom Page#Custom Status page|Custom Status Page]]).  
* the Key name <span style="color:purple; font-style:italic">Status</span> is reserved (see [[Custom Page#Custom Status page|Custom Status Page]]).  
* the Key name "Pwd" is reserved (see optional subtree for custom passwords)
* the Key name <span style="color:purple; font-style:italic">pwd</span> is reserved (see optional [[#Pwd subtree|Pwd subtree]] for custom passwords)
* keys in the <span style="color:purple; font-style:italic;">/images</span> subtree have defined names except for the user-defined [[#<Image-name> subtree|<Image-name> subtree]].
* the Key name <span style="color:purple; font-style:italic">path</span> is reserved (obsolete)
* keys in the <span style="color:purple; font-style:italic">/images</span> subtree have defined names except for the user-defined [[#<Image-name> subtree|<Image-name> subtree]].


There are two characters that have special meaning if they are the last character of a Key name in the <span style="color:purple; font-style:italic;">/Custom</span> tree :
There are two characters that have special meaning if they are the last character of a Key name in the {{Odbpath|path=/Custom}} tree :
*    The character "&" forces the page to be opened within the current frame when the ''custom-button'' is pressed. If this character is omitted, the page will be opened in a new frame. The "&" character is omitted from the name of the button.
*    The character "&" forces the page to be opened within the current frame when the ''custom-button'' is pressed. If this character is omitted, the page will be opened in a new frame. The "&" character is omitted from the name of the button.
*    The character "!" suppresses the ''custom-button'' from appearing on the [[Status Page]], forming a hidden-link.
*    The character "!" suppresses the ''custom-button'' from appearing on the [[Status Page]], forming a hidden-link.
Line 106: Line 105:
The hidden-link feature can be used to provide external webpages hidden from the user, such as a stylesheet or a file of Javascript functions needed by other custom pages.
The hidden-link feature can be used to provide external webpages hidden from the user, such as a stylesheet or a file of Javascript functions needed by other custom pages.


The <span style="color:purple; font-style:italic;">/Custom</span> tree in the [[#Example|example]] above would produce one custom-button, i.e.
The {{Odbpath|path=/Custom}} tree in the [[#Example|example]] above would produce one custom-button, i.e.{{Button|name=ppg&nbsp;cycle}}.
<span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">ppg&nbsp;cycle</span>


= <span style="color:purple; font-style:italic">Pwd</span> subtree=
= <span style="color:purple; font-style:italic">Pwd</span> subtree=
Line 114: Line 112:
</div>  
</div>  


This optional subtree in the  [[#top|/Custom ODB tree]] is created by the user if custom page write access is to be  [[Custom Page Features#Password protection of ODB variables|password protected]].
This optional subtree in the  [[#top|/Custom ODB tree]] is created by the user if [[Custom Page]] write access is to be  [[Custom Page Features#Password protection of ODB variables|password protected]].


== <span style="color:purple; font-style:italic"><password></span> ==
== <span style="color:purple; font-style:italic"><password></span> ==
Line 122: Line 120:
</div>
</div>
The '''name''' of the optional key(s) in the <span style="color:purple; font-style:italic">/Pwd</span> subtree defines a password that the user must specify to gain access to a [[Custom Page Features#Password protection of ODB variables|password-protected]]
The '''name''' of the optional key(s) in the <span style="color:purple; font-style:italic">/Pwd</span> subtree defines a password that the user must specify to gain access to a [[Custom Page Features#Password protection of ODB variables|password-protected]]
item on a custom page.  
item on a [[Custom Page]].  


=== Examples ===
=== Password examples ===
If the password is ''CustomPwd'', the ODB key <span style="color:purple; font-style:italic">/Custom/Pwd/CustomPwd</span> would be defined.
If the password is ''CustomPwd'', the ODB key <span style="color:purple; font-style:italic">/Custom/Pwd/CustomPwd</span> would be defined.



Revision as of 16:31, 25 September 2014


Links


Purpose

The /Custom ODB tree is required if the user wishes to create mhttpd custom pages. It contains essential data needed for mhttpd to display a custom page. The /images subtree is required if an imagefile (*.gif) is to be displayed on the custom page. Optionally, labels, bars and fills can be superimposed on the image.

Creating the /Custom tree

The /Custom ODB tree is an optional tree that may be created by the user.


Example

The following example using the odbedit ls command shows the optional custom tree for an experiment.
Note the use of the "&" and "!" characters in the names of the custom keys (see key names for details).

[local:pol:S]/ls -lr /Custom
Key name                        Type    #Val  Size  Last Opn Mode Value
---------------------------------------------------------------------------
custom                          DIR
   ppg_cycle&                  STRING  1    80    36h  0  RWD  /home/pol/online/pol/custom/pol_sc.html
   pol_functions!              STRING  1    80    36h  0  RWD  /home/pol/online/pol/custom/pol_functions.js
   style!                      STRING  1    80    36h  0  RWD  /home/pol/online/pol/custom/style.css
   images                      DIR
       pol_sc.gif              DIR
           background          STRING  1     80    36h  0   RWD  /home/pol/online/pol/custom/pol_sc.gif
           labels              DIR
               num bins        DIR
                   Src         STRING  1     256   36h  0   RWD  /Equipment/pol_acq/settings/output/num bins per cycle
                   Format      STRING  1     32    36h  0   RWD  %d
                   Font        STRING  1     32    36h  0   RWD  Medium
                   X           INT     1     4     36h  0   RWD  315
                   Y           INT     1     4     36h  0   RWD  502
                   Align       INT     1     4     36h  0   RWD  0
                   FGColor     STRING  1     8     36h  0   RWD  FFFFFF
                   BGColor     STRING  1     8     36h  0   RWD  0000FF
               dwell time      DIR
                   Src         STRING  1     256   36h  0   RWD  /Equipment/POL_ACQ/Settings/input/dwell time (ms)
                   Format      STRING  1     32    36h  0   RWD  %f ms
                   Font        STRING  1     32    36h  0   RWD  large
                   X           INT     1     4     36h  0   RWD  145
                   Y           INT     1     4     36h  0   RWD  430
                   Align       INT     1     4     36h  0   RWD  0
                   FGColor     STRING  1     8     36h  0   RWD  FFFFFF
                   BGColor     STRING  1     8     36h  0   RWD  0000FF
            fills              DIR
                   SSLevelBox  DIR
                   Src         STRING  1     256   36h  0   RWD  /Equipment/TpcGasPlc/GasCalc/Calculated[136]
                   X           INT     1     4     36h  0   RWD  578
                   Y           INT     1     4     36h  0   RWD  490
                   Limits      DOUBLE  3     8     2s   0   RWD
                                       [0]             0
                                       [1]             1
                                       [2]             2
                   Fillcolors  STRING  4     8     2s   0   RWD
                                       [0]             000000
                                       [1]             00FF00
                                       [2]             808080
            bars               DIR
                   temp        DIR
                   Src         STRING  1     256   36h  0   RWD  /Equipment/Temperature/Variables/Readback[5]
                   X           INT     1     4     36h  0   RWD  42
                   Y           INT     1     4     36h  0   RWD  68
                   Width       INT     1     4     36h  0   RWD  10
                   Height      INT     1     4     36h  0   RWD  50
                   Direction   INT     1     4     36h  0   RWD  0
                   Axis        INT     1     4     36h  0   RWD  1
                   Logscale    BOOL    1     4     >99d 0   RWD  n
                   Min         DOUBLE  1     8     >99d 0   RWD  0
                   Max         DOUBLE  1     8     >99d 0   RWD  0
                   FGcolor     STRING  1     8     2s   0   RWD  000000
                   BGcolor     STRING  1     8     2s   0   RWD  FFFFFF
                   BDcolor     STRING  1     8     2s   0   RWD  808080

Keys in the /Custom tree

The optional ODB /Custom tree may contain any of the following:

  • links to local external files containing custom web pages created by the user (html/javascript files)
  • links to local external files containing stylesheets (.css files)
  • keys containing the html/javascript code for internal custom webpages
  • /pwd subtree used to contain custom password keys
  • /images subtree used to specify images for custom pages

If keys are defined in this tree, except where noted below, the names of the keys will appear as custom-buttons on the mhttpd Status Page. By clicking on one of these custom-buttons, the custom page will be visible in a new frame (see also Key names).

If the external HTML file is on a remote webserver, the link should be placed under the /Alias ODB tree rather than the /Custom tree.

Key names

The user chooses the names of any keys in the /Custom ODB tree except for

  • the Key name Status is reserved (see Custom Status Page).
  • the Key name pwd is reserved (see optional Pwd subtree for custom passwords)
  • the Key name path is reserved (obsolete)
  • keys in the /images subtree have defined names except for the user-defined <Image-name> subtree.

There are two characters that have special meaning if they are the last character of a Key name in the /Custom tree :

  • The character "&" forces the page to be opened within the current frame when the custom-button is pressed. If this character is omitted, the page will be opened in a new frame. The "&" character is omitted from the name of the button.
  • The character "!" suppresses the custom-button from appearing on the Status Page, forming a hidden-link.

The hidden-link feature can be used to provide external webpages hidden from the user, such as a stylesheet or a file of Javascript functions needed by other custom pages.

The /Custom tree in the example above would produce one custom-button, i.e. ppg cycle.

Pwd subtree

  • Type: DIR

This optional subtree in the /Custom ODB tree is created by the user if Custom Page write access is to be password protected.

<password>

  • Type: STRING
  • Default: ""

The name of the optional key(s) in the /Pwd subtree defines a password that the user must specify to gain access to a password-protected item on a Custom Page.

Password examples

If the password is CustomPwd, the ODB key /Custom/Pwd/CustomPwd would be defined.

By using an explicit name, one can use a single password for all controls on a page, or one could use several passwords on the same page. For example, a shift crew password for the less severe controls could be defined as ShiftPwd, and an "expert" password ExpertPwd for the critical things.

In this case, the ODB would have two passwords defined, i.e.

/Custom/Pwd/ExpertPwd
/Custom/Pwd/ShiftPwd

The password is of course not secure in the sense that it is placed in plain text into the ODB, but its purpose is to prevent accidental modification, rather than malicious interference.



Images subtree

  • Type: DIR

This optional subtree in the /Custom ODB tree is created by the user. It is required if an imagefile (*.gif) is to be displayed on a custom page. This subtree is also required for any labels, bars or fills to be superimposed on the image.




<Image-name> subtree

  • Type: DIR
  • Default:

User-created subdirectory usually named for the corresponding gif-image, e.g. "pol_sc.gif" in the example above. For multiple images, multiple subdirectories may be defined. The user chooses the name of this key.




Background

  • Type: STRING
  • Default:

This key in the <image-name> subtree contains the path and filename of the image file to be loaded into a custom page. Only gif format is supported for the image. This optional key is created by the user.





Labels subtree

  • Type: DIR
  • Default:

User-created subdirectory in the <image-name> subtree required if labels are to be superimposed on an image on a custom page.





<label-name> subtree

  • Type: DIR
  • Default:

User-created subdirectory in the Labels subtree containing keys to define this label as listed below. There will be a <label-name> subtree for each label superimposed on the custom image.

The user creates keys in this subtree with the names and types as listed below. See also the example above.



Src
  • Type: STRING [256]
  • Default:

This key in the <label-name> subtree contains the path of a valid ODB Key variable. This is the value to be used for this label on an image.





Format
  • Type: STRING [32]
  • Default: "%1.1f"

This key in the <label-name> subtree contains the format for this label on the image. Format specifications (c.f. "printf" in C) are used to convert the value specified by the Src key into the output string that appears on the image. For example,

  • "Count Rate:%5d kB/s" used to display an integer value
  • "%5.2f%% iBu" used to display a floating point value. Note "%%" displays the "%" sign.






Font
  • Type: STRING[32]
  • Default: "Medium"

This key in the <label-name> subtree contains the font size for this label. Supported values are "small", "medium" or "giant".





X
  • Type: INT
  • Default: 0

This key in the <label-name> subtree contains the X position for this label in pixels.




Y
  • Type: INT
  • Default: 0

This key in the <label-name> subtree contains the Y position for this label in pixels.





Align
  • Type: INT
  • Default: 0

This key in the <label-name> subtree contains an integer representing Horizontal Alignment for this label. Set to one of 0 (left), 1 (center) or 2 (right).





FGColor
  • Type: STRING [8]
  • Default: "000000"

This key in the <label-name> subtree contains the foreground colour for this label in the format RRGGBB (hex). See colour table.






BGColor
  • Type: STRING [8]
  • Default: "FFFFFF"

This key in the <label-name> subtree contains the background colour for this label in the format RRGGBB (hex). See colour table.






Bars subtree

  • Type: DIR
  • Default:

User-created subdirectory in the <image-name> subtree required if bars are to be superimposed on an image on a custom page.







<bar-name> subtree

  • Type: DIR
  • Default:

User-created subdirectory in the Fills subtree containing keys to define this bar as listed below. There will be a <bar-name> subtree for each bar superimposed on the custom image.

The user creates keys in this subtree with the names and types as listed below. See also the example above.



Src
  • Type: STRING [256]
  • Default:

This key in the <bar-name> subtree contains the path of a valid ODB Key variable. This is the value to be used for this bar.





X
  • Type: INT
  • Default: 0

This key in the <bar-name> subtree contains the X position for this bar in pixels.




Y
  • Type: INT
  • Default: 0

This key in the <bar-name> subtree contains the Y position for this bar in pixels.





Width
  • Type: INT
  • Default: 10

This key in the <bar-name> subtree contains the width of this bar in pixels.





Height
  • Type: INT
  • Default: 100

This key in the <bar-name> subtree contains the height of this bar in pixels.




Direction
  • Type: INT
  • Default: 0

This key in the <bar-name> subtree contains an integer denoting the direction of this bar. It can be either 0 (vertical) or 1 (horizontal).





Axis
  • Type: INT
  • Default: 1

This key in the <bar-name> subtree contains an integer specifying the axis of this bar. It can be either 0 (none), 1 (left) or 2 (right).




Logscale
  • Type: BOOL
  • Default: "n"

This key in the <bar-name> subtree specifies whether the axis of this bar is logarithmic. Set to "y" for logarithmic, otherwise "n".




Min
  • Type: DOUBLE
  • Default: 0

This key in the <bar-name> subtree contains the minimum value for the axis of the bar.





Max
  • Type: DOUBLE
  • Default: 10

This key in the <bar-name> subtree contains the maximum value for the axis of the bar.





FGColor
  • Type: STRING [8]
  • Default: "000000"

This key in the <bar-name> subtree contains the foreground colour for this bar in the format RRGGBB (hex). See colour table.






BGColor
  • Type: STRING [8]
  • Default: "FFFFFF"

This key in the <bar-name> subtree contains the background colour for this bar in the format RRGGBB (hex). See colour table.





BDColor
  • Type: STRING [8]
  • Default: "808080"

This key in the <bar-name> subtree contains the border colour for this bar in the format RRGGBB (hex). See colour table.





Fills subtree

  • Type: DIR
  • Default:

User-created subdirectory in the <image-name> subtree required if fills are to be superimposed on an image on a custom page. A "fill" can change the colour of a region on the image. The contents of the ODB key defined in Src determines the colour as defined by the Limits and Fillcolors arrays.





<fill-name> subtree

  • Type: DIR
  • Default:

User-created subdirectory in the Fills subtree containing keys to define this fill as listed below. There will be a <fill-name> subtree for each fill superimposed on the custom image.

The user creates keys in this subtree with the names and types as listed below. See also the example above.



Src
  • Type: STRING
  • Default:

This key in the <fill-name> subtree contains the path of a valid ODB Key variable. Unless a logic calculation is included, the contents of this key determines the value used for the fill on the image defined by the key Background (see fill-name "SSLevelBox" in the example above).

If a logic calculation is included, up to two operators are permitted, and they must be either

">>" (shift to the right) or
"&" (bitwise AND).

A hexadecimal number preceded by "0x" is also supported. This feature enables a SRC key that is actually a bit pattern to be used for a fill.

In the following example, a gas valve is open if bit 14 of PLCR[136] is TRUE and closed if bit 15 is TRUE (bits are from 0-15). The contents of PLCR[136] are shifted to the right by 14 and then a logical AND is performed to clear all but the lowest 2 bits. The result is used to colour the valve body lime green if the valve is open, and black if it is closed. If neither bit is set (i.e. the valve is neither open nor closed) the valve body is coloured red to indicate an error. Anything else (i.e. both bits TRUE) will give a gray colour.

[local:t2kgas:S]/>ls /custom/images/Pump_20.gif/fills/d2vb3
Src                             /Equipment/TpcGasPlc/Variables/PLCR[136] >> 14 & 0x3
X                               905
Y                               536
limits
                               0
                               1
                               2
                               3
Fillcolors
                               808080
                               00FF00
                               000000
                               808080
                  

Any fill that requires a more complicated calculation than this will have to be done using Javascript in the custom page. The calculated value can then be stored in an ODB key, which is then defined as a Fill Src key.




X
  • Type: INT
  • Default:

This key in the <fill-name> subtree contains the X position for this fill in pixels.




Y
  • Type: INT
  • Default:

This key in the <fill-name> subtree contains the Y position for this fill in pixels.





Limits
  • Type: INT array
  • Default:

This key in the <fill-name> subtree is a variable-length array containing the values of the limits that when reached cause a colour change. Array length must match length of array Fillcolors.





Fillcolors
  • Type: INT array
  • Default:

This key in the <fill-name> subtree is a variable-length array containing the colours corresponding to the Limits array. The colours are defined in the format RRGGBB (hex). See colour table. Array length must match length of Limits array.







Colour Table

For convenience, a colour reference table is shown here for some common colours:

Colour RGB Value
Black 000000
White FFFFFF
Red FF0000
Lime green 00FF00
Blue 0000FF
Yellow FFFF00
Grey 808080