APPENDIX: The Soft-bar Installer API

The Soft-bar Installer API is a set of functions available to an XForms document which allow bars to be added and removed from the browser.

The namespace for the library is:

urn:formsplayer.com/softbars

Example

Functions in the library can be made available to XPath expressions like this:

<html
 xmlns="http://www.w3.org/1999/xhtml"
 xmlns:xf="http://www.w3.org/2002/xforms"
 xmlns:sb="urn:formsplayer.com/softbars"
>
  <head>
    .
    .
    .
    <xf:model functions="sb:GenerateBar sb:RemoveBar">
      ...
    </xf:model>
  </head>
  .
  .
  .
</html>
sb:GenerateBar
The sb:GenerateBar function will add a new bar to the list of bars available to the browser.
The parameters are:

type
The type of bar to add:

1 = toolbar;
2 = sidebar;
3 = footer-bar;
4 = explorer bar.

internal name


A name by which you can identify the bar. It's important that this is unique since it will be used internally by the browser to link the bar to any menus, and is also used to identify the bar when calling sb:RemoveBar to remove it. This should be completely alphabetic.
menu entry
A name for the bar that will be used in the browser menu.
URL
The location of the bar. This can be on the internet, which does make it very easy to add new functionality to the bar without requiring a download.

The return value will be "Success" if successful, otherwise an error description.
Example
A typical use would be to invoke the function, and then show a message. The message could indicate success or failure:
<xf:action ev:event="my-install-bar">
  <xf:setvalue
   ref="@retval"
   value="sb:GenerateBar(
    string(../type),
    string(../internalName),
    string(../name),
    string(../uri)
   )"
  />
  <xf:message level="modal">
    '<xf:output ref="name" />'
    has
    <xf:output value="
      if(
        @retval = 'Success',
        ' been added. You will need to open a new browser window to see the change.',
        concat(' failed to install. The error is &#34;', @retval, '&#34;.')
      )"
    />
  </xf:message>
</xf:action>

sb:RemoveBar
The sb:RemoveBar method will remove a previous installed soft-bar. There is only one parameter:

internal name
The internal name used when the bar was created with sb:GenerateBar.


The return value will be "Success" if successful, otherwise an error description.
Example
A typical use would be to invoke the function, and then show a message. The message could indicate success or failure:
<xf:action ev:event="my-remove-bar">
  <xf:setvalue
   ref="@retval"
   value="sb:RemoveBar(string(../internalName))"
  />
  <xf:message level="modal">
    '<xf:output ref="name" />'
    has
    <xf:output value="
      if(
        @retval = 'Success',
        ' been removed. You will need to open a new browser window to see the change.',
        concat(' failed to be removed. The error is &#34;', @retval, '&#34;.')
      )"
    />
  </xf:message>
</xf:action>