|
Documentation for Rapid Form Builder: (Joomla 1.5) Christopher Knott
Digital Light Internet Design Inc.
Is RFB right for me?
--------------------
This module is great for you IF you are comfortable with PhpMyAdmin. If you are not, please learn to use it, or go no further. PhpMyAdmin is super easy to use if you know the basics about what a database is. Also, if you are uncomfortable using a Text Editor to change a couple of values in code... please go no further.
About Rapid Form Builder (Ajax Forms)
-------------------------------------
Rapid Form Builder (AJAX) is an easy to use Joomla 1.5 module that lets administrators quickly build powerful forms that are integrated into the Joomla 1.5 sessions. This means that if you login, you will always see your values. Cool eh? Anonymous users will see their values for as long as their session lasts.
There are a lot of options for security and validation. These are built in and are explained here:
HOW TO USE THIS MODULE
======================
Joomla Page Creation
--------------------
Create two pages in Joomla 1.5.
Page 1: The page you want the form to appear in.
Page 2: The Thank You Page you want the user to go to when they complete the form.
Copy both of these URL's into a text file (or something) to be sure you have access to them soon.
Module Installation:
--------------------
1. Database Installation
I have included a sample data set so that it will be easy to use the example provided. Since it is nice to use the same database prefix everywhere, please Replace the prefix provided. This should take ~1 minute.
a - Extract the .zip and find the .sql file included
b - Open the file: xxx_rfb.sql in any text editor
c - Change the database prefix in the SQL to equal your own (optional but recommended)
(You can use the Replace feature in any text editor)
d - Save the file (don't forget)
e - Import the SQL file into PhpMyAdmin and keep PhpMyAdmin open... you will need it again in a minute.
2. Joomla Module Installation
a - Login as an administrator to your Joomla 1.5 interface
b - Extensions -> Install
c - Upload the mod_rfb.zip file
3. Module Parameters
Under the Module Manager, Update:
a - Details -> Position (wherever you want it to appear)
b - Menu Assignment -> Menu selection (pages you want it on)
c - Parameters -> change the database prefix to match your own
d - Report Start -> When you login as Admin (ID=62) then you will see a report. This is where the report will start. When the report gets too long, you can increase this number
a - Report Stop -> as above
b - Save (don't forget)
c - Enable the Module
4. Update Table References in the Code
DID YOU DO THE OPTIONAL STEP IN #1 ?
Did you (as recommended) change the datebase prefix in Option 1? ( you know... the database prefix?)
If you did, then there is one place in the code where you need to make the following update:
a - open a text editor and change lines 44 and 45 of check.php to match your prefix.
b - save the file
c - open a text editor and change lines 38 and 29 of clearForm.php to match your prefix.
d - save the file
That's it for installation. If, by some random stroke of luck, the form you wanted to create is EXACTLY the same as the demo one... hey... great... you're done! :) Most people will want to create a custom form.
Customize Your Form
-------------------
The demo form should now work, and is integrated into the Joomla Sessions. In order to customize the form, a little knowledge is required. Mainly, you will need to know how the database works.
The /tmpl/default.php file will look for the ajaxField Name (a1, a2, etc)
Then, it will try to match it to the ajaxField in the TableMappings table
It will lookup the fieldName on the same row
Using the data table, it will read and update the data accordingly. 
To change how fields behave, you will need to edit this table: xxx_rfb_tableMappings.
This is the breakdown of the tables:
ID - standard. auto-increments with every new item
ajaxField - this is the name of the field that we will use within the default.php page (you will edit this page soon). this is the 'master reference' for each field. this is also the name that will be served within the HTML. Do NOT make it the same as the Field Name. If you do, you risk a possible security weakness. This provides an extra measure of security to guard against SQL injections.
tableName - you shouldn't need to touch this one. this tells teh module where the data is stored for this field
fieldLabel - this will be printed out on the HTML as a field label.
mandatory - is this field mandatory? 1 = yes 0 = no
minimumLength - does the response need to be a certain length or more? -- enter the value here if so. 0 = none
uniqueResponse - some things like email addresses will need to be unique. 1 = yes 0 = no
formNumber - default to 1 because i haven't confirmed that you can use multiple forms with this module. maybe one day :)
accordianNumber - you can split up your form fields into groups. it makes the form more usable. which accordian do you want this in?
fieldType - define the type of response you want. e.g. email address
Field Types:
------------
aln - alphanumeric (0-9 a-z)
apl - alphabetic (a-z)
eml - email address
phn - phone # (10 digits)
dig - numbers only (0-9)
txt - basically a free form. should default to this
chk - used only for a checkbox
accessPosition - for accessibility: what letter in the label should be used as a keystroke shortcut. (do NOT use the same letter 2x)
fieldLength - for text fields, how long should the field be? default = 20
defaultValue - use this to display a default value. this may not work as expected, so call me if you want to see it done differently
tabIndex - used for accessibility. tabbing through the form will be done in this order
fieldRows - for Text Areas only. how many rows do you want in the text area?
Update the tmpl/default.php
---------------------------
Based on the above (Customize your form), you should have the database setup fully. All you need to do now is update the 'html' portion of the module.
There are really only 2 types of inputs: Headers and Fields
Headers work like this:
echo $displayField->displaySectionHeader(1,1,"Group 1");
echo - php. do not change
$displayField-> - php. do not change
displaySectionHeader - php. do not change
(1,1,"Group 1"); - Form#, Accordian#, AccordianTitle
- Form# - should match the one from the database. default = 1 (see above comments)
- Accordian# - first = 1 second = 2. matches teh database (see above)
- Title. If your length > 10 characters, you will need to tweak the CSS accordingly
Text Fields work like this:
echo $displayField->displayField(a1, $sid, $mappingsName);
echo - php, do not change
$displayField - php, do not change
->displayField - php, do not change
(a1, - a1 - this field should reflect the ajaxField from the tableMappings table
$sid - php, do not change
$mappingsName - php, do not change
Text Areas work like this:
echo $displayTextArea->displayTextArea(b3, $sid, $mappingsName);
Usage: same as Text Field.
Check Boxes work like this:
echo $displayTextArea->displayCheckBox(b3, $sid, $mappingsName);
Usage: same as Text Field
NOTE: be sure that the type = 'chk' in the tableMappings table
Bug Fixes
---------
Notice a bug? Please send a report.
Feature Requests
----------------
Want a new feature? Send a request.
Final Notes:
============
That should be all you need. You should now have very powerful forms that are validated real-time.
If you have questions or suggestions, please feel free to reach out to me.
I will NOT be making a GUI to create these in the near future. If i get enough donations, or uptake, I may, but there are currently no plans.
Best of luck,
Chris
|
