# Makumba Specification

[Data Definitions] | [Query Languages] | [JSP tag library: Intro | Listing | Forms] | [Business Logics] | [Summary]

## Presentation with JSP taglib

Makumba Controller JSP tag parameters <mak:response/> | Data can be presented and edited per record and field. The current presentation language uses JSP taglibs and corresponding notation, but principles can be applied in any other HTML-centric presentation language such as PHP. ### Makumba in Java Server Pages Makumba offers a JSP custom tag library, that allows easy interaction (viewing, editing) with the data in your database, right from your HTML (actually, JSP) document. Since Makumba pages, are essentially JSP pages, a basic understanding of JSP will be helpful to make more advanced use of makumba. Same goes for knowing a bit of Java itself. But you can get a long way with just a few notions! Really. Makumba tags are written according to Servlet 2.3 specification and JSP 1.1 specification. You will need a so-called "servlet container" that supports them both, such as Apache Tomcat. The corresponding WEB-INF/makumba.tld is already included in the distribution `makumba.jar`. The example WEB-INF/web.xml can be found in Makumba cvs repository. Before using Makumba tags in your JSP pages you also need to declare the taglib with:
    <%@ taglib uri="http://www.makumba.org/presentation" prefix="mak" %>
A few resources on JSPs (don't be afraid to try first, read later) : JSP documentation by Sun J2EE web services documentation by Sun. This is an introduction on the various technologies that you might use when building webapplications using Java2 (J2EE). Gentle introduction to JSPs #### Makumba Controller The makumba controller is a component running in the 'servlet container'. When a request for a makumba page enters the servlet container, the controller will intercept the request, and perform its "controller" activities (cfr. the model-view-controller pattern) : checking if the page has the appropriate attributes (see handler initialisation; e.g. force login). checking if the page request is the result of a form submit or a deleteLink. If so, perform the relevant actions in the handler and database. deal with problems (exceptions) during the controller activity: if `org.makumba.LogicException` is thrown, the Exception can write a message to the `<mak:response>` in the requested page. `org.makumba.UnauthenticatedException` and `org.makumba.UnauthorizedException` will force login (although UnauthorizedException probably shouldn't, bug 444) if another exception occurs, an errorPage will be shown instead of the requested page. For this to work, the correct configuration must be applied in `WEB-INF/web.xml` (example file). The following would tell the makumba controller to filter all requests for .jsp files.
      <filter>
         <filter-name>makumba_controller</filter-name>
         <filter-class>org.makumba.controller.http.ControllerFilter</filter-class>
      </filter>

      <filter-mapping>
        <filter-name>makumba_controller</filter-name>
        <url-pattern>*.jsp</url-pattern>
      </filter-mapping>
Note that if (in this example) the result page for a makumba form would be an `.html` page, then the makumba controller would not intercept the `.html` page request, and the actions implied by the form, would not be performed. #### JSP tag parameters JSP-tag parameter values are either FIXED or RTEXPR (runtime expression). A FIXED tag parameter must have a constant, literal value, while an RTEXPR can also be of the form <%= java_expression %>. On the other hand, some FIXED parameters can contain jsp attributes like $attr in makumba tags. All parameters are optional unless specifically mentioned as being mandatory. Specific concern can be the parameter quoting. Tag parameters can be written as name="value" or name='value' (note: the stringLiteral on DATE must be quoted with "). The choice of quote can be determined by the need to use either double or single quote as part of the value itself. If the quote is also present within the value, it must be escaped by a backslash.
      <mak:list from="general.Person p" where="p.gender=\"male\"" >
      <mak:list from="general.Person p" where='p.gender="male"' >
      <mak:list from="general.Person p" where="p.gender='male'" >
      <mak:list from="library.Book b" where="b.publisher=\"O'Reilly\" " >
      <mak:list from="library.Book b" where='b.publisher="O\'Reilly" ' >
Quotes in extra HTML formatting parameters, such as `styleClass`, `title`, `styleId`, `onClick` ... need some special attention with quotes. The parameter values are copied verbatim (with no modifications by makumba) to the resulting HTML, always surrounded with double quotes ("). This means that you have to use other quotes, like single one ('), If you need to pass a literal backslash (\) you have to escape it with a preceeding backslash (\\).
      <mak:input ... onClick="alert(this.value);"/>
      <mak:input ... onClick="alert('Hello world!');"/>
      <mak:input ... onClick="alert('Hello\\nWorld');"/>
Unfortunately the idea to use a sequence of escapes, eg writing \\\' in the JSP page to set the tag attribute to \', which could be handy for javascript tag attributes, is confusing the Tomcat servlet container. ### <mak:response/> `<mak:response/>` prints information about the results of the actions that were performed by the makumba controller (e.g. for a form submit or deleteLink): It either displays the `message="..."` parameter of the form tag (in green) in case of success, or (in red) the message of a uncaught `LogicException` resulting from Business Logic. Other exception types will provoke an exception page. The unformatted message is available as request-scope attribute `makumba.response`. The jsp page can get hold of the message using e.g.
    <% String s = (String) request.getAttribute("makumba.response") %>
Similarly, request-scope attribute `makumba.successfulResponse` is set only in case of successful action execution.
    <% if (null == request.getAttribute("makumba.successfulResponse")) { /* action failed */ } %>
(A body-tag style (`<mak:response>...</mak:response>`) will be added later, to display different messages for different circumstances (errors). It will also be possible to get hold of the actual exception object. )