!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|http://java.sun.com/products/servlet/] and [JSP 1.1 specification|http://java.sun.com/products/jsp/]. You will need a so-called "servlet container" that supports them both, such as [Apache Tomcat|http://jakarta.apache.org/tomcat/]. The corresponding __WEB-INF/taglib.tld__ is already included in the [distribution|download.html] {{makumba.jar}}.

Before using Makumba tags in your JSP pages you also need to declare the taglib with:
[{Code

 <%@ 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|http://java.sun.com/products/jsp/docs.html]
* [J2EE web services documentation by Sun|http://java.sun.com/webservices/tutorial.html]. This is an introduction on the various technologies that you might use when building webapplications using Java2 (J2EE).
* [Gentle introduction to JSPs|http://www.apl.jhu.edu/%7Ehall/java/Servlet-Tutorial/Servlet-Tutorial-JSP.html]

!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.
[{Code

        <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 (~\\).
[{Code

        <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.


%%(display:none;)[Category Documentation]%%
