title

FreeMarker widgets for displaying data

The following macros are working very closely with the Struts actions of the Tiny Marbles Framework. The main purpose it to show data in form of lists with rows, columns, filter and pagination. For that reason each action or class which uses these widgets (in the related FreeMarker template) has to import the class org.cws.webcore.FilterHibernate and provide a public method getFilter().  

@data.table

Shows a table with the given collection of elements. In combination with the macros below like @data.column and @data.pagination it is a powerful macro and used in the admin pages of Tiny Marbles CMS to show data objects in form of tables (=list with rows and columns).

Parameters of @data.table:

label (required)
text for the table title. elements (required)
a collection of elements to be shown in the table. showHeader (optional boolean, default 'true')
if true the header of the table is shown with a title given in the label. dataResultCssClass (optional, default empty)
adds a CSS class to the element <div> which frames the table. id (optional, default 'dataTable')
id of the table. cssTableClass (optional, default empty)
adds a CSS class to the table. cssEmptyClass (optional, default empty)
adds a CSS class for an empty table. rowIdAttribute (optional, default 'id')
fetches the id for the row of the table from property 'id' of the collection. If the
property has another name you can specify this name here.
rowCssClass (optional, default empty)
adds a CSS class to the row. onMouseOver (optional, default empty)
JavaScript, used for the event onmouseover of a table row. onMouseOut (optional, default empty)
JavaScript, used for the event onmouseout of a table row. headerAsLink=false (optional boolean, default 'false')
adds a link to the header of the table. headerLink (optional, default '#')
value of the link for the header of the table. headerOnClick (optional, default empty)
JavaScript for the header on click. headerClass (optional, default 'header')
adds a CSS class to the header. url (optional, default empty)
url for links and pagination. Pagination is created automatically in case url is not
empty. Is passed to the macros @data.column and @data.pagination which are used
internally.
param (optional, default empty)
parameter for the url for links and pagination. Is passed to the macros @data.column
and @data.pagination which are used internally.
jsFunction (optional, default empty)
JavaScript, is passed to the macros @data.column and @data.pagination which are used
internally.
onPageNumberClick (optional, default empty)
JavaScript, is passed to the macro @data.pagination which is used internally. onClick (optional, default empty)
JavaScript, is passed to the macros @data.column and @data.pagination which are used
internally.
paginationLinkFirst (optional, default '<img src='${base}/webcore-static/images
/first.png' alt='first'/>')
link for pagination, link: 'first page'. paginationLinkPrevious (optional, default '<img src='${base}/webcore-static/images
/previous.png' alt='previous'/>')
link for pagination, link: 'previous page'. paginationLinkNext (optional, default '<img src='${base}/webcore-static/images/next.png'
alt='next'/>')
link for pagination, link: 'next page'. paginationLinkLast (optional, default '<img src='${base}/webcore-static/images/last.png'
alt='last'/>')
link for pagination, link: 'last page'. paginationShowItemsFound (optional boolean, default 'true')
if true the total number of elements are shown in pagination. paginationBeforePageNumber (optional, default empty)
decoration before page number of pagination. Could be virtually any character,
usually '|' or '['.
paginationAfterPageNumber (optional, default empty)
decoration after page number of pagination. Could be virtually any character,
usually '|' or '['.

Example for @data.table:

<@data.table id="users" elements=filter.result.elements 
   label="user.list" url="/list.action"; user>
   <@data.column label="Login" sortBy=["login:asc"]>${user.login}</@data.column>
   <@data.column label="Name" sortBy=["name:asc"]>${user.name}</@data.column>
</@data.table>

Screenshot (example) for @data.table:

user_list.png

 

@data.column

Provides a column for the data table. Must be used as child of @data.table to build the dynamic table.

Parameters of @data.column:

label (required)
text to show for the title of the column. cssClass (optional, default empty)
a CSS class name for the row (<td> element). sortBy (optional, default empty)
name of the property of the object. Used for the sorter in the table header. Example:
["loginname:asc"].
fixedSortBy (optional, default empty)
name of the property of the object. Used for the second sort value for sorter in the
table header. Example: ["id:asc"].
id (optional, default empty)
id for the row (<td> element). onClick (optional, default empty)
JavaScript for the link element of the row, event on click. tdOnClick (optional, default empty)
JavaScript for the row (<td> element) itself, event on click. style (optional, default empty)
a CSS style for the row (<td> element).

Example for @data.column:

<@data.column label=action.getText("label.Zone.name") sortBy=["name:asc"]>
   <@show.link target="${base}/admin/zone/view.action?zone.id=${zone.id?c}"
      label="${zone.name?html}"/>
</@data.column>

 

@data.deleteColumn

This is a specialization of the @data.column. Provides a column with an image for the delete action. It has a multi-selection feature, that enables the user to select one or more items of the list to delete at the same time (using shift/control). Calls internally the @data.column macro. An overlay box appears to confirm the delete action, the delete action uses an Ajax call.

Parameters of @data.deleteColumn:

url (required)
url of the delete action (Struts) to delete the selected elements. paramId (required)
the name of the parameter id to be deleted, examples: 'versionId' or 'zoneId'. params (optional, default empty)
optional parameter for the url. cssClass (optional, default empty)
a CSS style to be passed to the macro @data.column. showDeleteButton (optional boolean, default 'true')
if set to true the macro shows the default delete button. If false, a nested code can
be used to show a customized delete button.
deleteAllowed (optional boolean, default 'true')
adds a CSS style to the delete button if delete is not allowed. obj (optional, default empty)
the object to be deleted. Internally used to get the id of the object to be deleted. onExecute (optional, default 'delete_elements')
JavaScript callback function name for when delete is executed. onUnCheck (optional, default 'unCheckDelete')
JavaScript callback function name for when a element is unchecked. onCheck (optional, default 'checkDelete')
JavaScript callback function name for when a element is checked. width (optional, default '500')
width of the confirmation overlay box. height (optional, default '120')
height of the confirmation overlay box.

Example for @data.deleteColumn:

<@data.deleteColumn obj=user showDeleteButton=false 
   url="${base}/admin/user/delete-form.action"
   paramId="users" width="524" height="188"
   params="active=${active}"; objId>
      <#if user?exists && (user.systemId?if_exists != defaultUserSystemId)
         && (user != currentUser) && deleteUser && user.active>
       <@data.deleteButton deleteAllowed=true objId=objId />
      </#if>
</@data.deleteColumn>

Screenshot (example) for @data.deleteColumn:

company_delete.png

 

@data.pagination

Shows the navigation for the pagination feature at the bottom of a data table. Usually used in combination with the macro @data.table, but it can also be used independantly, for example to add pagination to an article list or blog list of the public website.

Parameters of @data.pagination:

url (required)
url the links of pagination. labelItens (optional, default 'label.pagination.itensFound')
text for items found. max (optional, default empty)
optional parameter for the url. param (optional, default empty)
optional parameter for the url. anchor (optional, default empty)
optional anchor to be added at the link of the pagination. jsFunction (optional, default empty)
calls a JavaScript function in the link instead of an url. cssClass (optional, default empty)
adds a CSS class to the element <div> which frames the pagination. linkFirst (optional, default '<img src='${base}/webcore-static/images/first.png'
alt='first'/>')
link for pagination, link: 'first page'. linkPrevious (optional, default '<img src='${base}/webcore-static/images/previous.png'
alt='previous'/>')
link for pagination, link: 'previous page'. linkNext (optional, default '<img src='${base}/webcore-static/images/next.png'
alt='next'/>')
link for pagination, link: 'next page'. linkLast (optional, default '<img src='${base}/webcore-static/images/last.png'
alt='last'/>')
link for pagination, link: 'last page'. showItemsFound (optional boolean, default 'true')
if true the total number of elements are shown in pagination. beforePageNumber (optional, default empty)
decoration before page number of pagination. Could be virtually any character,
usually '|' or '['.
afterPageNumber (optional, default empty)
decoration after page number of pagination. Could be virtually any character,
usually '|' or '['.
onPageNumberClick (optional, default empty)
JavaScript executed when page number is clicked. showInactiveLinks (optional boolean, default 'false')
if true also inactive links of the pagination are shown. showAllPages (optional boolean, default 'false')
if true, all pages of the pagination are shown.

Example for @data.pagination:

<#local params = 
   "${params}&amp;channel=${(channel.systemId)!}&amp;request_locale=${locale?string}" />
<#assign hasPagination =
   elements?size gt 0 && (filter.result.hasNext() || filter.result.hasPrevious()) />
<#if hasPagination>
   <#if filter.sortOptions?exists>
      <#assign params =
         "${params}&amp;filter.sd=${filter.sd?lower_case}${data.createSortOptions()}" />
   </#if>
   <@data.pagination url=url param=params labelItens="pagination.News.view"
      linkFirst="" linkLast=""
      linkPrevious="<span class='back'>${action.getText('label.back')}</span>"
      linkNext="<span class='forward'>${action.getText('label.next')}</span>"
      showItemsFound=false cssClass="navPag"/>
</#if>

Screenshot (example) for @data.pagination:

pagination.png


title

FreeMarker widgets for showing information

@show.page

Shows the html header and body. This includes all necessary CSS (lookAndFeel) and Javascript files, the document type, and so on. Any content you nest in this tag will be added to the body.

Parameters of @show.page:

pageTitle (optional, default empty)
the page's main title. title (optional, default empty)
additional title. Separated from main title with '-'. defaultTitle (optional, default empty)
only used in MUM, CMS (admin): overwrites the title in the <h1> headline of the macro
@show.header (MUM). The value is passed to the parameter 'defaultTitle' of @show.header.
lookAndFeel (optional, default 'mum')
defines the look and feel (=laf) of the page. Default value is 'mum'. direction (optional, default empty)
declares the direction that the text should run: left-right or right-left. zoneStyle (optional, default empty)
adds a CSS style to the body. compatibility (optional, default empty)
compatibility meta tag for IE. onLoad (optional, default empty)
a JavaScript to execute when the body finishes loading.

 

@show.string

Shows a fieldset displaying a label and a property of an object. The object is usually described in the model and persisted in the database. Examples: User.name or Article.title. The property is shown as string. If parameter 'value' is empty any content you nest in this tag will be shown instead of the value.

Parameters of @show.string:

label (optional, default empty)
the label for the property. idLabel (optional, default empty)
The id for the label.. value (optional, default empty)
the value of the property, shown as <span>. idValue (optional, default empty)
The id for the value. title (optional, default empty)
the title which is used in label and value tag. cssClass (optional, default 'label')
a CSS class used for the fieldset. Default class: 'label'.

 

@show.text

Shows a fieldset displaying a label and a property of an object. Works similar like @string, but uses a <div> instead of a <span> for the property value.

Parameters of @show.text:

label (optional, default empty)
the label for the property. idLabel (optional, default empty)
The id for the label. value (optional, default empty)
the value of the property, shown as <div>. idValue (optional, default empty)
The id for the value. title (optional, default empty)
the title which is used in label and value tag. cssClass (optional, default 'label')
a CSS class used for the fieldset. Default class: 'label'.

 

@show.link

Shows an html <a> tag, safe against html hacking which is helpful in case the link information comes directly from the database. If paramater 'label' is empty any content you nest in this tag will be shown instead of the label.

Parameters of @show.link:

target (required)
url of the link target. label (optional, default empty)
link text to show (inside the <a> element). value (optional, default empty)
the value of the property, shown as <div>. title (optional, default parameter 'label' if exists or empty)
the link title (shown by most browsers as a tooltip). targetFrame (optional, default '_top')
defines which window will open by the link. onClick (optional, default empty)
a JavaScript to execute when the link is clicked. toolTip (optional, default empty)
a tooltip framed by a <span> element, shown after the label. cssClass (optional, default empty)
a CSS class used for the <a> element.

 

@show.tree

This highly specialized macro displays a draggabble tree starting from a root node. It also generates JavaScript controls for drag-and-drop operations associated with an update action. When a node A is dropped on node B, the tree calls an action to update the system, passing A's id as the source id and B's id as the target id.

The root element should be an object with a references to children which are displayed as the first-level elements of the tree. The tree searches for each element for its children property effectively displaying a tree of objects.

Parameters of @show.tree:

elements (required)
the children of the root element. Expects a collection of objects. updateAction (required)
url of the action that will be called to update the tree (drag/drop). srcParam (required)
name of the action paramater to pass the source node's id when a drop occurs. destParam (required)
name of the action parameter to send the target node's id when a drop occurs. rootId (optional, 'root.id')
the id of the root object. rootName (optional, default 'root.name')
the name of the root object to display as the label for the root node rootIcon (optional, default empty)
an icon to display for the root node. showRoot (optional, default 'true')
if set to 'false' the root node will be hidden and the tree starts with the children. editable (optional, default empty)
if true, allows to drag and drop the nodes. sortable (optional, default 'true')
if true, the order of the children of a node can be changed. highlight (optional, default empty)
an object that must be highlighted when encountered in the tree (usually used
for "the current value" kind of trees)

Nested content of @show.tree: Nested content is usually the @show.node macro.

Example for @show.tree:

<@show.tree 
    elements=childrenOfRoot
updateAction="${base}/admin/article/category/set-parent.action"
    srcParam="child.id"
    destParam="parent.id"
    rootId=0
    rootName=action.getText("label.ArticleCategory.tree.root")
    rootIcon="${base}/mum-static/images/tree/branch_active.gif"
    editable=editable?string
    sortable=true
  ; node, parentId>
   <@show.node id=node.id label=name ... >
       ...
   </@show.node>
</@show.tree>

Screenshot (example) for @show.tree:

tree_example.png

 

@show.node

Is used in combination with the macro @show.tree. It displays a draggable tree node.

Parameters of @show.node:

id (required)
The ID of the object to be displayed as a node. label (required)
the text to be displayed as the label of the node. editable (required)
if true, the node can de dragged. Should be passed from the macro @show.tree. draggable (optional, default 'true')
name of the action paramater to pass the source node's id when a drop occurs. droppable (optional, default 'true')
name of the action parameter to send the target node's id when a drop occurs. onClick (optional, default empty)
some JavaScript to execute when the node is clicked. icon (optional, default empty)
url of an image to use as node icon. tooltip (optional, default empty)
text to use as node tooltip ( title attribute). cssClass (optional, default empty)
a CSS class used for the <span> element which frames the label of the node. parentId (optional, default '-1')
the parentId should be passed from the macro @show.tree. requestedLocale (optional, default 'locale')
optional. If empty, it takes the locale of the basic action.

Nested content of @show.node: Whatever you nest inside the node will be considered additional content to be displayed when the user hovers the mouse over the node.

Example for @show.node:

<@show.node
    id=node.id
    label=node.name
    icon="${base}/pics/tree/leaf.gif"
    tooltip="drag node to move it">
  <@show.link obj=node idParam="groupId" label="Manage group" />
</@show.node>

 

@show.tabbedPane

This macro displays a tabbed pane with Ajax-filled tabs. The pane itself is filled with another FreeMarker template from the Ajax call. The look and feel of the tabbed pane is highly customizable. Frequently used in the administration area of MUM and CMS. See also @show.tab below.

Parameters of @show.tabbedPane:

name (required)
each tabbed pane on a page must have a unique name. active (optional, default empty)
if provided, the tab will automatically open with the given name. isBox (optional, default 'true')
displays a back box around the pane with a border. showHeader (optional, default 'true')
adds a header to the back box. showFooter (optional, default 'true')
adds a footer with round corners to the back box. headerRounded (optional, default 'false')
sets the header of the back box to round corners. cssClass (optional, default empty)
a CSS class used for the tabbedPane itself or the back box (if isBox==true).

 

@show.tab

Adds a tab to a tabbed pane (see @show.tabbedPane above). By default, tabs use an Ajax call to fetch content from the server and display it inside the tabbed pane using a FreeMarker template. If the content is fetched with Ajax, any forms it contains will be modified to submit their content using Ajax too.

Parameters of @show.tab:

name (optional, default empty)
name of the tab, must be unique within the pane. url (optional, default empty)
the url the tab-content is loaded using ajax.. title (optional, default empty)
a title for the tab link. newPage (optional, default 'false')
if true, the tab link will open in a new page. linkClass (optional, default empty)
an extra CSS class for the tab link. iconClass (optional, default empty)
an extra CSS class for the tab icon.
separator (optional, default '|')
an extra span with the given text will be shown (deprecated). processForm (optional, default 'true')
if true, process the forms in the HTML result to use an ajax hook from the tabbed pane.

Example for @show.tabbedPane and @show.tab:

<@show.tabbedPane name="userOps" cssClass="view" isBox=false active="user.edit">
   <#if modifyUser>
      <@show.tab name="user.edit" iconClass="editTab"
         url="${base}/admin/user/edit.action?user.id=${user.id?c}"
         showDivision=false />
   </#if>
   <#if createUser>
      <@show.tab name="user.create" iconClass="createUser"
         url="${base}/admin/user/create.action"
         showDivision=false />
   </#if>
   <#if changePassUser>
      <@show.tab name="user.change-password" iconClass="manageAuthorization"
         url="${base}/admin/user/edit-password.action?user.id=${user.id?c}"
         showDivision=false />
   </#if>
   <#if selectUserGroup>
      <@show.tab name="user.select-groups" iconClass="manageGroup"
         url="${base}/admin/user/select-group.action?user.id=${user.id?c}"
         showDivision=false />
   </#if>
</@show.tabbedPane>

Screenshot (example) for @show.tabbedPane and @show.tab:

tabbedPane.png

 

@show.tabContainer

This macro displays a container with tabs. Works similar to @show.tabbedPane but doesn't use Ajax calls for the container. The container itself is filled with the nested content of the @show.tabItem macro (see below). Usually filled with an unordered list <ul>. The container can be combined with Ajax using the callback parameters.

Parameters of @show.tabContainer:

id (required)
id for the container. beforeChangeCallback (optional, default empty)
JavaScript callback function called before activating a tab. afterChangeCallback (optional, default empty)
Javascript callback function called after activating a tab. activeCssClass (optional, default 'active')
a CSS class used for the active tab. cssClass (optional, default empty)
a CSS class used for the container and the tab list (<ul> element).

 

@show.tabItem

Adds a tab to a tab container (see @show.tabContainer above). The tab can be combined with Ajax using the onClick parameter.

Parameters of @show.tabItem:

id (required)
id for the container. label (required)
a text shown as a label for the tab. onClick (optional, default empty)
a JavaScript to execute when the tab is clicked. showTab (optional, default 'false')
if true, the tab is activated and the nested content is shown as tab item. fixed (optional, default 'false')
if true the value 'fixed' is added to the cssClass parameter. cssClass (optional, default empty)
a CSS class used for the tab itself (<li> element).

Example for @show.tabContainer and @show.tabItem:

<@show.tabContainer id="permissionsTab" activeCssClass="active" >
   <@show.tabItem id="optionGroupPermission"
      label=action.getText("label.groupPermission.title")
      showTab=true cssClass="active">
         <ul class="list" id="availableGroupPermission">
            <#list groupPermissions?keys as key>
               <#if key_index % 2 == 0>
                  <#assign cssClass = "even" />
               <#else>
                  <#assign cssClass = "" />
               </#if>
               <li class="${cssClass}" ... </li>
            </#list>
         </ul>
   </@show.tabItem>
   <@show.tabItem id="optionSinglePermission"
      label=action.getText("label.simplePermission.title")>
         <ul class="list" id="availableSimplePermission">
            <#list simplePermissions?keys as key>
               <#if key_index % 2 == 0>
                  <#assign cssClass = "even ${cssClass}" />
               <#else>
                  <#assign cssClass= "" />
               </#if>
               <li class="${cssClass}" ... </li>
            </#list>
         </ul>
   </@show.tabItem>
</@show.tabContainer>

Screenshot (example) for @show.tabContainer and @show.tabItem:

tabbedContainer.png


title

FreeMarker widgets for information input

@edit.form

Displays a form to edit an object. In combination with the macros below like @edit.field, @edit.string, @edit.text, @edit.hidden ... it is pretty smart and powerful macro and virtually always used in the admin pages of Tiny Marbles CMS to create, save or update objects. It is prepared for the usage of Ajax.

Parameters of @edit.form:

id (optional, default empty)
id of the form. name (optional, default parameter id)
name of the form. If empty, the parameter 'id' is used. formAction (optional, default empty)
the url value for the form action. title (optional, default empty)
a title for the form. If provided, text is shown inside an <h2> tag. method (optional, default 'post')
the form submission method, as described in HTML specification. onSubmit (optional, default empty)
JavaScript code to be executed upon submit. Here you can place the Ajax call if needed. target (optional, default empty)
the target. enctype (optional, default 'application/x-www-form-urlencoded')
encryption type. enableToken (optional boolean, default 'true')
creates a token for preventing double submission (used with Struts). cssClass (optional, default empty)
a CSS class used for the <div> element which frames the form.

Form confirmation: Some actions require a special confirmation token to prevent hacking scripts and <img> calls. The macro tests if a confirmation id is required and generates a hidden field called confirmationId for it.

Example for @edit.form:

<@edit.form id="updateUser" formAction="${base}/admin/user/update.action">
   <@edit.hidden name="user.id" value=user.id?c />
   <@edit.string name="user.name" size="40" required=true />
   <@edit.password name="user.password" size="40" />
   <@edit.controls>
      <@edit.button label=action.getText("control.User.submit") />
   </@edit.controls>
</@edit.form>

 

@edit.field

Shows a fieldset displaying a label and a property of an object. It can only be used inside a form. Macros like @edit.string, @edit.text, @edit.hidden or @edit.password are using it internally. The property of the object is taken from the nested content of the calling macro. For example: @edit.string calls internally @edit.field and in this case the property is shown as <input type="text" ... />. The macro is automatically adding field errors that the validation of the Struts action generated.

Parameters of @edit.form:

name (required)
the property name for this field. required (boolean, required)
if true, will style the field with a CSS class "required_field". label (optional, default empty)
the label for the property. showErrorAsLabel (optional boolean, default 'false')
Default: errors are shown below the property field. If set to 'true', errors are shown
as labels.
cssClass (optional, default empty)
a CSS class used for the <fieldset> element which frames the label and fields.

 

@edit.string

Shows an <input type="text" /> element to edit a property of an object. It can only be used inside a form. Internally it calls the macro @edit.field and displays the input element with a label framed by a fieldset. Field errors are automatically added that the validation of the Struts action generated.

Parameters of @edit.string:

name (required)
the property name for this field. id (optional, default empty)
the id for the input field. value (optional, default empty)
the value for the property, shown as <input type="text" ... />. label (optional, default empty)
the label for the field. required (optional boolean, default 'false')
if true, will style the field with a CSS class "required_field". Is passed to @edit.field. size (optional, default '25')
the size of the input field in characters. CSS styling is preferrable to HTML size
changes, so override this option with care.
maxLength (optional, default empty)
the maxLength of the input field. readOnly (optional boolean, default 'false')
sets the input field to read only. disabled (optional boolean, default 'false')
disables the input field. onClick (optional, default empty)
JavaScript code to be executed on click. onChange (optional, default empty)
JavaScript code to be executed on change. onKeyUp (optional, default empty)
JavaScript code to be executed on key up. onKeyDown (optional, default empty)
JavaScript code to be executed on key down. prefixValue (optional, default empty)
a value to be displayed right before the %lt;input> element framed by <span>. showEmptyPrefix (optional boolean, default 'false')
if set to true it shows the <span> right before the %lt;input> element although
prefixValue is empty.
showErrorAsLabel (optional boolean, default 'false')
Default: errors are shown below the property field. If set to 'true', errors are shown
as labels. Is passed to @edit.field.
cssClass (optional, default empty)
a CSS class used for the <fieldset> element which frames the label and fields. Is passed
to @edit.field.

 

@edit.text

Shows an <textarea /> element to edit a property of an object. Used for long texts inside a form. It can only be used inside a form. Internally it calls the macro @edit.field and displays the textarea element with a label framed by a fieldset. Field errors are automatically added that the validation of the Struts action generated.

Parameters of @edit.text:

name (required)
the property name for this field. id (optional, default empty)
the id for the textarea. value (optional, default empty)
the value for the property, shown as <textarea ... />. label (optional, default empty)
the label for the field. required (optional boolean, default 'false')
if true, will style the field with a CSS class "required_field". Is passed to @edit.field. col (optional, default '25')
default number of columns (in characters) for the text area. CSS styling is preferrable
to HTML size changes, so override this option with care.
rows (optional, default '10')
default number of rows (in lines) for the text area. CSS styling is preferrable to HTML
size changes, so override this option with care.
showErrorAsLabel (optional boolean, default 'false')
Default: errors are shown below the property field. If set to 'true', errors are shown
as labels. Is passed to @edit.field.
cssClass (optional, default empty)
a CSS class used for the <fieldset> element which frames the label and fields. Is passed
to @edit.field.

 

@edit.hidden

Shows a hidden field and can only be used inside a form. Hidden fields are not displayed inside @edit.form elements.

Parameters of @edit.hidden:

name (required)
the property name for this field. id (optional, default empty)
the id for the input field. value (optional, default empty)
the value for the property, shown as <input type="hidden" />.

 

@edit.password

Shows a password field (i.e. an <input> field with type "password") that works much like the @edit.string, except that it never displays a value. It can only be used inside a form. Field errors are automatically added that the validation of the Struts action generated.

Parameters of @edit.password:

name (required)
the property name for this field. id (optional, default empty)
the id for the input field. value (optional, default empty)
the value for the property, shown as <input type="password" ... />. label (optional, default empty)
the label for the field. required (optional boolean, default 'false')
if true, will style the field with a CSS class "required_field". Is passed to @edit.field. size (optional, default '25')
the size of the input field in characters. CSS styling is preferrable to HTML size
changes, so override this option with care.
js (optional, default empty)
allows you to pass a JavaScript event listener, like "onclick=alert('click');" readOnly (optional boolean, default 'false')
sets the input field to read only. cssClass (optional, default empty)
a CSS class used for the <fieldset> element which frames the label and fields. Is passed
to @edit.field.

Example for @edit.form, @edit.string and @edit.hidden: Please note the beautiful code using the MVC approach (Struts, Hibernate, Freemarker): you can easily pass the properties of the object 'User' to the template like for example: 'value=user.signature'.

<@edit.form id="updateUser" formAction="${base}/admin/user/update.action">
   <@edit.hidden name="user.id" value=user.id?c />
   <@edit.language name="user.locale"
      label=action.getText("label.User.locale")+":"
      value=user.locale supportedLocales=action.language.supportedAdminLocales />
   <@edit.string name="user.login" size="15"
      label=action.getText("label.User.login")+":"
      value=user.login required=true />
   <@edit.string name="user.signature" size="40"
      label=action.getText("label.User.signature")+":"
      value=user.signature required=true />
   <@edit.string name="user.email" size="40"
      label=action.getText("label.User.email")+":" value=user.email/>
   <@edit.controls>
      <@edit.button label=action.getText("control.User.submit") />
   </@edit.controls>
</@edit.form>

Screenshot (example) for @edit.form, @edit.string, @edit.hidden and validation (field error):

edituser.png

 

@edit.date

Provides an input field for a date with a JavaScript datepicker. The required date format is determined by the locale submitted by the browser and defaults to U.S. format. Field errors are automatically added that the validation of the Struts action generated.

Parameters of @edit.date:

name (required)
the property name for this field. id (optional, default empty)
the id for the input field. value (optional, default empty)
the value for the property, shown as <input type="text" ... />. label (optional, default empty)
the label for the field. required (optional boolean, default 'false')
if true, will style the field with a CSS class "required_field". Is passed to @edit.field. size (optional, default '25')
the size of the input field in characters. CSS styling is preferrable to HTML size
changes, so override this option with care.
showClear (optional, default empty)
shows a link to clear the field clearLabel (optional, default 'action.getText("label.date.clear")')
adds a label to the link to clear the field, gets the default label from
message.properties
clearLink (optional, default javascript: void(0);)
adds a value to the link to clear the field clearClick (optional, default $('${id}').value='';)
JavaScript snippet to clear the field cssClearClass (optional, default empty)
adds a CSS class to the link to clear the field readOnly (optional boolean, default 'false')
sets the input field to read only. cssClass (optional, default empty)
a CSS class used for the <fieldset> element which frames the label and fields. Is passed
to @edit.field.

Example for @edit.date:

<@edit.date name="article.publishDate" 
   value=publishDate?if_exists readOnly=true
   label="${action.getText('label.article.publishDate')}:" />

 

@edit.controls

Shows a control area to place submit, cancel or reset buttons inside a form. Uses the element <div> to frame the control elements and is used in combination with the macro @edit.button.

Parameters of @edit.controls:

id (optional, default empty)
the id for the <div> element. cssClass (optional, default empty)
a CSS class used for the <div> element which frames the control elements.

 

@edit.button

Adds a button of the type 'submit', 'image' or 'button' to the control area. Should be used with the macro @edit.controls.

Parameters of @edit.button:

label (optional, default empty)
the label to displayed for the button. id (optional, default empty)
the id for the button. type (optional, default 'submit')
the type for the button. Accepted are: 'submit', 'image' or 'button'. onClick (optional, default empty)
JavaScript code to be executed on click. image (optional, default empty)
the URL to an image to be displayed for the type 'image'. style (optional, default empty)
a CSS style added to the button. disabled (optional boolean, default 'false')
adds a CSS class with the value 'disabled' to the button. cssClass (optional, default empty)
a CSS class used for the <div> element which frames the control elements.

Example for @edit.form, @edit.controls and @edit.button:

<@edit.form id="touchConfirmArticle"  ... 
onSubmit="save('overlayBox','${base}/admin/article/touch.action',this); >
   <@show.boxMessage title=action.getText("tab.article.refresh") ... />
   <@edit.controls>
      <@edit.button name="touchArticle"
         label=action.getText("control.Article.touch.submit") />
      <@edit.button label=action.getText("control.cancel") type="button"
         onClick="closeOverlayBox()" />
   </@edit.controls>
</@edit.form>

Screenshot (example) for @edit.form, @edit.controls and @edit.button:

refresh.png

 

@edit.checkBox

Creates a fieldset with a checkbox and label or only a checkbox in case label is empty string.

Parameters of @edit.checkBox:

label (required)
the label to be displayed for the checkbox. If empty string, checkbox is shown without
label.
name (optional, default empty)
the name of the checkbox. id (optional, default parameter 'name' if exists or 'chbx')
the id of the checkbox. onClick (optional, default empty)
JavaScript code to be executed on click. onChange (optional, default empty)
JavaScript code to be executed on change. checked (optional boolean, default 'false')
if true, the checkbox will be checked when shown. required (optional boolean, default 'false')
a CSS class added if the checkbox is required. disabled (optional boolean, default 'false')
disables the checkbox. cssClass (optional, default empty)
a CSS class used for checkbox and fieldset.

 

@edit.radioGroup

Creates a fieldset for a radio button group with label or only a radio button group in case label is empty string. Should be used with the macro @edit.radioOption (see below).

Parameters of @edit.radioGroup:

label (required)
the label to be displayed for the radio button group. If empty string, the radio button
group is shown without label.
name (optional, default 'rd')
the name of the radio button group. required (optional boolean, default 'false')
a CSS class added if the radio button group is required. cssClass (optional, default empty)
a CSS class used for radio button group and fieldset.

 

@edit.radioOption

Creates a radio button like <input type='radio' ... />. Should be used with the macro @edit.radioGroup (see above).

Parameters of @edit.radioOption:

label (optional, default empty)
the label to be displayed for the radio button. value (optional, default empty)
the value of the radio button. name (optional, default empty)
the name of the radio button. id (optional, default empty)
the id of the radio button. onClick (optional, default empty)
JavaScript code to be executed on click. onChange (optional, default empty)
JavaScript code to be executed on change. checked (optional boolean, default 'false')
if true, the radio button will be checked when shown. cssClass (optional, default empty)
a CSS class used for radio button.

 

@edit.select

Creates a fieldset with a select box (drop down list) and a label. In case you pass a collection of elements to the macro, it creates the option tags automatically. You can also nest the option tag yourself using the @edit.option macro (see below) and get a bit more control over the option tag.

Parameters of @edit.select:

label (required)
the label to be displayed for the select box. name (optional, default empty)
the name of the select box. id (optional, default empty)
the id of the select box. elements (optional, default empty)
a collection of elements to be shown as options in the field. selectedElement (optional, default empty)
the name of the selected element to be shown as the selected option. isMuliple (optional boolean, default 'false')
if true it allows multiple selection in a select box. size (optional, default '0')
the size of the select box. onChange (optional, default empty)
JavaScript code to be executed on change. required (optional boolean, default 'false')
a CSS class added if the select box is required. disabled (optional boolean, default 'false')
disables the select box. cssClass (optional, default empty)
a CSS class used for select box and the fieldset.

Examples for @edit.select:

<@edit.select name="zoneId" elements=zones property="name" />

The call above creates a select for the zones on the login page of the Tiny Marbles CMS admin page. It creates a <select> tag with name zoneId. For each of the elements, it will show an option with the element's id as value and label defined by the element's name property, like this:

<select id="Login_zoneId" name="zoneId">
  <option value="80">MUM Zone</option>
  <option value="82">Example Zone</option>
</select>

Alternatively, you can use your own nested options, the call above is equivalent to this one:

<@edit.select name="zoneId" elements=zones ; el >
  <@edit.option value=el.id?c label=el.name />
</@edit.select>

 

@edit.option

Shows a select option, usually nested in select calls (see @edit.select above).

Parameters of @edit.option:

label (optional, default empty)
the option label, i.e. what is shown to the user. Nested content as option label. value (required)
the option value, i.e. what is sent to the server. id (optional, default empty)
the id of the option tag. selected (optional boolean, default 'false')
if true, the option will be marked as selected in the resulting HTML.

Examples for @edit.option:

Since there are already examples in the @edit.select above, here a complicated label and selection. Let's say you have a collection of Feed objects with two parameters, "title" and "url". You want to show the title, with the url in parenthesis:

<@edit.select name="feedId" elements=feeds ; el >
  <@edit.option value=el.id?c >
    ${el.title?html} (${el.url?html})
  </@edit.option
</@edit.select>