Proposed content by rudi

Pagination of results (<mak:list>, <mak:resultList>)#

When you retrieve more results from a <mak:list> or <mak:resultList> query than you would want to show to the user, you should utilise pagination. Pagination simply means you will display only a fixed number of n results on per page, and for the next results, the user has to click on a link/button to view the next n results. This technique is used e.g. in any web search engine.

Makumba provides integrated support for pagination both on regular data listing via the <mak:list> tag, as well as on displaying results of a search, using <mak:resultList>. This is achieved via the <mak:pagination> tag, which will display the current page number, the total page number, and will provide links to the first, previous, next and last page with data. <mak:pagination> makes use of the information provided by the enclosing <mak:list> or <mak:resultList>, i.e. the offset and limit, and automatically computes the total of rows that would be returned by the list, if no limit was specified.

If we want to print the list of employees, and only view 15 employees per page, we could do this as follows:

<mak:list from="company.Employee e" offset="$offset" limit="15">
  <mak:pagination action="employeeList.jsp" title="true" itemName="Employees" />
  <mak:value expr="e.nameSurname()"/>, born on <mak:value expr="e.birthdate" /> <br/>
  <mak:pagination action="employeeList.jsp" title="true" itemName="Employees" />
</mak:list>

This will create a pagination header and footer, before and after the list of employees. The exact meaning of the attributes can be seen in the <mak:pagination> reference documentation.

The attributes offset and limit define the status of the pagination, i.e. from which result to display on (offset), and how many results to display (limit). In the example, we take use for the offset attribute the parameter $offset, which is either a parameter to the page (e.g. employeeList.jsp?offset=30), or defined elsewhere in the page, before the <mak:list>. If the parameter is not present, then it will be assumed to be 0.

Navigation in the pagination is controlled by the attribute action, which defines the target page to go to when clicking on a pagination link.

Finally, the appearance is controlled by a set of attrbiutes: itemName is the the name of the items displayed, to be used in the text "Showing 'itemName' x out of y (Page z)", while paginationLinkTitle decides whether or not to display title="..." elements on the pagination links. Regarding layouting and formatting, the styleClass sets the CSS class used for the pagination elements, and defaults to makumbaPagination.

In the example above, the limit of items to be shown in the page was constant. However, often we want the user to chose how many items he wants to see at once. We can do this as follows:

<mak:list from="company.Employee e" offset="$offset" limit="$limit" defaultLimit="15">
  <mak:pagination action="employeeList.jsp" title="true" itemName="Employees" />
  <mak:value expr="e.nameSurname()"/>, born on <mak:value expr="e.birthdate" /> <br/>
  <mak:pagination action="employeeList.jsp" title="true" itemName="Employees" />
</mak:list>

In this case, we now also control the limit by a changeable value. As before with the $offset, the value can be set via a page-parameter (e.g. employeeList.jsp?offset=50&limit=25), or be defined somewhere in the page before the <mak:list>. If the value for $limit is not defined, the <mak:list> will instead default to the value given by defaultLimit.

Different input controls for <mak:input>#

for sets: multi select list vs. checkbox for enums: single select list vs. radio buttons for integer: spinner, ..

copy from http://old.makumba.org/makumba-spec.html#input

HTML INPUT type to be used

• "hidden" works for all fields
• for char , type can be "text" or "password", default is "text"
• default type for setintEnum, setcharEnum, ptr and set is "select" (dropdown or scroll list depending on size). Alternative is "tickbox" (checkboxes or radio buttons). Can be forced to a specific type by using "radio" or "checkbox"
• for set, type can be seteditor, which will create two multiple-select boxes (see an example).
• for int, spinner creates a spinner input with increase/decrease buttons; if a validation definition defines a range for the field, select and radio are will create select boxes and radio buttons.
• date is split in 3 inputs, <fieldname>_0 (day), _1 (month), _2 (year), and likewise for time elements
• for text, default is "textarea"; "file" will create file upload box, and will create supplementary attributes <fieldname>_filename, <fieldname>_contentType and <fieldname>_contentLength that have to be handled separately by the handler method
• for file, a file upload box will automatically created, and handling of file name, content type and length will be done automatically.

Controlling the values displayed in ptr/set inputs#

From http://old.makumba.org/makumba-spec.html#choiceDisplay

By default, for pointer and set fields, mak:input will show a choser (selector) that includes the title of all possible options, ordered by that title. To change that behavior, the mak:input can include one or more mak:option. Options can be repeated using mak:list, c:foreach, and in general can appear inside any other tag.

Text inside mak:option will become an option title. The value attribute will become the option. Text inside the mak:input that is not inside a mak:option amd is not blank (whitespace) will be assumed to separate groups of options and will be rendered. For options that render HTML SELECTs, this is only accepted for multiple SELECTs which will create several SELECT boxes of equal size, one for each option group.

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>

Form validation#