Single Project Licenses

A Single Project License controls formsPlayer configuration for an unlimited number of users, for all XForms within a given directory on a web-server. For example, if you have a web application that is located at:

http://www.example.org/accounts

then when formsPlayer loads any of the following XForms it will pick up the configuration options that have been specified:

http://www.example.org/accounts/form1.html
http://www.example.org/accounts/invoices/form2.html
http://www.example.org/accounts/purchase/form3.html

However, the following form would not receive the same configuration:

http://www.example.org/crm

In this situation, a second license could be purchased to provide distinct branding for the CRM application, or if no separate configuration is required--i.e., both the accounts application and the CRM application can use the same splash-page and branding--then the main license could refer to:

http://www.example.org

Now both the accounts and CRM applications would have the same configuration settings.

If you would like to buy Single Project Licenses they are available online from Grey Matter. Also see Using a formsPlayer Single Project License for instructions on how to use the license.

User Licenses

Whilst a Single Project License is appropriate when a large number of users will be accessing a single application, there will be times where a smaller number of users will be accessing many applications. This scenario is supported by formsPlayer User Licenses which will disable the Community Edition branding on a single machine, regardless of the web applications that the user looks at.

If you would like to buy User Licenses they are available online from Grey Matter. Also see Using a formsPlayer User License key for instructions on how to remove the Community Edition branding.

Using formsPlayer with server-side XForms processors

Since XForms can run on many different devices then it's obviously important for server-based systems such as Orbeon, Chiba and Intalio to be able to use any client-side XForms processor. This means that even if developers are aiming to avoid any installation requirement on the part of their users, it is still possible to make use of an XForms processor such as formsPlayer or the Firefox extension, if it is found to be already present on a user's machine.

To try to make this as easy as possible, we've released a GPL script that can be placed in an HTML or XHTML document, and which tries to assist in the use of client-side XForms processors if they are installed. The script will also help the user to install a processor if necessary.

The key point is to place control over whether or not to use a client-side processor in the hands of the user. When building HTML sites we try to make sure that browser choice is irrelevant, and the goal is to do the same for XForms. In this section we look at how we can do that.

The lib-xh project

To create a document that will work with many different processors we use lib-xh, an open source project hosted at Google Code :

  http://code.google.com/p/lib-xh

The source for the project is located here:

  http://lib-xh.googlecode.com/svn/trunk/

Using the library simply requires the main script to be included in source documents, as follows:

  <script src="http://lib-xh.googlecode.com/svn/trunk/xH.js" type="text/javascript">/**/</script>

Operation of lib-xH.js

At the moment the script checks for formsPlayer (if running within Internet Explorer) and for the Firefox XForms extension (if running within Firefox). If the Firefox extension is present then the script doesn't need to do anything else, but if formsPlayer is detected the correct tags need to be added to the source document so that the formsPlayer ActiveX component can be invoked. This also conveniently addresses the Eolas problem.

If neither plug-in is present then a small message is added to the top of the document along the lines of 'this form will run faster if you install x'. The message includes a link to make it easier for the user to download either the Firefox extension or formsPlayer, depending on the browser being used.

To see how this side of the script works, try running the following form in various browsers::

  http://lib-xh.googlecode.com/svn/trunk/test/basic.html

Using lib-xh to automatically install or upgrade formsPlayer

The script can also be used to automatically install formsPlayer, in situations where a project specifically requires formsPlayer to be present. It's also possible to indicate a required minimum version, which will force an upgrade if necessary. To make use of installation and upgrade features a version number is added to the document before the instruction to load lib-xH.js:

  <script type="text/javascript">
    var sLatestFpRelease = "1,5,4,1010";
  </script>
  <script src="http://lib-xh.googlecode.com/svn/trunk/xH.js" type="text/javascript">/**/</script>

An example that uses this technique is here:

  http://lib-xh.googlecode.com/svn/trunk/test/upgrade-fp.html

Note that loading this form in Firefox or Safari will give different messages to the previous example; since in this form we have specified that we must have formsPlayer installed, viewing the page in any browser other than IE will give users a message that there is no version of formsPlayer available for them, and that they should try again, using IE.

Deciding whether to deliver XForms or HTML

If you are running a server-side XForms processor then you'll also need to detect whether a client-side processor has been installed. To detect formsPlayer check the HTTP Accept headers for the string formsPlayer. If it's detected then your server can simply deliver the XForms untransformed.

[Need to check how this is done with Firefox.]

If no client-side XForms processor is detected then the transformation to HTML can continue, and the HTML delivered to the user. However, even then, if lib-xH.js is included in the output HTML, the user still has the option to install a client-side processor which would then be used for subsequent forms.

Conclusion

Since XForms can be run on a number of different processors, applications that make use of XForms would do well to empower their users to decide whether they use a client-side processor or not.

Deploying formsPlayer

A commercial license for formsPlayer entitles an organisation to distribute formsPlayer to their users, in any way they like--from their own servers, via CD-ROM, and so on. But whichever way is chosen, the technique is the same; an HTML file references a CAB file, which in turn contains formsPlayer. This allows organisations control over everything from the look-and-feel of the installation, to when exactly it should take place.

In the mark-up that follows we'll assume that the CAB file is to be distributed from an intranet server, and that the HTML file is at a different location to the CAB file (hence the need for absolute paths). But the same techniques will work if the HTML and CAB file are in the same directory on the same server, or if they are both in a ZIP file on a CD-ROM.

We'll assume that the CAB file containing the specific version of formsPlayer that needs to be installed, has been copied to this location:

http://intranet/files/formsPlayer1.4.3.1028.cab

Installing formsPlayer

Installation is as simple as creating an HTML page that contains the following:

<head>
  <object width="0" height="0" id="formsPlayer"
   classid="CLSID:4D0ABA11-C5F0-4478-991A-375C4B648F58"
   codebase="http://intranet/files/formsPlayer1.4.3.1028.cab"
  >
    <b>formsPlayer has not been installed.</b>
  </object>
  <?import namespace="xf" implementation="#formsPlayer"?>
  <title>Some XForm</title>
</head>

Using @codebase in this way will cause formsPlayer to be installed if it is not already present on the machine. However, if it has been installed already, it will not be automatically upgraded if the version in the CAB file being referenced is newer; in fact, the CAB file is not referenced at all if formsPlayer was successfully initialised.

Upgrading formsPlayer

To force Internet Explorer to test the version of a current installation of formsPlayer, #Version is added to the CAB file's URL:

<object width="0" height="0" id="formsPlayer"
 classid="CLSID:4D0ABA11-C5F0-4478-991A-375C4B648F58"
 codebase="http://intranet/files/formsPlayer1.4.3.1028.cab#Version=1,4,3,1028"
>
  <b>formsPlayer has not been installed.</b>
</object>

With this combination, a user that doesn't have formsPlayer installed already will have version 1.4.3.1028 installed for them, whilst a user that has a version less than 1.4.3.1028 will be automatically upgraded. Nothing will happen for those that already have 1.4.3.1028 installed, and likewise, nothing will happen if a user obtained a newer version of formsPlayer via another route.

Enforcing a minimum version

The version number needn't be as specific as indicating an exact release of formsPlayer. For example, if we have a form that makes use of some XForms 1.1 features that were introduced in formsPlayer 1.5, we may want to insist on the user having some version of 1.5, but we might not mind which one. This scenario could be handled as follows:

<object width="0" height="0" id="formsPlayer"
 classid="CLSID:4D0ABA11-C5F0-4478-991A-375C4B648F58"
 codebase="http://intranet/files/formsPlayer1.5.1.1001.cab#Version=1,5"
>
  <b>formsPlayer has not been installed.</b>
</object>

As new versions of formsPlayer are placed on the server, the name of the CAB file can be updated, but the value of the Version parameter needn't change:

<object width="0" height="0" id="formsPlayer"
 classid="CLSID:4D0ABA11-C5F0-4478-991A-375C4B648F58"
 codebase="http://intranet/files/formsPlayer1.5.1.1002.cab#Version=1,5">
  <b>formsPlayer has not been installed.</b>
</object>

<object width="0" height="0" id="formsPlayer"
 classid="CLSID:4D0ABA11-C5F0-4478-991A-375C4B648F58"
 codebase="http://intranet/files/formsPlayer1.5.1.1003.cab#Version=1,5">
  <b>formsPlayer has not been installed.</b>
</object>

<object width="0" height="0" id="formsPlayer"
 classid="CLSID:4D0ABA11-C5F0-4478-991A-375C4B648F58"
 codebase="http://intranet/files/formsPlayer1.5.2.1001.cab#Version=1,5">
  <b>formsPlayer has not been installed.</b>
</object>

This has the effect of not upgrading everyone each time a new version of 1.5 is available, but it does ensure that anyone still using 1.4 or 1.3 will be upgraded.