Differences ¶
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
en:tutorials:simple-jforms-example [2008/04/07 11:36] – laurent | en:tutorials:simple-jforms-example [2012/12/06 20:38] (current) – [Simple jForms example for Jelix 1.3] laurent | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Simple jForms example for Jelix ====== | ||
+ | |||
+ | Here is a little tutorial to demonstrate how powerful is jForms, the Jelix form system. This tutorial is compatible with Jelix 1.3 and 1.4. | ||
+ | |||
+ | |||
+ | |||
+ | ===== Create your application ===== | ||
+ | |||
+ | First, let's create your application. After downloading a [[http:// | ||
+ | |||
+ | <code bash> | ||
+ | php createapp.php ../myapp | ||
+ | </ | ||
+ | |||
+ | Don't forget to change rights on @@F@< | ||
+ | |||
+ | An application skeleton is created. Your local tree structure should look like: | ||
+ | |||
+ | * myapp/ | ||
+ | * modules/ | ||
+ | * myapp/ | ||
+ | * classes/ | ||
+ | * controllers/ | ||
+ | * default.classic.php | ||
+ | * dao/ | ||
+ | * forms/ | ||
+ | * locales/ | ||
+ | * templates/ | ||
+ | * zones/ | ||
+ | * plugins/ | ||
+ | * responses/ | ||
+ | * var/ | ||
+ | * www/ | ||
+ | * lib/ | ||
+ | * temp/ | ||
+ | |||
+ | |||
+ | @@F@myapp/ | ||
+ | |||
+ | Last, copy the content of @@F@lib/ | ||
+ | |||
+ | ===== The contact form ===== | ||
+ | |||
+ | |||
+ | Now you're going to create a form. The only thing to do, is to create one XML file in the @@F@forms/ | ||
+ | |||
+ | <code xml> | ||
+ | <? | ||
+ | < | ||
+ | |||
+ | < | ||
+ | < | ||
+ | <item value=" | ||
+ | <item value=" | ||
+ | </ | ||
+ | |||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | |||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | |||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | |||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | You can see that it is a declarative format. It is easy to read and edit. | ||
+ | |||
+ | |||
+ | ===== Displaying the form ===== | ||
+ | |||
+ | Now you're going to display the form. First, modify the default controller, @@F@default.classic.php@@: | ||
+ | |||
+ | <code php> | ||
+ | class defaultCtrl extends jController { | ||
+ | |||
+ | function index() { | ||
+ | $view = $this-> | ||
+ | $view-> | ||
+ | $view-> | ||
+ | |||
+ | $f = jForms:: | ||
+ | $view-> | ||
+ | |||
+ | return $view; | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | On the first line, you retrieve an HTML view (a @@C@jHtmlResponse@@ object) with the @@M@getResponse()@@ method. Next, you set the title of the page (@@$view-> | ||
+ | In the @@P@bodyTpl@@ property, | ||
+ | |||
+ | Next, in the @@V@$f@@ variable, you put an instance of the contact form. jForms creates dynamically a class from the content of @@F@contact.form.xml@@ and the static method @@M@create()@@ returns an instance of this class. Note that this class inherits from the @@C@jFormsBase@@ class. | ||
+ | |||
+ | You pass @@V@$f@@ variable to an instance of a template engine (jTpl which works like smarty). It is stored in @@$view-> | ||
+ | |||
+ | Last line returns @@V@$view@@ object and Jelix **finishes the job**: the view will generate a page based on the given template file, @@F@main.tpl@@. | ||
+ | |||
+ | Let's create this template in @@F@myapp/ | ||
+ | |||
+ | <code php> | ||
+ | < | ||
+ | < | ||
+ | | ||
+ | </ | ||
+ | |||
+ | It uses the **formfull** template plugin, which accepts as arguments, a @@C@jFormsBase@@ object, and a selector of action. this is the action to be called after a submit on the form. | ||
+ | |||
+ | At this step, you can execute the action, @@http:// | ||
+ | |||
+ | {{en: | ||
+ | |||
+ | When testing this form, notice the check done on fields before the submit: some javascript code is generated automatically on this purpose. Anyway, here is the generated html code: | ||
+ | |||
+ | <code html> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | //< | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | // (snip other javascript code...) | ||
+ | // | ||
+ | </ | ||
+ | < | ||
+ | < | ||
+ | <th scope=" | ||
+ | <td> <select name=" | ||
+ | <option value=" | ||
+ | <option value=" | ||
+ | </ | ||
+ | </ | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | < | ||
+ | <th scope=" | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | < | ||
+ | <input type=" | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | Note also that form elements have CSS classes or IDs assigned to ease their design. | ||
+ | |||
+ | The **formfull** plugin generates the form in an HTML table. Of course there are alternatives. By using other plugins, Jelix allows you to control precisely the html generated. Let's change that in the main.tpl file. | ||
+ | |||
+ | <code html> | ||
+ | < | ||
+ | {form $form, " | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | {formcontrols} | ||
+ | < | ||
+ | < | ||
+ | {/ | ||
+ | </dl> | ||
+ | </ | ||
+ | < | ||
+ | | ||
+ | </ | ||
+ | |||
+ | The template above use the **form** plugin instead of **formfull**. Its arguments are identicals. The **formcontrols** plugin do a loop over the fields declared in the @@F@contact.form.xml@@ file (except submit and reset controls), and you can display the label and the field with **ctrl_label** and **ctrl_control**. **formsubmit** displays all submit controls. | ||
+ | |||
+ | Here is the result of this template : | ||
+ | |||
+ | |||
+ | {{en: | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ===== Handling submitted data ===== | ||
+ | |||
+ | Now you're going to create the action method indicated in the arguments of the **form** plugin. In the templates above, it is called ' | ||
+ | |||
+ | <code php> | ||
+ | function save() { | ||
+ | $view = $this-> | ||
+ | $view-> | ||
+ | |||
+ | $f = jForms:: | ||
+ | if(!$f || !$f-> | ||
+ | $view = $this-> | ||
+ | $view-> | ||
+ | return $view; | ||
+ | } | ||
+ | |||
+ | $view-> | ||
+ | $view-> | ||
+ | return $view; | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | To get the instance of the form, and by the same time to fill it with submitted data, use the @@M@fill()@@ method. Then, test if this instance doesn' | ||
+ | |||
+ | <code php> | ||
+ | $f = jForms:: | ||
+ | if(!$f) | ||
+ | $f = jForms:: | ||
+ | </ | ||
+ | |||
+ | Instead of just creating a new instance of the contact form, check before if there is an existing one. So HTML fields will be filled with datas previously submitted (and saved in the session). | ||
+ | |||
+ | Back to @@M@save()@@ method. After the @@$f-> | ||
+ | |||
+ | <code php> | ||
+ | if(!$f || !$f-> | ||
+ | |||
+ | $alldatas = $f-> | ||
+ | // or | ||
+ | $firstname = $f-> | ||
+ | if ($firstname == ' | ||
+ | /* goto home */ | ||
+ | } | ||
+ | // and so on. | ||
+ | </ | ||
+ | |||
+ | Finally, you could display submitted data and thanks the user. Here is the @@F@contact_ok.tpl@@ file: | ||
+ | |||
+ | <code html> | ||
+ | < | ||
+ | |||
+ | < | ||
+ | < | ||
+ | < | ||
+ | {formcontrols $form, array(' | ||
+ | < | ||
+ | < | ||
+ | {/ | ||
+ | </dl> | ||
+ | </ | ||
+ | |||
+ | <p>We will contact you. Thanks!</ | ||
+ | </ | ||
+ | |||
+ | Use again the **formcontrols** plugin, but in a standalone manner (not with a **form** plugin). Indicate as arguments your form object (@@$form@@), | ||
+ | |||
+ | {{en: | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ===== Conclusion ===== | ||
+ | |||
+ | |||
+ | That's all! It is really easy to use jForms, isn't it? You can: | ||
+ | |||
+ | * create a form | ||
+ | * display a form | ||
+ | * retrieve submitted data | ||
+ | * validate submitted data (this is done automatically !) | ||
+ | * display the form again with errors | ||
+ | |||
+ | With only one xml file and few lines of code! | ||
+ | |||
+ | And jForms has many other features, such as: | ||
+ | |||
+ | * create your own form " | ||
+ | * specify your own error messages | ||
+ | * localize everything | ||
+ | * manage how error messages are displayed | ||
+ | * display helps and tooltips | ||
+ | * fill menulist, listbox, (and so on) choices automatically, | ||
+ | * read and store data automatically still using a jDao object | ||
+ | * create quickly a CRUD controller, by using the @@C@jControllerDaoCrud@@ controller (only indicate a jforms file, a jdao file, and that's all !) | ||
+ | * and many other controls are availabled: **< | ||
+ | |||