mod_qlform - Documentation

Here you add the xml code. Use Joomla! xml style for form. Params U see here. As textarea doesn't allow , use [ and ] instead. So the form xml might look like that.

[form]
[fieldset name="fieldset1"]
[field name="name" type="text"  size="50"
required="true" /]
[field name="email" type="email" size="50"
required="true" /]
[field name="subject" type="text" size="50" /]
[field name="message" type="textarea"
cols="50" rows="20" required="true" /]
[/fieldset]
[/form]

You must use a form tag and a fieldset tag. Fieldset tag MUST have a name, otherwise Joomla! can't display fields

You can add additional fieldsets with (or without) labels, e. g.

[form]
   [fieldset name="fieldset1" label="Personal data"]
     [field name="firstname" type="text"  size="50"
     required="true" /]
     [field name="lastname" type="email" size="50"
     required="true" /]
     [field name="subject" type="text" size="50" /]
     [field name="message" type="textarea"
     cols="50" rows="20" required="true" /
  [/fieldset]
  [fieldset name="fieldset2" label="Adress data"]
     [field name="street" type="text"  size="50"
     required="true" /]
      [field name="suburb" type="text" size="50"
      required="true" /]
      [field name="zip" type="text" size="50" /]
  [/fieldset]
[/form]

All form field types you find in the Joomla! docs:

• http://docs.joomla.org/Category:Standard_form_field_types
• http://docs.joomla.org/Standard_form_field_and_parameter_types

In case you get the error message "invalid form" while saving. This refers not (!) to the xml in the textarea field. Just add a valid e-mail address in the e-mail address field.

By the way, this is why the param section "e-mail settings" is marked with an asterisk (*).

To display a mod_qlform or any other module in an article, do as follows:

• generate a mod_qlform; give it the position "qlform1"
• go to your article; enter {'loadposition qlform1} (without ' of course) into it
• that works already!
• optimization: go to mod_module, change "Menu Assignement", activate module only for that very menu item, you call the article with (<-not neccassary, but nice:-)

Explanation: Joomla! has a plugin callled up with the {'loadposition XXX} command (without ' of course). For "XXX" set the name for the module position you attach the module to; I always use something meaningful like "qlform1" or "contactform" a. s. o. You can call any module with this plugin command.

(Addition: Alternatively you could use the plg_qlmodule; that would make sense, if you have a bunch of forms that look all alike, but shall be sent to different e-mail recipient. For one or two forms the Joomla! core plugin is definately enough:-)

Sometimes you wish to have an explaining text above or below a field. This can easily be done with a spacer field.

Just add the following tags within you xml:

• [field type="spacer" label="This is an explaining text concerning the input below" description="This description text would show up when hovering the text"][/field]

More about spacers you find here:

• http://docs.joomla.org/Spacer_form_field_type

• Create article like "Thank you very much for your message bla bla"
• Create "Shadow menu", it means a menu, that you will not display on website
• Create Menu entry in shadow menu link "thank you very much"
  • save
  • copy the url (here: "index.php/thank-you-very-much")
  • cancel
• Go to mod_qlform administration:
  • redirctions: use redirection: "yes"
  • redirctions: redirection: "/index.php/thank-you-very-much"
  • important!: leading "/" in front of "index.php"
  • save
• Thank should do it;-)

Explanation: After sending the mail (or doing whatever to the data) mod_qlform redirects to new page. This page is identified by it's url. As we want wo have a nice url ("index.php/blabla") we create a menu entry in a shadow menu. Thus we acoid an seo unfriendly url like indep.php?option=com_components&...". As it is only a shadow entry, it will be displayed nowhere.

Symptom: Nothing happens; the captcha is static.

Probably the caching of the website is activated. Then the captcha pic won't be reloaded anymore.

(1) For modules in a generic template module position

Recommended setting:

• global configuration>caching:"progressive or conservative"
• modules>mod_qlform>advanced>caching:"no"

(2) For modules bound to an article via {'loadposition ...} or {'loadmodule ...} or so:

Only one possible action:

•  deactivate global configuration>caching:"no" and activate captcha

(a) xml: add attribute size (sometimes not reliable)

Add the attribute "size" to your field - textareas require rows and cols attributes , e. g.:

• [field type="text" size="20" ... /]
• [field type="textarea" rows="20" cols="20" ... /]

Rating: Fast and easy, yet not reliable, as size attributes are interpreted differently by the browsers

(b) css: add stylesheets (always reliable, therefore recommended)

Go to your stylesheets:

• templates/yourTemplateName/css/yourCssFile.css
  or via Joomla!
• Extensions > Templates > Style > YourTemplateName > yourStylesheetFile.css

Alter single, individual field:

• div.qlform #jform_name input {background:green; color:yellow;} /*input of field 'name'*/

If you want whole groups of inputs to look the same, call the via the fieldset they are in, like:

• css
  #fieldset1 input {background:green; color:yellow;} /* all inputs in #fieldset1*/

Or call them via their class, that you have stated in the xml:

• xml:
  [field type="text" class="myGreenfields" ... /]
  [field type="text" class="myGreenfields" ... /]
• css:
  div.myGreenFields  {background:green; color:yellow;} /* all inputs with class .myGreenFields*/

Rating: A little bit of work, but clean solution for every browser

mod_qlform generates regular html code. So use the normal css styles.
You can call the html code e. g. via following commands:

• div.qlform {} /*this div container around mod_qlform; depends on what name you gave it in the xml*/
• div.qlform dt {} /*the dt container around the labels*/
• div.qlform dd {} /*the dt container around the inputs*/
• div.qlform dt.jform_name {} /*the very dt container of name field; depends on what name you gave it in the xml */
• div.qlform dd.jform_name {} /*the very dt container of name field; depends on what name you gave it in the xml */
• div.qlform input,div.qlform textarea, div.qlform button {} /*any button, textarea, input in mod_qlform*/
• div.qlform .jform_name input {} /*input of field 'name'*/

Read also:

• "Horizontal fields"
• Important: User FireFox-Addon "Firebug", get it, you'll love it!

Es ist eine reine css-Geschichte. D. h., Du musst nur die richtigen css-Befehlen eingeben.
Grundlegend sind folgende Befehle:

float:left; /* the next element shall be to my left*/
clear:both; /* I will stand in the next line, I don't care what my pregoing elemnt wants  */
width: 150px; /*oder*/ width: 250px; /*often elements would like to float,
but are too big; so cut down the size a little*/

Helpful: FireFox-Addon "Firebug", get it, you'll love it!

2 Possibilities for horizontal fields

(6.1) via css

Every form field and every label has an own id or other html attribute. They are accessible via css.

Example xml:
[field name="zutaten" label="Checkboxes" type="checkboxes"]
[option value="1"]Salami[/option]
[option value="2"]Champignons[/option]
[option value="3"]Käse extra[/option]
[option value="4"]Noch mehr Käse[/option]
[/field]

css commands:

#jform_zutaten li {float:left; display:block; width:200px; height:50px;}
#jform_zutaten li:nth-child(2n-1) {clear:both;} /*that means, every 1st,, 3rd, 5th etc. field ist displayed in a new line; works in FireFox and IE9; might not work on IE8.*/

Where to find css files? Go to the css files of your template. You find them here:

a) either via files: templates/yourTemplateName/css/styleSheetName.css
b) or via Joomla administration: Extensions>Template Manager>Templates>yourTemplateName Details and Files>styleSheetName.css

(6.2) Via html

(Rather for developers.) Generate an overriding layout. Generate copies of all files that you can find in modules/mod_qlform/tmpl/..., e. g.:

• templates/yourTemplate/html/mod_qlform/default.php
• templates/yourTemplate/html/mod_qlform/default_form.php
• ...

In the original files the form ist generate automatically via ->getFieldsetsWe're ghonna change this now.

The field should be available as separate fields (that means e. g. not one "checkboxes" field, but several "checkbox" fields. Now you can generate labels an inputs via following commands:

• echo $form->getInput('fieldId');
• echo $form->getLabel('fieldId');

These commands you can a. g. put into a table.

Example xml:

[field name="salami" id="salami" label="Salami" type="checkbox" /]
[field name="champignons" id="champignons" label="Champignons" type="checkbox" /]
[field name="kaese-plus" id="kaese-plus" label="Käse extra" type="checkbox" /]
[field name="kaese-doppelplus" id="kaese-doppelplus" label="Noch mehr Käse" type="checkbox" /]

The correspanding html

<table>
<tr><?php echo $form->getInput('fieldId');?><td><?php echo $form->getInput('fieldId');?></td></tr>
<tr><?php echo $form->getInput('fieldId2');?><td><?php echo $form->getInput('fieldId2');?></td></tr>
</table>

1. SETTINGS

Use following settings (example here with recipe table):

1. Basic Options > Save to Database : Yes
2. Database > Database table : #__recipes [put here your table's name)
3. Database > Add date created : Yes

2. XML

Say, we have a form for recipes people can send. XML looks like that:

[form]
[fieldset name="fieldset1"]
[field name="name" type="text"  size="50" required="true" /]
[field name="ingredients" type="textarea" size="50" cols="50" rows="20" required="true" /]
[field name="todo" type="textarea" size="50" cols="50" rows="20" required="true" /]
[/fieldset]
[/form]

3. CREATE TABLE

Create the table #__recipes in your database. This table has the following cols:

• id [autoincrement; important!]
• name
• ingredients
• todo
• created

4. TROUBLE SHOOTING

The module itself tells you, what it needs. Do as follows:

1. Basic Options > Save to Database : Yes
2. Basic Options > Message type : In module itself
3. Database > Show db-form conflict : Yes
4. Cascading forms > Add post data to form : No [default of elder versions was "yes", but might lead to problems here]

5. READ ERROR MESSAGE AND ADJUST

Now submit your form and see, what the form tells you. E. g. my qlform tells me now the following error message

"Table `fwj25_qlform_survey1` was not found in database `snoopy`. To store data, create new table in database.
For help check module parameters and read description of module.
mod_qlform : Db-form conflict:
`name` column could not be found in database.
`email` column could not be found in database.
`subject` column could not be found in database.
`message` column could not be found in database.
If intended, ignore message. (Tip: Set 'Display db-form conflict' to 'No' before going online.)"

Here you can see right away, what's missing. In my case, the table is not found (therefore no table cols are found, too:-).

Assuming we got 3 forms cascaded. All 3 forms gather the data; only the last one does something (like saving to database or sending an e-mail)

• Formular 1
  is seated on page /index.php/form-1
  Settings:
  
  • Email>email (always required)
  • Cascading Forms>action > "/index.php/form-2" (without quotes)
• Formular 2
  is seated on page /index.php/form-2
  Settings:
  
  • Email>email (always required)
  • Cascading Forms>action > "/index.php/form-3" (without quotes)
  • Cascading Forms>addPostDataToForm > "yes"
• Formular 3
  is seated on page /index.php/form-3
  Form that finally sends data to database and/or send e-mail
  Settings:
  
  • Email>email (always required)
  • Cascading Forms>action > NO Action, adressing itself with "#" (without quotes)
  • Cascading Forms>addPostDataToForm > "yes"
  • Basic Options>send email >"yes" (if desired)
  • Basic Options>safe to database >"yes" (if desired, watch out database settings)

     

• erstellen Sie Artikel
  • 1. Artikel hat den Inhalt
  • 2. Artikel hat den Inhalt
  • 3. Artikel hat den Inhalt
• erstellen Sie ein neues Menü, Name "Schattenmenü"
• erstellen Sie neue "Schattenmenü"-Menüpunkte (das Schattenmenü wird nirgends angezeigt; es dient lediglich dazu, dass Joomla! sich orientieren kann:-)
  
  • 1. Menüpunkt
    
    • Name: Formular1:
    • Typ: Beiträge: Einzelner Beitrag
    • Beitrag: Formular 1
    • Wichtig: Notieren Sie sich die erzeugte URL bzw. das Link
  • 2. Menüpunkt
    
    • Name: Formular2:
    • Typ: Beiträge: Einzelner Beitrag
    • Beitrag: Formular3
    • Wichtig: Notieren Sie sich die erzeugte URL bzw. das Link
  • 3. Menüpunkt ... (wie oben)
    • wie oben, nur mit 3
    • Wichtig: Notieren Sie sich die erzeugte URL bzw. das Link
• erstellen Sie Module 
  • Modul 1
    • Typ: mod_qlform
    • Position: formular1
    • Menüzuweisung : nur ausgewählte Seiten >1. Menüpunkt
    • "Action of form": das notierte Link des Menüpunktes 2
  • Modul 2
    
    • Typ: mod_qlform
    • Position: formular2
    • Menüzuweisung : nur ausgewählte Seiten >2. Menüpunkt
    • "Action of form": das notierte Link des Menüpunktes 3
    • "Post-Daten hinzufügen": Ja
  • Modul 3
    
    • Typ: mod_qlform
    • Position: formular3
    • Menüzuweisung : nur ausgewählte Seiten >3. Menüpunkt
    • "Action of form": #
    • "Post-Daten hinzufügen": Ja
    • "E-Mail verschicken": Ja
• Ihr Formular erreichen Sie über den notierten Link von Menüpunkt 1; Sie können nun diesen Artikel auch anderweitig in Ihre Navigation einbinden, also z. B. einen zusätzlichen Menüpunkt im Hauptmenü erstellen, der auf das Formular verweist.

For changes generate an override.ini. Works like that

• generate folder languages/overrides
• generate file languages/overrides/en-GB.override.ini
• Enter the line you wish in the the file, e. g.:
  MOD_QLFORM_SENDCOPY_LABEL="Here is your translation"
• You can look up all placeholders in the following file
  languages/en-GB/mod_qlform.ini
  Do not change this very file; change the override.ini

Explanation: In the module's template are only placeholders; if you change existing translations, you can adjust them by calling the placeholders in the override.ini.
Thus you avoid that translations are unwillingly overridden when upgrading the module.

All language data are stored in the language fiels installed. Simple generate your own language file. Let's asume its the Norvegian language you'd like to translate to.

1. go to folder "language/en-GB/"
2. copy files "en-GB.mod_qlform.ini" und "en-GB.mod_qlform.sys.ini"
3. go to folder "language/nn-NO/"
4. put both files there
5. rename files to "/nn-NO.mod_qlform.ini" und "/nn-NO.mod_qlform.sys.ini"
6. open "/nn-NO.mod_qlform.ini"
7. translate (tip: translate only what you really need, so just pick e. g. "Send copy to me":-), mind the syntax, so don't forget the opening =" and the ending"

You have a full translation for mod_qlform? Why use it once? Why use it alone?
Send it to me to add it to mod_qlform. Make it a real OpenSource!

To suppress the cloaking change the setting in module's administration e-mail cloaking.

Explanation: Joomla! is "cloaking" e-mail-addresses to avoid spamming - when used within a component.

So when qlform is used within an article, an e-mail address in an input field is cloaked via javascript, and that gets alll wrong within a input field. So we switch e-mail-cloaking off and that's it:-)

Mark: If you are a developer, if you can code, here is the "how to":-)
If you are not, maybe you try to get the component "jdownloads" or some other form module.

• Override templates files
  • go to modules/mod_qlform/tmpl
  • copy all files in this folder
  • create folder templates/yourTemplate/html/mod_qlform
  • insert copied files here
  • modifytemplates/yourTemplate/html/mod_qlform/default_form.php: add 'enctype="multipart/form-data"' in form tag
    
• modify module and doSomethingElse
  • set params "do Something Else" to "yes"
  • rename "modules/mod_qlform/classes/modelQlSomethingElse.php-rename-me-when-you-use-me" to "modules/mod_qlform/classes/modelQlSomethingElse.php"
  • add own code in modules/mod_qlform/classes/modelQlSomethingElse.php; here you can add saving files etc.

• backend>modules>mod_qlform>basic settings>"do Something else" >"Yes"
• activate "modelQlSomethingElse.php", thus read the pregoing paragraph about doing something else
• copy all method (functions within class "modQlMailer") from "modelQlMailer.php"
• paste all qlmailer methods into the class "modelQlSomethingElse" in "modelQlSomethingElse.php"
• add the following lines into the doSomethingElse() method:
  • $recipient=preg_split("?\n?",$this->params->get('recipient'));
  • $subject=$this->params->get('subject');
  • $data=$this->data;
  • foreach ($recipient as $k=>$to)
  • {
  •      $this->mail($to, $subject, $data);
  • }
• adjust method generateMail() to your html needs
• I haven't tried this very code yet, so there might be a syntax mistakes in it; nevertheles it should be clear, how it works:-) Good luck!

There are 2 different ways of doing something else, if you want to do something else and something completely different and other things I might not guess.

(a) "hardcoded"
All module data - including the id - is passed to SomethingElse(); now just generate a "fork" like

function SomethingElse()
{
    if (132==$this->module->id) $this->doThisVerySomething();
    if (133==$this->module->id OR 142==$this->module->id ) $this->doSomethingCompletlyDifferent();
    return true;
}

I don't know, if the syntax is really proper (no editor here), but I think you get what I mean:-)

(b) more flexible (recommended)

Use the "note" field in your module give some extra information, e. g. emailSender or sms.
This you can add new modules with the already existing functionality - without having to adjust the source code.

function SomethingElse()
{
    $note=$this->getNote($this->module->id);   
    if ('sms'==$note) $this->sendSMS();
    if ('emailSender'=$note) $this->sendEmail();
    if ('databaseSpecial'=$note) $this->databaseSpecial();
    return true;
}

function getModuleNote($moduleId)
{
    $db=JFactory::getDbo();
    $db->setQuery('SELECT `note` FROM `#__modules` WHERE `id`=\''.$moduleId.'\'');
    return trim($db->loadObject()->note);
    /*I don't know, if the syntax is proper (no editor here), but I think you get what I mean:-), you find how to do this query on Joomla! dev site*/
}

function sendSMS() {...}
function sendEmail() {...}
function databaseSpecial() {...}

Of course you could also perform several actions on only one module by using a if (preg_match('/sms/',$note) command or by $arrTasks=preg_split('/ /',$note); plus foreach ($arrTasks ...)

• Create an override of the mod_qlform
  • generate folder templates/yourTemplate/html/mod_qlform/
  • copy all file you can find in modules/mod_qlform/tmpl to the generated folder
  • now work with these files
• Manipulate overwriting file templates/yourTemplate/html/mod_qlform/default_form.php
  • add you html code here, e. g. table etc.
  • strip that foreach stuff
  • Getting field stuff with following commands (without ' of course)
    
    • <'?php getInput('fieldId'); ?>
    • <'?php getLabel('fieldId'); ?>
  • around the label you can add your links
    • <'a href="http://www.ql.de"><'?php getInput('fieldId'); ?>
  • In this file you can do everything you like and know about html, css and forms. Just make sure, that everything works afterwards and that you haven't forgotten a maybe very important field.