XForms/Naming Conventions

Here are some naming conventions used for this WikiBook. These naming conventions are designed to be consistent across the sample programs, allowing our students to be able to copy and paste blocks of code from the sample programs with a minimum amount of reformatting. So even though it may be a little bit annoying to have the xf: prefix on the XForms data elements, it does make it easy for students to quickly build new applications from the samples.

The audiences for much of this material are state and federal agencies that are converting paper forms to electronic forms. As a result we tend to use the XML Naming and Design Guidelines used by these organizations. Since these standards are built around ISO/IEC-11179 and other ebXML standards, they should not be too strange to most business developers.

There are over 150 of "Naming and Design Rule" guidelines but we don't need to use them all. A web site that discusses them is the Component Organization and Registration Environment web site.

Here are some guide lines to start out with:

Indentation

Please use three space characters to indent your examples. MediaWiki does not allow us to set tab stops and by default they are 8 characters.

Wrap XML Code in Source Tags

Please enclose all your sample XML code with the source tags with the lang="xml" attribute like this:

<syntaxhighlight lang="xml">
 ....your XML code here...
</syntaxhighlight>

Namespace Standards

Namespaces are core to XForms today and essential for our examples to work under a large number of diverse platforms. Please take some time to think carefully about namespaces and namespace prefixes.

Please use the following template at the head of your example:

<html 
   xmlns="http://www.w3.org/1999/xhtml" 
   xmlns:xf="http://www.w3.org/2002/xforms" 
   xmlns:ev="http://www.w3.org/2001/xml-events">
   <head>
   ...

Note that the first line:

xmlns="http://www.w3.org/1999/xhtml"

indicates that the file uses XHTML as its default namespace. Any tags that do not have a namespace prefix are by default elements in the xhtml namespace.

We feel that keeping the examples in this default namespace will make students familiar with HTML more at home with XForms. Standard tags such as <h1>, <p>, <b> and <i> can be freely used in all our examples.

You can optionally add the XML processing instruction before the <html> tag:

<?xml version="1.0" encoding="UTF-8"?>

but most XForms systems do not need this. Any file that has a file extension of ".xhtml" implicitly implies that it is an XML file.

Warnings about DOCTYPE

Please do not put the !DOCTYPE tag in the header for xhtml1-strict.dtd. This specifically states that the file ONLY contains XHTML and most systems will not allow XForms tags when they see this. Many example programs have this and it should be removed to be correct.

XForms Player Specific Markup

Please do not put any player-specific markup in the examples. This book is about W3C standards, specifically XForms, CSS, XML Schema and XHTML. These examples should not require a specific implementation of a client forms player. If you are working with a specific player that does require special HTML tags, they can be automatically inserted by the web application server using an XML transform. This allows these examples to be used in a wide variety of classroom environments and by a large number of server and client XForms players.

For a general template see XForms/Template

For player specific instructions see Player Specific Instructions.

List of Example Program Naming Conventions

Use a separate namespace for HTML, XForms controls and Data.
Give HTML the default namespace. This makes it easy to take existing XHTML code and use it in the examples
1. If it is not possible to give HTML a default namespace, give it a namespace prefix that is short, such as "h".
Use the "xf" namespace prefix for XForm elements. I find about 3/4 of the examples use this already but some use the full "xform" or "xforms" prefix. I suggest avoiding the confusion and just use "xf" since it is short and in common use already.

Examples for US State and Federal Agencies

It is our hope that many US state and federal agencies may integrate this material into their training programs. This is an important audience for XForms since much of the XForms standards were promoted by agencies that did not allow JavaScript to be executed on their desktops for security reasons.

The namespace that we are using for most of our federal data model examples is the NIEM. The namespace prefix is "u" for "Universal" data elements for things like Address, Contact, Activity, Documents, Organizations, Person. The NIEM also has a very nice sub-schema generator that works very well with the process of building forms. See the niem.gov web site for more information on this. If you have any suggestions on any better tools then the NIEM tools, please let us know.

Next Page: Comparison of XForms Products | Previous Page: Installing and Testing
Home: XForms