Quick links: Content - sections - sub sections
EN

Trace:

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
en:tutorials:simple-jforms-example [2008/03/04 13:38] – biboen: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 ====== +====== Simple jForms example for Jelix ======
- +
-Here is a little tutorial to demonstrate how powerful is jForms, the Jelix form system.+
  
 +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.
  
  
Line 8: Line 7:
 ===== Create your application ===== ===== Create your application =====
  
-First, let's create our application. After donwloading a [[http://jelix.org/articles/en/download/stable|jelix archive]], extract it to your <jelix folder> of choice. Navigate to ''<jelix folder>/lib/jelix-scripts/'' directory and type in a console:+First, let's create your application. After downloading a [[http://jelix.org/articles/en/download/stable|jelix archive]], extract it to your <jelix folder> of choice. Navigate to ''<jelix folder>/lib/jelix-scripts/'' directory and type in a console:
  
 <code bash> <code bash>
-  ./jelix --myapp createapp+  php createapp.php ../myapp
 </code> </code>
  
-Don't forget to change rights on ''<jelix folder>/temp/myapp/''. This will allow your web server to create files in this directory. ([[en:manual:installation|see installation manual]]).+Don't forget to change rights on @@F@<jelix folder>/temp/myapp/@@. This will allow your web server to create files in this directory ([[http://docs.jelix.org/en/manual-1.3/getting-started|see installation manual]] for details).
  
-An application skeleton is created. Your local tree structure shall look like:+An application skeleton is created. Your local tree structure should look like:
  
   * myapp/   * myapp/
Line 23: Line 22:
           * classes/           * classes/
           * controllers/           * controllers/
-          * default.classic.php+             * default.classic.php
        * dao/        * dao/
        * forms/        * forms/
Line 33: Line 32:
     * var/     * var/
     * www/     * www/
-  * lib/   (jelix libraries)+  * lib/   (Jelix libraries)
   * temp/   * temp/
  
  
-//myapp/// directory contains all files of your application. Note that there is another //myapp/// folder in //myapp/modules/// : by default **createapp** command creates a module with the same name of your application. This will be the main module.+@@F@myapp/@@ directory contains all files of your application. Note that there is another @@F@myapp/@@ folder in @@F@myapp/modules/@@: by default the **createapp** command creates a module with the same name of your application. This will be the main module.
  
-Then, copy the content of //lib/jelix-www/// into //myapp/www/jelix// (or can declare an alias in apache, if preferred).+Last, copy the content of @@F@lib/jelix-www/@@ into @@F@myapp/www/jelix@@ (or you can declare an alias in apache, if preferred).
  
 ===== The contact form ===== ===== The contact form =====
  
  
-Now we're going to create a form. The only thing to do, is to create one xml file in the //forms/// directory. We call it contact.form.xml. Here is its content:+Now you're going to create a form. The only thing to do, is to create one XML file in the @@F@forms/@@ directory. Call it @@F@contact.form.xml@@. Here is its content:
  
 <code xml> <code xml>
  <?xml version="1.0" encoding="utf-8"?>  <?xml version="1.0" encoding="utf-8"?>
- <forms xmlns="http://jelix.org/ns/forms/1.0">+ <form xmlns="http://jelix.org/ns/forms/1.1">
    
    <menulist ref="title">    <menulist ref="title">
Line 71: Line 70:
      <label>Contact us</label>      <label>Contact us</label>
    </submit>    </submit>
-  </forms>+  </form>
 </code> </code>
  
-You can see that it is a declarative format. So it is easy to read and edit.+You can see that it is a declarative format. It is easy to read and edit. 
  
 ===== Displaying the form ===== ===== Displaying the form =====
  
-Now we're going to display the form. First you modify the default controller, default.classic.php:+Now you're going to display the form. First, modify the default controller, @@F@default.classic.php@@:
  
 <code php> <code php>
Line 89: Line 89:
    
         $f = jForms::create("myapp~contact");         $f = jForms::create("myapp~contact");
-        $view->tpl->assign('form', $f );+        $view->body->assign('form', $f );
    
         return $view;         return $view;
Line 96: Line 96:
 </code> </code>
  
-At the first line, we retrieve an HTML view (a jHtmlResponse object) with the **getResponse()** method. Then we set the title of the page (**$view->title**). +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->title@@). 
-In the **bodyTpl**, we indicate the template to use for the main content of the page (the content of the body tag of a html page; the html header is generated automatically by the view). The given string is called a __selector__ in Jelix. A selector specifies a resource in a module. Its syntax is "moduleName~resourceName". So here, we says that the template will be the //templates/main.tpl// file in the myapp module.+In the @@P@bodyTpl@@ property,  you indicate the template to use for the main content of the page (the content of the body tag of a HTML page; HTML header is generated automatically by the view). The given string is called a __selector__ in Jelix. A selector specifies a resource in a module. Its syntax is "moduleName~resourceName". Here, you simply say that the template will be @@F@templates/main.tpl@@ file in //myapp// module.
  
-Next, in the **$f** variable, we put an instance of the contact form. jforms creates dynamically a class from datas which are in the contact.form.xml and the "create" method creates an instance of this class. Note that this class inherits from the jFormsBase class.+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.
  
-Then we pass the **$f** variable to an instance of a template engine (jTpl which works like smarty) stored in **$view->body**.+You pass @@V@$f@@ variable to an instance of a template engine (jTpl which works like smarty). It is stored in @@$view->tpl@@.
  
-At the end, we return the **$view** object and Jelix will end the job : the view will generate the page with the given template file, //main.tpl//.+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@@.
  
-Now let's create this template in //myapp/templates/// directory :+Let's create this template in @@F@myapp/templates/@@ directory:
  
 <code php> <code php>
Line 113: Line 113:
 </code> </code>
  
-We use the template plugin **formfull**, which accepts as arguments a **jFormsBase** object, and the selector of the action where to submit datas.+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://localhost/jelix/myapp/www/**  (or **http://localhost/jelix/myapp/www/index.php?module=myapp&action=default:index**, this is the same +At this step, you can execute the action, @@http://localhost/jelix/myapp/www/@@  (or @@http://localhost/jelix/myapp/www/index.php/myapp/default/index@@, this is the same thing because this action is the default one of the application), and watch the results:
-thing because this action is the default one of the application), and you see the result :+
  
 +{{en:tutorials:simple-forms-example-1.png}}
  
-When testing this form, you can see that a check is done on fields before the submit : some javascript code are generated automatically. Here is the generated html code :+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> <code html>
- <form action="/jelix/myapp/www/index.php" method="post" id="jform1" onsubmit="return jForms.verifyForm(this)"> + <form action="/jelix/myapp/www/index.php/myapp/default/save" method="post" id="jform1" onsubmit="return jForms.verifyForm(this)"> 
- <div> + <div></div>
-      <input type="hidden" name="module" value="myapp"/> +
-      <input type="hidden" name="action" value="default:save"/> +
- </div>+
  <script type="text/javascript">  <script type="text/javascript">
  //<![CDATA[  //<![CDATA[
Line 134: Line 131:
  jForms.tControl = new jFormsControl('title', 'Title', 'string');  jForms.tControl = new jFormsControl('title', 'Title', 'string');
  jForms.tControl.required = true;  jForms.tControl.required = true;
- jForms.tControl.errRequired='La saisie de "Title" est obligatoire'; + jForms.tControl.errRequired='"Title" input is required'; 
- jForms.tControl.errInvalid ='La saisie de "Title" est invalide';+ jForms.tControl.errInvalid ='"Title" input is invalid';
  // (snip other javascript code...)  // (snip other javascript code...)
  //]]>  //]]>
Line 167: Line 164:
 </code> </code>
  
-Note that some CSS classes facilitate the designing of the form. **formfull** plugin generate the form in an HTML table, but of course you can change this, by using other plugins, which allow you to control how to generate html. Let's change that in the main.tpl file.+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> <code html>
  <h2>jForm example</h2>  <h2>jForm example</h2>
- {form $form, "myapp~default:save", array(),'','','post'}+ {form $form, "myapp~default:save", array(),'html', array('method'=>'post')}
   <fieldset>   <fieldset>
      <legend>Please fill out this form:</legend>      <legend>Please fill out this form:</legend>
Line 185: Line 184:
 </code> </code>
  
-We use here the **form** plugin instead of **formfull**. Its arguments are same. **formcontrols** plugin do a loop over the fields declared in the contact.form.xml (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.+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 : Here is the result of this template :
  
  
-===== Handling datas after a submit =====+{{en:tutorials:simple-forms-example-2.png}}
  
-Now we're going to create the save method indicated in the arguments of the **form** plugin. We add this methods in default.classic.php.+ 
 + 
 + 
 + 
 +===== 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 'save'. Add this method in @@F@default.classic.php@@.
  
 <code php> <code php>
Line 201: Line 206:
         $f = jForms::fill("myapp~contact");         $f = jForms::fill("myapp~contact");
         if(!$f || !$f->check()) {         if(!$f || !$f->check()) {
-            $rep = $this->getResponse('redirect'); +            $view = $this->getResponse('redirect'); 
-            $rep->action="myapp~default:index"; +            $view->action="myapp~default:index"; 
-            return $rep;+            return $view;
         }         }
    
Line 212: Line 217:
 </code> </code>
  
-To get the instance of the form, and by the same time to fill it with submitted datas, we use the **fill** method. Then we test if this instance doesn't exist (**!$f**) or if there are bad datas (**!$f->check()**). If this is the case, we made a redirection to the first action and then the form will be displayed again with error messages: this is automatic ! However, we should change the index method. Replace **$f = jForms::create("myapp~contact");** by +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't exist (@@!$f@@) or if there are bad data (@@!$f->check()@@). If this is the case, make a redirection to the first action (displaying the form). The form will be displayed again with error messages included: this is automatic! However, you should change slightly the index method. Replace @@$f = jForms::create("myapp~contact");@@ by 
  
 <code php> <code php>
Line 220: Line 225:
 </code> </code>
  
-So here, we try to get an existing instance of the form, and if not, we create a new instance.+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).
  
-In **save** method, after the test, this is the opportunity to execute business code (not shown in this tutorial). For example:+Back to @@M@save()@@ method. After the @@$f->check()@@, you could insert some business code (not shown in this tutorial). For example:
  
 <code php> <code php>
 +    if(!$f || !$f->check()) { ... }
 +
     $alldatas = $f->getDatas();     $alldatas = $f->getDatas();
 +    // or
     $firstname = $f->getData('firstname');     $firstname = $f->getData('firstname');
-    // etc.+    if ($firstname == 'E.T.') {  
 +        /* goto home */ 
 +    } 
 +    // and so on.
 </code> </code>
  
-And at the end of the process, we could display submitted datas and says thank you. Here is the contact_ok.tpl file:+Finally, you could display submitted data and thanks the user. Here is the @@F@contact_ok.tpl@@ file:
  
 <code html> <code html>
Line 236: Line 247:
  
   <fieldset>   <fieldset>
-     <legend>Datas you have submited.</legend>+     <legend>Data you have submitted.</legend>
      <dl>      <dl>
       {formcontrols $form, array('title','lastname','firstname','email')}       {formcontrols $form, array('title','lastname','firstname','email')}
Line 245: Line 256:
    </fieldset>    </fieldset>
    
-  <p>We will contact us. Thank you !</p>+  <p>We will contact you. Thanks!</p>
 </code> </code>
  
-We use again the **formcontrols** plugin, but in a standalone manner (so not with a **form** plugin). We indicate as arguments the jFormsBase object (**$form**), and the list of controls to display (it is optional).+Use again the **formcontrols** plugin, but in a standalone manner (not with a **form** plugin). Indicate as arguments your form object (@@$form@@), and the list of controls to display (those are optional). 
 + 
 +{{en:tutorials:simple-forms-example-3.png}} 
 + 
 + 
 + 
 + 
  
 ===== Conclusion ===== ===== Conclusion =====
  
  
-That's all ! We saw how it is easy with jForms :+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
  
-  * to create a form +With only one xml file and few lines of code!
-  * to show a form +
-  * to retrieve submitted datas +
-  * to validate submitted datas (this is done automatically !) +
-  * to show the form again with errors+
  
-Notice that jForms has many other features, which allow you :+And jForms has many other features, such as:
  
-  * to create your own form "builder", so plugins could displays the form, not in HTML, but in other format like Xforms, XUL, or in HTML+ajax etc. +  * create your own form "builder", so plugins could displays the form, not in HTML, but in other format like Xforms, XUL, or in HTML + your prefered ajax library. 
-  * to specify your own error messages +  * specify your own error messages 
-  * to manage how error messages are displayed +  * localize everything 
-  * to display helps and tooltip +  * manage how error messages are displayed 
-  * to fill menulist, listbox etc automatically, from a jDao object (the ORM layer of Jelix) +  * display helps and tooltips 
-  * to store automatically datas with a jDao object +  * fill menulist, listbox, (and so on) choices automatically, using a @@C@jDao@@ object (ORM layer of Jelix) 
-  * to create quickly a CRUD controller, by using the jControllerDaoCrud controller (only indicate a jforms file, a jdao file, and that's all !) +  * read and store data automatically still using a jDao object 
-  * and many other controls are availabled: **<textarea>**, **<listbox>**, **<checkbox>**, **<checkboxes>**, **<radiobuttons>**, **<reset>**,   **<secret>**, **<secret>**+**<confirmation>**, **<upload>** +  * create quickly a CRUD controller, by using the @@C@jControllerDaoCrud@@ controller (only indicate a jforms file, a jdao file, and that's all !) 
-  * some others will be available soon:  **<htmleditor>** **<hidden>**...+  * and many other controls are availabled: **<textarea>**, **<htmleditor>**,  **<wikieditor>**, **<captcha>**, **<listbox>**, **<checkbox>**, **<checkboxes>**, **<radiobuttons>**, **<reset>**,   **<secret>**, **<secret>**+confirmation, **<upload>** etc...
  
  

en/tutorials/simple-jforms-example.1204637881.txt.gz · Last modified: 2008/03/05 10:09 (external edit)

Recent changes RSS feed Creative Commons License