Getting Started

You'll want to start off by unzipping and copying the contents of the qForms zip file to a directory either on your local PC or on a web server. The examples included with qForms API do not require a web server to run.

Once you've copied the files, go ahead and view a few of the example files. Play around with the forms and make sure to view the source code. I think you'll be amazed by how little actual JavaScript was needed in order to get the forms working.

Installation
Create a directory off the root of your web server to store the qForms API files. For the purpose of documentation this directory will be called "/lib/".*

You'll need to copy the following files and directory into the "/lib/" folder. The files are included in the "lib" sub-folder of the zip file.

  • File: qforms.js
  • Directory: /qforms/
  • File: qforms_full.js (Optional**)
  • File: qforms_init.js (Optional**)
Note: In a production environment, you may wish to use the versions of the library files located in the "compressed" sub-folder of the qForms distribution file. The JavaScript files in this folder have all the erroneous white space and comments removed. This dramatically reduce the file size of the library—which means faster download times for the users.
* You can use this folder to store all of your JavaScript library files in. If you already have a directory for this purpose, then you can install the qForm files into that directory. Just make sure to substitute "/lib/" in the documentation with the path where the qForms API files were installed to.
** The purpose of these files is to simplify usage of qForms. If you choose to use these files, you'll need to manually update the files with the correct path to the qForm API files. If you install the files into the default "/lib/" directory, then no changes are necessary.

Preparing A Form
Before you can use the qForms API, there are few things you need to do. The first thing you need to do is to load the qForms API library. You do this by loading the qforms.js using the <SCRIPT> tag. Create a new HTML document, and place the following in between the <HEAD></HEAD> tags of your document:

<!--// load the qForm JavaScript API //-->
<SCRIPT SRC="/lib/qforms.js"></SCRIPT>
<!--// you do not need the code below if you plan on just
       using the core qForm API methods. //-->
<!--// [start] initialize all default extension libraries  //-->
<SCRIPT LANGUAGE="JavaScript">
<!--//
// specify the path where the "/qforms/" subfolder is located
qFormAPI.setLibraryPath("/lib/");
// loads all default libraries
qFormAPI.include("*");
//-->
</SCRIPT>
<!--// [ end ] initialize all default extension libraries  //-->
The above code should be kept isolate from other calls to the qForm API. The reason for this is the include() method acutally performs a document.write() statement which outputs other <SCRIPT> tags. These additional tags are not executed until the end </SCRIPT> tag is reached. If you receive errors that certain methods are undefined which you know exist, try isolate the include() method in it's own block of JavaScript code.
NOTE: The qFormAPI.setLibraryPath() and qFormAPI.include() lines are only required if you wish to use the extension libraries-like the "Validation", "Field" and "Functions" libraries. The usage of these functions will be explained in more detail later on in the documentation.

The next thing you need to do is to initialize a new qForms object. This must be done after the form has been initialized by the document. This can be done in two manors: creating a function to run when the document's onLoad event occurs, or by placing the JavaScript code anywhere in the document after the ending </FORM> tag. For this demonstration, we'll initialize the qForms object after the ending </FORM> tag. Place the following code within the <BODY></BODY> tags of your document.

<!--// a simple form //-->
<FORM ACTION="" METHOD="POST" NAME="frmExample">
<P>Enter some sample text:<BR>
<INPUT TYPE="Text" NAME="SampleText"></P>

<INPUT TYPE="Button" NAME="Test" VALUE="Hello World!"
	onClick="objForm.SampleText.setValue('Hello World!');"></P>

</FORM>

<!--// this code must execute after the end </FORM> tag //-->
<SCRIPT LANGUAGE="JavaScript">
<!--//
// replace "frmExample" with value of the <FORM> tag's NAME
// attribute. you can also substitute "objForm" with any
// variable name that makes sense for you
objForm = new qForm("frmExample");
//-->
</SCRIPT>

Now save the document you just created and load it up in your browser. Clicking the "Hello World!" button will place the text "Hello World!" into the SampleText field. That's all there is too it!

Now that you have a basic overview of the qForms API, you're should be more then ready to start using it in your projects. Take a look at the examples for more inspiration.

[< Back] [Index] [Next >]