<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE document PUBLIC "-//MAKUMBA//DTD Documentation V2.0//EN" "document-v20-mak.dtd">
<document>
  <header>
    <title>Creating and editing data: Makumba forms</title>
  </header>
  <body>

    <section>
      <title>Introduction</title>

      <p>Makumba can produce four types of forms: new, add, edit and generic forms. In adition to
        the forms, it is also possible to delete records. All forms have a number of common
        features: They can include <code>&lt;mak:input&gt;</code> tags. They all can have
          <code>action</code>, <code>method</code>, <code>handler</code>, <code>name</code> and
          <code>message</code> arguments. Forms can have handler methods, which are part of the
        Makumba Business Logics.</p>

      <p><strong>Non-generic (type specific) forms</strong><br/>New, edit and add forms are type
        specific. Their fields must be named after the fields in the respective type (and related
        fields).</p>

      <p><strong>Multiple forms</strong> Multiple forms is a powerful feature of Makumba which makes
        it possible to:</p>
      <ul>
        <li>embed several forms in one, so as to have only one submit button</li>
        <li>create or edit multiple data sets at once, in combination with <a href="/usage/list.html"
            >Makumba lists</a></li>
      </ul>

    </section>

    <fixme author="manu">link to all the form types</fixme>

    <section>
      <title>Basic form operations</title>


      <section>
        <title>Entering new data: newForm</title>
        <p>In order to create new data</p>

      </section>

      <section>
        <title>Editing existing data: editForm</title>
      </section>

      <section>
        <title>Adding data to sets: addForm</title>
      </section>

      <section>
        <title>Deleting data: delete and deleteLink</title>
      </section>

      <section>
        <title>Generic forms: form</title>
      </section>

    </section>

    <section>
      <title>Combining forms: multiple forms</title>

      <ul>
        <li>addForms can add to the subsets of object produced by the enclosing newForm</li>
        <li>any number of levels of form inclusion is possible but only the outermost form can have
          an action, onSubmit, and method and other attributes specific to HTML forms </li>
        <li>all form actions take place in a single transaction, which is rolled back by the
          controller filter if there is an error </li>
        <li>after_ methods are not executed in correct order (bug 689)</li>
      </ul>

      <source>
        <![CDATA[
  <mak:form action="somePage.jsp">
      <%-- the topmost form, will result in a HTML form, may or may not have logic, 
      or it can be a specialized form (new, edit, add...)
      --%>
      
      <mak:input name="someField" /> <%-- the topmost form can have fields of its own --%>
      
      <mak:list from="general.Person p"> 
        <mak:addForm object="p" field="adresses" >
          <%-- note that there is no action indicated here, it's the action of the 
          topmost form a normal on_add BL method will be called 
          --%>
          <mak:input name="someOtherField" /><%-- the topmost form can have fields of its own, 
          even repeated in loops 
          --%>
          ...
        </mak:addForm>
      </mak:list>
      
      <mak:list from="general.Car c" > <%-- there can be more than one loop in a root form -- %>
        ...
      </mak:list>
      <input type=submit> <%-- it's easy to add a submit button anywhere --%>
    </mak:form>
]]>
      </source>

    </section>

    <section>
      <title>Form submission: form actions, validation and business logics</title>

      <fixme author="manu">what happens at form submission (validation, authorisation, BL - in which
        order, where...), link to the relevant chapters.</fixme>

    </section>

    <section id="annotation">
      <title>Form annotation</title>
      <p>Form validation errors are either reported in the Makumba response which would be displayed
        on the form action page, or can for improved usability be annotated in the form itself. In
        the latter case, on a form validation error, the form page itself would be displayed again,
        and errors are displayed next to the inputs that failed validation. </p>
      <p>An example can be seen below:</p>

      <table>
        <tr>
          <td>age</td>
          <td>
            <ihtml><![CDATA[ <input name="age" value="1r" maxlength="10" id="age" type="text"> &nbsp; <span style="color: red; font-weight: bold">invalid integer: 1r</span> ]]></ihtml>
          </td>
        </tr>
        <tr>
          <td>weight</td>
          <td>
            <ihtml><![CDATA[ <input name="weight" value="24b" maxlength="10" id="weight" type="text"> &nbsp; <span style="color: red; font-weight: bold">invalid real: 24b</span> ]]></ihtml>
          </td>
        </tr>
      </table>

      <p> The annotation message will be put inside a <code>&lt;span
          class="formAnnotation"&gt;</code>; this CSS-class can be used to add custom formatting
        to the message.</p>

      <p> Reloading the form page on errors can be triggered by the attribute reloadFormOnError, the
        location of the annotation message by the attribute annotation. </p>
      <p>Additionally, form validation can be done also on the client-side, i.e. in the browser.
        Client-side validation can be either live, i.e. on entering data in an input, or before form
        submission; this is controlled by the attribute clientSideValidation.</p>

    </section>

    <section>
      <title>MOVE ME: Handler methods</title>

      <fixme author="manu">move this whole section to the BL part</fixme>


      <p>Handler methods (if they exist) are executed by the Makumba controller, when the form is
        submitted to another Makumba page. </p>

      <p>If there is a business logic class, the engine will look (once after each page compilation)
        for the corresponding handler method. The handler methods are executed before the default
        action and may prevent the action from being executed by throwing an exception. Some forms
        also have an after-action handler method. </p>
      <p>If the handler class exists but no handler method can be found, an error is thrown (the
        site is not allowed to do the operation, e.g. StudentHandler will never have a
        on_newLibraryBook() method). If the handler class wishes to allow the action, it can define
        an empty handler method. </p>

    </section>



  </body>
</document>