# Makumba Specification

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

## JSP taglib - listing

<mak:object> Attributes and OQL in <mak:list> and <mak:object> <mak:value/> mak:count(), mak:maxCount(), mak:lastCount() <mak:if> <mak:attribute> | ### <mak:list...>...</mak:list> Performs a query on the database. The body of the list, if present, is run once for every item in the resulting data (size 0..N), e.g. to display it. Queries are generated on the spot and can be nested. Example:
    <mak:list from="best.Student s, s.person p" where="p.gender=\"male\""
              orderBy="p.name">

        <c:if test="${mak:count()==1}">
           <p> There are ${mak:maxCount()} male students:
        </c:if>

        <br> <%= counter %>.
        <mak:value expr="p.name"/>
        <mak:value expr="p.surname"/> <br>
        <mak:list from="p.addresses a">
           <mak:value expr="a.streetno"/> <mak:value expr="a.city"/>
        </mak:list>
    </mak:list>

    <c:if test="${mak:lastCount()==0}"> There are no male students. </c:if>
tag parameter | description | comments
--- | --- | ---
`db` | The makumba database to connect to. The format is `Host_SQLEngineType_DatabaseName` If not present, the default database is used. See database configuration and lookup. | Fixed, cannot contain attributes, for now. The default database is chosen if this argument is not set. Can only be set for top-level (root) query tags Can be a Rtexpr <%= ...%>
`from` | OQL FROM section. If the query is nested, the keys from the parent's query are added to this FROM section in the resulting query | Fixed, Mandatory.
`variableFrom` | supplementary, variable OQL FROM section. | Fixed, can contain #{ JSP EL expressions }
`where` | OQL WHERE section. If the query is nested, the WHERE section from the parent's query, is added to this in the resulting query | Fixed, can contain #{ JSP EL expressions }
`groupBy` | OQL GROUP BY section | Fixed, can contain #{ JSP EL expressions }
`(having)` | OQL HAVING section | Fixed
`orderBy` | OQL ORDER BY section | Fixed, can contain #{ JSP EL expressions } `label.$fieldname used to be supported, not anymore`
`offset` | the offset of the result to show (0 for starting from the first result) | Fixed ($attribute allowed). Only allowed for the outermost mak:list
`limit` | the maximum numbers of results to show (-1 for all results) | Fixed ($attribute allowed). Only allowed for the outermost mak:list. LIMIT can limit the query time dramatically, but the children mak:lists are not yet limited.
`countVar` | The `java.lang.Integer` variable that will contain the number of the current iteration. | Fixed. A new Java variable is created, so no other variable by the same name can exist in the Java scope at that point in the JSP. Deprecated, use mak:count() expression language function instead
`maxCountVar` | The `java.lang.Integer` variable that will contain the total number of iterations. | Fixed. A new Java variable is created, so no other variable by the same name can exist in the Java scope at that point in the JSP. Deprecated, use mak:maxCount() expression language function instead
`separator` | Character string as separator between two list elements. It is not included before the first or after the last | D eprecated, use <c:if test="${mak:count<mak:maxCount()}"> instead.
`id` | Tag's identifier | Fixed. Can be used to distinguish otherwise identical tags on a page (to avoid confusion by Makumba's JSP analyser)
#### <mak:object ...>.... </mak:object> Like list, but the query can only have zero or one result. A zero value for `maxCountVar` and `countVar` indicate that the object does not exist. Example: See `<mak:list>`. #### Attributes and OQL in <mak:list > and <mak:object > Attributes are accessible through `$AttributeName` to any makumba tag. Typically they will be present in OQL sections instead of `$number` attributes (therefore the OQL sections of these tags is not "pure"). For example:
    <mak:list from="best.internal.Lbg"
              where="lbg.country=$country"
              orderBy="lbg.$lbg_order">
      .....
    </mak:list>
If a `$` (dollar) sign needs to be in the string, the escape is `$$`. If at the end of an attribute there has to be a Java identifier letter, the attribute name can be written as `text1$attrName$text2`, that is, with `$` at both ends. The http parameters are automatically set as page attributes. Other attributes can be set by the Java code as attributes in any scope (page, request, session, application) using `pageContext.setAttribute(name, value, scope)`. The query generator is setting all the attributes that are logically possible as prepared query parameters. For example, the $country above is a query parameter since it's a value, but the $lbg_order will not be accepted as query parameter, since it's a field name. If an attribute has multiple values, it is expanded into multiple OQL parameters. For example:
    <mak:list from="best.internal.Lbg" where="lbg.status in set($status)" >
(For view-level attributes such as lbg_order above, the value range can be defined by : `<mak:defineAttribute name="lbg_order" values="name, id" default="name"/>` ) (Later: Maybe the page might want to set attributes. Something like : `<mak:setAttr name="lbg" from="best.internal.Lbg lbg" where ... scope="session" />` Then the attribute could be used as `$lbg` in the rest of the page/session/application... Con: such stuff is normally done by the Java code. ) #### <mak:value .../> Displays the value of an expression from within the query. Example:
    <mak:list from="best.Student s, s.person p"
    	where="p.gender=\"male\"" orderBy="p.name">
        <mak:value expr="p.name"/>
        <mak:value expr="p.surname"/>
        <mak:value expr="p.birthdate" var="birth" printVar="printBirth"/>
        <% // we only print the birthdate if it's after some date
             if ( ((java.util.Date)birth).after(new java.util.Date(1980, 0, 1)) )
                 out.print(printBirth);
        %>
        <mak:value expr="s.person.favoriteQuote" maxLength="60" addTitle="auto" />
    </mak:list>
tag parameter | description | comments
--- | --- | ---
`expr` | OQL SELECT projection expression. It will be displayed if `var` nor `printVar` are not specified. | Fixed, Mandatory.
`var` | The value of the expression is set to a new `java.lang.Object` variable by this name, as well as to a page-scope attribute, also by the same name (accessible as `$attributename`). | Fixed. A new Java variable is created, so no other variable by the same name can exist in the Java scope at that point in the JSP. Note: the Java variable must be cast to its specific type (Integer, String, Date, Text, Pointer, Vector) before using it as such.
`printVar` | The formatted output as it would have been printed, is instead stored in a new `java.lang.String` variable by this name, as well as to a page-scope attribute by the same name (accessible as `$attributename`). | Fixed. A new Java variable is created, so no other variable by the same name can exist in the Java scope at that point in the JSP.
`urlEncode` | Indicates if the expression will be part of an URL or not. If "true", the output is URL-encoded. Default is "false". | Rtexpr.
`html` | Normal behaviour is to transform character output to its HTML escaped form. If this is "`true`", content is assumed to be HTML, and is not escaped. If "`auto`", heuristically checks the content for HTML tags and inhibits escape if there are any. Default is "`false`". | Rtexpr. Only char[] and text
`format` | Format string to specify the formatting of a date value, according to `java.text.SimpleDateFormat` | Rtexpr. Only for date. Defaults to "`dd MMMM yyyy`"
`lineSeparator` | Separator for long lines. If a text consists of short lines only, it will be surrounded by `<pre>...</pre>`. Default is "`<p>`". | Rtexpr. Only for text. Current implementation is buggy: separator is added before every long line, instead of between every long line.
`longLineLength` | The length of a long line. If a text contains long lines, it will be printed differently. See `lineSeparator`. Default is "30" | Rtexpr. Only for text.
`maxLength` | The maximum length (number of characters) to print. Longer output is cut off, and an `ellipsis` is added to indicate the cut. If not set (default), there is no maximum. | Rtexpr. Only applies for char[] AND if it is not already HTML formatted (cfr. `html`).
`ellipsis` | The character string to print to indicate that the text extended the `maxLength`. Default is "...". The final printed string, including the `ellipsis`, will not exceed `maxLength`. | Rtexpr
`ellipsisLength` | The equivalent character length of `ellipsis`. By default, this is the number of characters in `ellipsis`. But if `ellipsis` is e.g. HTML code, then that is not appropriate. | Rtexpr. Example, the ellipsis is an image of approx 3 characters wide. `ellipsis="<img src=icon.gif width=10 height=10>" ellipsisLength="3"`
`addTitle` | If "`true`", add an HTML tooltip with the value, to the printed output. If "`auto`", add tooltip only if the printed output is cut (cfr `maxLength`). Default is "`false`". | Rtexpr. Note: implementated by producing as output: `<span title="printVar">possibly-cut-printVar</span>`
`default` | The character string to print if the `expr` results in a NULL value. Default is `default=""` (i.e. zero-length string) Support not available for: date, "choice" = ptr, set, setCharEnum | Rtexpr
`empty` | The character string to print if the normal printed output would be empty (i.e. zero-length string). Therefore, this is also used for case `expr=NULL` and `default=""`. | Rtexpr
#### mak:count(), mak:maxCount(), mak:lastCount() These are JSP EL (expression language) functions that give information about the iterations in a list. mak:count() gives the number of the current iteration inside a mak:list or mak:object. It has no value outside that tag. mak:maxCount() gives the total number of iterations inside a mak:list or mak:object (1). It has no value outside that tag. mak:lastCount() gives the total number of iterations of the previous mak:list or mak:object, respectively. It has no value inside the mak:list/object. Note: if you want to store the value of some mak:list/object for usage in/after a later mak:list/object, you can do that with <c:set var="someVariableName" value="${mak:lastCount()}" just after that mak:list/object. Example using the Java Standard Tag Library (JSTL, prefix "c"):
    <mak:list ...>
       <c:if test="${mak:count()==1}">These are the list elements: </c:if>
       <tr bgcolor="${mak:count()%2==1?"white":"grey"}">
           <td>this shows in alternative colors</td>
       ...
       <c:if test="${mak:count()!=mak:maxCount()}">
           a separator where we can have any <b>tag</b>
           we don't want separators to be shown after the last element
       </c:if>
    </mak:list>
    <c:if test="${mak:lastCount()==0}">These are no elements </c:if>
#### <mak:if ...> ... </mak:if> Displays the body of the tag only if the OQL expression evaluates to true. Example :
    <mak:list from="best.Student s"
    	  where="s.person.birthdate <> nil" orderBy="s.name">
       <mak:value expr="s.person.name"/>
       <mak:if test="s.person.hideAge = 0">
          was born on <mak:value expr="s.person.birthdate" />
       </mak:if>
    </mak:list>
tag parameter | description | comments
--- | --- | ---
`test` | OQL SELECT projection expression. It must be a test, resulting in a 'boolean' in SQL : 0 or 1. for the test expressions: =, !=, <, <=, >, >= | Fixed, Mandatory. (in first implementation, this was called `expr`, but changed to reflect practice in XSL and JSTL)
#### <mak:attribute .../> Displays the value of an attribute, or sets it to a Java variable. Example:
    <mak:attribute name="pattern" var="pattern" exceptionVar="exception"/>

    <% if (exception!=null) {
         pageContext.setAttribute("pattern", (String)pattern+"%");
    %>
       <mak:list from="type t" where="t.field like $pattern" >...</mak:list>

    <% } else { %>
       No pattern argument. Please indicate one.
    <% } %>
tag parameter | description | comments
--- | --- | ---
`name` | the name of the attribute. Will be printed if `var` is not present and there is no exception when finding the argument. If there is an exception but `exceptionVar` is indicated, nothing will be printed. | Fixed, Mandatory.
`var` | The name of the `java.lang.Object` variable where to store the attribute value. Note that you will have to cast it to its specific type. | Fixed
`exceptionVar` | The name of the created `java.lang.Throwable` variable that will hold eventual exceptions raised when trying to compute the attribute. If `exceptionVar` is missing, any raised exception will stop page execution. If it is present, and `AttibuteNotFoundException` occurs, the attribute is set to `null` (so a next request for the attribute will return `null`) | Fixed
`db` | The database in which the business logic (if any) will compute the attribute. The default database is normally used. | Fixed