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.

Community support

Getting started

The best way to get started is to look at the documentation in the handbooks. In particular, read Programming with formsPlayer and XForms which will guide you through installing formsPlayer and setting up a development environment, which you can then use to work through the Introduction to XForms tutorial. The course shows many key XForms features by way of two useful forms; the first saves links to del.icio.us, whilst the second searches Flickr for images that match a tag.

Samples

There are many complete samples available, which will provide plenty of code to look at. The samples are categorised, with tags such as social-bookmarking, mapping, REST, 3D graphics, and more.

Forums

Once you start developing your own XForms applications you'll find the forums a useful place to ask questions about development. If you've had any problems installing formsPlayer or setting up your development environment then also take a look at the installation forums. If you have any announcements about XForms or formsPlayer then post them in the News and announcements forum.

Bug reports

Please read the detailed description on using the issue-tracking system, linked to below.

Feature requests

We're always looking for ways to improve and enhance formsPlayer, so if you have ideas for features you'd like to see, we'd love to hear them. Please first search the list of feature requests to see if there is a similar suggestion. Even if someone has already made the same suggestion, feel free to add any further thoughts you have, so that if we do come to implement the feature, we'll fulfill as many requirements as possible. And if you find nothing similar then go ahead and add your request.

Professional support

Incident-based support

Professional support is an incident-based paid service, obtained by purchasing support vouchers, each valid for one single support request. Vouchers expire in one year from the purchase date, and you must have at least one unused voucher before we can start tracking your request. If you have none yet, you can either buy a pack of 10 vouchers, or become a Silver Technology Partner, which includes, amongst other things, a pack of 10 vouchers.

Additional terms:

• All professional support requests must be filed through our issue-tracking system.
• Responses will be given through our issue-tracking system, and possibly via other channels (IM, e-mail, etc.). If other channels are used for quick interaction, a summary will still be recorded in the issue-tracking system as well.
• Community support requests will only be handled after all professional support requests are taken care of.

If you would like to find out more about Professional Support then please contact us.

Updating deployed forms

The changes between XForms 1.0 and XForms 1.0 Second Edition are documented in the next section, although the only one that would affect deployed forms is the way that MIP events are dispatched.

A separate section also lists the changes that have ocurred in formsPlayer, but the most significant is that there are a couple of changes to submission.

<xf:action ev:event="my-event">
  <xf:send submission="sub" />
  <xf:setvalue ref="x" value=". + 1" />
</xf:action>

<xf:action ev:event="my-event">
  <xf:send submission="sub" />
</xf:action>

<xf:action ev:observer="sub" ev:event="xforms-submit-done">
  <xf:setvalue ref="x" value=". + 1" />
</xf:action>

<xf:action ev:observer="sub" ev:event="xforms-submit-error">
  <xf:message level="modal">
    Failed to update the customer details.
  </xf:message>
</xf:action>

Changes between XForms 1.0 and XForms 1.0 Second Edition

This section summarises the changes that were made in the move from XForms 1.0 to XForms 1.0 Second Edition.

Although it is worth reading through all of the changes, most of them are unlikely to alter the operation of current forms, except for the way that MIP events are dispatched.