Makumba Specification

Makumba can produce four types of forms: new, add, edit and generic forms.

All forms have a number of common features: They can include <mak:input > tags. They all can have "action", "method", "handler", "name" and "message" arguments.

Handler methods (if they exist) are executed by the makumba controller, when the form is submitted to another makumba page.

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

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.

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.

Multiple forms
- addForms can add to the subsets of object produced by the enclosing newForm.
- 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.
- all form actions take place in a single transaction, which is rolled back by the controller filter if there is an error.
- after_ methods are not executed in correct order (bug 689)

<mak:form action="blabla">
<%-- 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="first" /> <%-- the topmost form can have fields of its own --%>

<mak:list .... > 
  <mak:addForm object="bla" field="bla" >
  <%-- 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="second" /><%-- the topmost form can have fields of its own, 
                                     even repeated in loops 
                                --%>
     ...
  </mak:addForm>
</mak:list>

<mak:list .... > <%-- 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>

(Later, new and edit forms that have no body, will build default forms. )

<mak:newForm  ...>.... </mak:newForm>

Makes a form for creating a new object of the indicated type.

Example (personNew.jsp):

<mak:newForm type="general.Person" action="personList.jsp" method="post">
        <mak:input name="name"/>
        <mak:input name="surname"/>
        <input type="submit">
</mak:newForm>

At form response, makumba (controller) invokes the following methods:

1. By defining on_new*, the handler class gets the opportunity to validate/change the data. If the data is not correct, the handler can throw an exception to prevent insertion in database.

   handler.on_newTypeName(data, attr, db);
   

2. The standard Database call for insertion:

   Pointer created= db.insert(type, data);
   

3. By defining after_new*, the handler class gets the opportunity to do supplementary operations with the inserted record.

   handler.after_newTypeName(created, data, attr, db);
   

If the handler class is present but both handler methods are missing (on_new and after_new), the action is not allowed.

At response the following calls are executed (in this order):

PersonLogic handler_obj; // see handler discovery
handler_obj.checkAttributes(attr, db);
handler_obj.on_newGeneralPerson(data, attr, db);
Pointer created= db.insert("general.Person", data);
handler_obj.after_newGeneralPerson(created, data, attr, db);

<mak:addForm  ...>.... </mak:addForm>

Makes a form for creating a sub-object of the mandatory enclosing <mak:object> (e.g. a language of a student, an address for a person).

Example:

<mak:object from="best.Student s" where="s=$student">
    <mak:addForm object="s" field="languages"
    		 action="studentView.jsp" method="post">
        <mak:value expr="s.name"/>
        <mak:input name="level"/>
        <mak:input name="comments"/>
    </mak:addForm>
</mak:object>

This will call the handler methods: (the argument names are adapted to the example. Note the changed pointer argument in the methods.)

on_addBestStudentLang(Pointer student, Dictionary languageData, Attributes pageParams, Database db)
after_addBestStudentLang(Pointer address, Dictionary languageData, Attributes pageParams, Database db)

<mak:editForm  ...>.... </mak:editForm>

Makes a form for editing the object indicated by any of the labels of the mandatory enclosing <mak:object> or <mak:list>. Also linked objects can be edited through the same form.

Example:

<mak:object from="best.Student s, s.person p" where="s=$student">
    <mak:editForm object="s" action="studentView.jsp" method="post">
        <mak:input name="person.name"/>
        <mak:input name="person.surname"/>
        <mak:input name="graduated"/>
    </mak:editForm>
</mak:object>

The response will call the handler method: (the argument names are adapted to the example)

on_editBestStudent(Pointer student, Dictionary fieldsToChange, Attributes pageParams, Database db)

<mak:form  ...>....</mak:form>

Creates a generic form, that may call a handler method in response. It allows the JSP author to make any kind of form. They are suitable for more complex operations than new, add, edit.

Example:

<mak:object from="best.Student s" where="s=$student">
    <mak:form handler="doSomething" action="studentView.jsp" method="post">
        <mak:input name="xxx" value="s.person.name"/>
        <input type=submit>
    </mak:form>
</mak:object>

<mak:input... />

An input field to be created, depending on the makumba type of the field. See the example for set/ptr choosers with Makumba.

scripts/makumba-javascript.html

The difference between <mak:input > and normal HTML <input> in a makumba form are:

• <mak:input> produces objects prepared for setting/comparing makumba fields (e.g. Pointer, Date, Text).
• the fields produced by <input> will be available as page $attributes but will all be of type String
• the fields produced by <mak:input> are available separately as a Dictionary to the handler method

<mak:object from="best.Student s, s.person p" where="s=$student">
    <mak:editForm object="p" action="studentView.jsp" method="post">
        name      <mak:input name="name"/>
        surname   <mak:input name="surname"/>
        gender    <mak:input name="gender" type="tickbox" />
        dob       <mak:input name="birthdate" format="yyyy-MM-dd" />
    </mak:editForm>
</mak:object>

Fields of related records can be reference and edited as well, via pointers. In this (somewhat strange) example, one can edit the name of the capital city of the country of which person is a citizen, through the person edit form :

<mak:input name="person.citizenship.capital.name" />

Restrictions for different field types:

• fixed fields: cannot be edited
• relational and index pointer: cannot be edited
• timestamps (create and modify): cannot be edited
• subset, subpointer: cannot be edited as a field, only as a separate object

<mak:option....>...</mak:option>

Text inside mak:option will become an option title. The value attribute will become the option. All text produced inside the mak:input that is not inside a mak:option must be blank!

If mak:option doesn't have a value indicated, it will produce a nil option. Such nil options will be ignored at form submission.

If an option value appears many times it will only be shown the first time it occurs.

<mak:input name="some" dataType="ptr T">
<mak:option>Please choose:</mak:option>
<mak:list from="T choice" where="someCondition" >
    <mak:option value="choice"><mak:value expr="choice.someField" /></mak:option>
</mak:list>
<mak:option> -------- separator----------</mak:option>
<mak:list from="T choice" where="someOtherCondition" >
   <mak:option value="choice"> <mak:value expr="choice.someField /></mak:option>
</mak:list>
</mak:input>

<mak:action>....</mak:action>

If the action URI of a form or deleteLink is more complex, possibly including other makumba tags, the action parameter of the form tag can be omitted, and the action URI can be indicated in a mak:action, anywhere inside the form tag.

Example:

<mak:editForm object="ins" method="post">
  <mak:action>memberView.jsp?person=<mak:value expr="p"/></mak:action>
...
</mak:editForm>

<mak:deleteLink>...</mak:deleteLink>

Produces a link to the page that will delete the object indicated by any of the labels of the mandatory enclosing <mak:object> or <mak:list>

Example:

<mak:object from="best.Student s, s.languages l"
	    where="s=$student AND l.lang.name=$langname">
	<mak:deleteLink object="l"  action="studentView.jsp">
		Delete <mak:value expr="l.lang.name"/>
	</mak:deleteLink>
</mak:object>

The response will call the handler method: (the argument names are adapted to the example)

on_deleteBestStudentLang(Pointer lang, Attributes pageParams, Database db)