Frontend integration

Summary   : How to run your forms in the frontend
Author    : Peter Koch
Created   : 2006-05-01
Revisions : 2006-06-14
Based on  : Facile Forms 1.4.5,  Joomla 1.0.9
Applies to: Facile Forms 1.0.0 ... 1.4.5, Joomla 1.0.0 ... 1.0.9, Mambo 4.5.1 ... 4.5.4

Basics

There are 3 ways to run forms:

• Run the form in the main area of your frontend, the component space. This is done by creating a menu item of type component.

• Run the form in a module position. This is accomplished by editing the default Facile Forms module, or making a copy of it and adjusting it. The optional Facile Forms module must be installed to run forms in module space.

• Embedd the form into an existing content. This is done by entering a meta command (a tag) into the content at the place where you want the form to be displayed. The optional Facile Forms mambot must be installed and published for this method.

Running forms in component space

• Go to the desired menu, for example Menu - mainmenu
• Click New to create a new menu item
• Click Component, or select the radio button near Component and click Next
• At Name enter the desired item name as you want it to be displayed in the menu, for example Pizza Shop
• In the component list click on Facile Forms
• Click on Apply to save the menu item and get the parameters shown on the right side.
• At Form name enter the form name, for example SamplePizzaShop
• Click on Save to save the settings
• Go to the frontend and click on Pizza Shop in the menu to have the form executed.

Running forms in module positions

For the very first form in module position:

• In case you have not yet installed the Facile Forms module, go ahead and install it now
• Go to Modules - Site Modules
• Locate Facile Forms. If you dont see it first, click on the link Next below the module list until it shows up
• Click on Facile Forms to open the settings
• In the module details you may change the title and select the desired module position
• Change Published to yes
• At Form Name enter the name of the form to be displayed, for example SamplePieceApp
• At Pages/Items you must at least select one menu item where the module will be displayed
• Click on the Save button to save the settings
• Go to the frontend and check it out

For additional forms in module positions:

• Locate the first Facile Form module (watch out, since you changed the title it no longer ready Facile Forms but whatever title you gave it)
• Select the record by checking the little box left of your first Facile Forms module
• Click the Copy button to make a copy of the module
• Again you may have to click Next to find the copied module in the list
• Open the settings and set all parameters as required

Embedding forms within content

• In case you have not yet installed the Facile Forms mambot, go ahead and install it now
• Go to Mambots - Site Mambots
• Locate the line with Facile Forms. If you dont see it first, click on the link Next below the list until it shows up.
• Click the red cross in the Published column to publish the mambot in case it is yet unpublished
• Go to one of your contents where you want to include the form
• In the desired position, enter a tag like this: {FacileForms : SampleContactForm, 1 , 0}
• Save the content
• Go to the frontend and check it out

Some notes to the tag syntax:

• The second parameter gives the starting page and the third switches border on or off.
• If starting on page 1 and having a border, just {FacileForms:SampleContactForm} would be enough, you dont have to supply parameters 2 and 3 if both are 1 (the default).

Below is the full tag syntax for release 1.4.5. To find the valid syntax for your installed release go to Mambots - Site Mambots and click on Facile Forms:

Pattern syntax:

	{ FacileForms : formname [, page, border, urlparams, suffix ] }

Parameter description:

	FacileForms : This tag must be present literally and in exact upper/lowercase.
	formname    : The name of the form to include, also in exact upper/lowercase.
	page        : The starting page number.   Defaults to 1 when omitted.
	border      : 0=no border, 1=with border. Defaults to 1 when omitted.
	urlparams   : Parameters to pass in URL style (no spaces or unencoded commas allowed).
	suffix      : Suffix appended to all CSS class names in the form.

Examples:

	{ FacileForms : SampleContactForm }
	{ FacileForms : MyVeryForm, 2 }
	{ FacileForms : AnotherForm, 1, 0, &ff_param_xy=123&ff_param_foo=bar }
	{FacileForms:testform,,,&ff_param_foo=bar,mysuffix}

But attention with the following one. Basicly it would work, but when using a WYSIWYG 
editor, the editor will insert linebreaks such as <br/> and so the bot will no longer 
recognize the pattern:
	{
		FacileForms:

			AnotherForm,
			1,
			0,
			&ff_param_xy=123&ff_param_foo=bar
	}