Groovy Templates
1 Overview
This article gives a glance at the Groovy language, and explains how to configure the portlet and and the groovy template.
It's recommended to read also
AJAX in e Xo Framework in order to understand better the communication between the Groovy Template and the portlet.
2 Basic structure
The structure of a template is very easy :
- The HTML code
- zero or more groovy language code blocks, enclosed by <% … %>
The HTML code in the template doesn't have to contain the
html, or
body tags. Hence, you can use a groovy template for a component that will be rendered in another component.
Example :
UIPortalApplication.gtmpl template (
/eXoProjects/portal/trunk/web/portal/src/main/webapp/groovy/portal/webui/workspace/)
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<%
import org.exoplatform.webui.core.UIComponent;
def currentPage = uicomponent.getCurrentPage();
...
%>
...
<div class="$uicomponent.skin" id="UIPortalApplication">
<%uicomponent.renderChildren();%>3 Groovy language
Groovy is a scripting language for Java. Here are a few examples on how to use it, but you can find more information in
the full documentation.
This language looks like Java a lot, so it's very easy to use.
Examples :
Variables definition :
int min = 1;
def totalPage = uicomponent.getAvailablePage();
String name = "uiPortlet";
categories = uicomponent.getItemCategories();
String [] columns = uicomponent.getColumns();
Other expressions :
for(category in categories) { ... } // easy to use for loop
for(i in min..max) { ... } // min and max are int variables
println "</div>" ;
println """
<div class="Item">
<div class="OverflowContainer">
""";
<%=uicomponent.getToolbarStyle();%> // <%= to avoid a call of println method
import org.exoplatform.portal.config.model.PageNode;4 Linking a portlet with a template
4.1 Portlet configuration
The configuration of a portlet is partly made with
ComponentConfig annotations (others are ComponentConfigs, EventConfig, etc). One of the parameters of this annotation is called
template, where you can define the path to the template file associated with this portlet.
To specify this parameter to your portlet, just add this statement to your configuration annotation, for example in
/eXoProjects/portal/trunk/portlet/exoadmin/src/main/java/org/exoplatform/applicationregistry/webui/component/ you find
UIApplicationForm.java:
@ComponentConfig(
lifecycle = UIFormLifecycle.class,
template = "system:/groovy/webui/form/UIFormWithTitle.gtmpl",
events = {
@EventConfig(listeners = UIApplicationForm.SaveActionListener.class),
@EventConfig(phase = Phase.DECODE, listeners = UIApplicationForm.CancelActionListener.class)
}
)
You see that the path is in the namespace called "system", "system" is a reference to the portal webapp. In this webapp you find some reusable groovy templates, just open the folder
/eXoProjects/portal/trunk/web/portal/src/main/webapp/groovy/webui/form/ to see them.
As you want to create your own template, create a groovy file in your webbapp and refer to it. Please use the namespace "app" for refering to the same webapp as your component. eXo always puts the component templates in a folder like "/webapp/groovy/your_portlet_name/webui/component".
template = "app:/groovy/your_portlet_name/webui/component/your_component.gtmpl"
You can now edit your template file.
4.2 The template file
As we said before, the template file is composed of HTML code and groovy code blocks. There are a few things more that you need to know to fully link your portlet with your template.
If your template defines the UI of a component, you have an access to this component instance (the java object) using the variable
uicomponent. This should be the case almost all the time, but we recommend that you check that your java class inherits from UIComponent before you use this variable.
With this
uicomponent variable, you can access all the attributes and functions of your component, to use them in your template.
Example : UIPageIterator.gtmpl
<%
def currentPage = uicomponent.getCurrentPage();
%>
...
<a href="<%=uicomponent.event("ShowPage","$currentPage")%>" class="Icon LastTopPageIcon"><span></span></a>
This example shows that
uicomponent can be used to make Ajax calls, thanks to the
event method. See
AJAX in e Xo Framework for more details.
Another variable that you can use is
_ctx. It gives access to the context in which the template is processed. Hence, you can get some elements like the request, the Javscript manager, or the resource resolver (_ctx.appRes).
Examples :
<%
def rcontext = _ctx.getRequestContext() ;
rcontext.getJavascriptManager().importJavascript('eXo.webui.UIPopupWindow');
_ctx.appRes(popupId + ".title."+ title);
%>
If you use your template to define the user interface of a component that includes a form, you can access the instance of UIForm in a variable named
uiform. The UIForm class provides the methods,
begin() and
end(), that write the HTML tags of the form. Your form class must inherit from
UIForm, in this class you add the input elements (fields, checkboxes, lists) which you wish to use in your form. In your groovy template you can render your input elements using
uiform.renderfield(your_fieldname). The
uiform object also contains specific attributes and methods defined in your form class.
Example:
<div class="UISearchForm">
<%uiform.begin()%>
...
<%
quickSearchInputSet = uiform.getQuickSearchInputSet();
for(field in quickSearchInputSet.getChildren()) {
uiform.renderField(field)
}
%>
<%uiform.end()%>
</div>
