UltraWork Web Toolkit

Web Toolkit - MC Examples and Taglib Documentation

Using Simple Components

Components are created using the ultrawork-wtk-mc taglib.

Components all share a common set of attributes :

The optional id attribute can be used to provide a unique identifier to the component, for example to later reference it inside of another component.

The optional name attribute can be used to reference another component.

The optional scope attribute specifies the scope under which the component must be stored. It requires an id attribute to be provided. Scope value can be page , request or application . If no scope is specified, the component will stored by the ComponentManager class.

The optional position attribute determines the position that the component will occupy inside of a container. This attribute can only be used if the component is nested inside of a mc:container or a mc:page tag.

Creating a Text

Text components are created using the mc:text tag.

The optional label attribute specifies the label of the text.

The optional key attribute specifies the key that must be used to lookup the text in the application ResourceBundle. The application ResourceBundle is defined using the init-parameters of the oprg.ultrawork.wtk.mc.ComponentController Servlet.

If neither label nor key are specified, the body of the tag will be evaluated and used as value.

Creating a Link

Link components are created using the mc:link tag.

The optional label attribute specifies the label of the link.

The optional key attribute specifies the key that must be used to lookup the link label in the application ResourceBundle. The application ResourceBundle is defined using the init-parameters of the oprg.ultrawork.wtk.mc.ComponentController Servlet.

The optional href attribute specifies the uri of an external resource.

The optional page attribute specifies the uri of a resource belonging to the web application. The uri must start with a slash (/) and must be relative to the web application context.

Creating a Block

Block components are created using the mc:block tag.

The required path attribute specifies the path of the JSP representing the block.

Displaying a Component

Components can be written to the response using the mc:write tag.

The mandatory name attribute specifies the component to be written.

The optional position attribute specifies the scope under which tje component must be looked up. Scope value can be page , request or application . If no scope is specified, the component will be looked up in the ComponentManager class.

Loading Components at Startup

MC ships with a Controller Servlet org.ultrawork.wtk.mc.ComponentControllerServlet that can be used to load component definitions at startup.

The Controller Servlet must be configured using the web.xml file located in the web application /WEB-INF directory.

The path to the JSP where the components are defined must be specified under the component-definition-url parameter of the Controller Servlet.

A basic configuration looks like this :


                    <servlet>
    <servlet-name>componentController</servlet-name>
    <display-name>ComponentControllerServlet</display-name>
    <servlet-class>org.ultrawork.wtk.mc.ComponentControllerServlet</servlet-class>
    <init-param>
        <param-name>component-definition-url</param-name>
        <param-value>/mc/component_definition.jsp</param-value>
    </init-param>
    <init-param>
        <param-name>development-mode</param-name>
        <param-value>true</param-value>
    </init-param>
</servlet>

Using the Controller Servlet

The Controller Servlet org.ultrawork.wtk.mc.ComponentControllerServlet can be used to display components managed by the org.ultrawork.wtk.mc.ComponentManager class.

The Controller Servlet must be configured using a prefix mapping such as :


                               <servlet-mapping>
               <servlet-name>componentController</servlet-name>
               <url-pattern>/page/*</url-pattern>
           </servlet-mapping>

It will then use the pathinfo as the name of the component to display. For example, with the previous mapping, if a page was defined under the id index , a request in the form of http://localhost:8080/page/index will display it.

Internationalization of Text Components

Text components defined using the key attribute will be written using a ResourceBundle, the user's locale taken from the HttpRequest or the user HttpSession , and the value corresponding to the key.

The location of the ResourceBundle to use can be specified in the Controller Servlet init-parameters . The resource bundle will be searched in the CLASSPATH. It follows the Java package syntax.


                                		<init-param>
            		    <param-name>resource-bundle</param-name>
            		    <param-value>ApplicationResources</param-value>
            		</init-param>

Using Containers

Two types of containers are available : Pages which represent a markup page, and Containers which represent an abstract set of components.

Since containers are also components, they share the same common attributes as regular components ( id, name, scope, position ).

All containers also share a common set of attributes :

The optional layout attribute specifies the path of the JSP responsible for managing the layout of the components that the container contains.

The optional master attribute specifies the id of another container that acts as its parent. A container inherits all atributes as well as the complete component graph from its master.

Creating a Container

Container components are created using the mc:container tag.

Creating a Page

Page components are created using the mc:page tag.

Adding Components to a Container

Depending on the layout they use, Containers can store components at specific positions, or they can just act as a set containing an unlimited number of components.

To add a component at a particular position, you use the position attribute :


                               <mc:page id="guest" layout="/layout/page/guest.jsp">
               <mc:block position="header" path="/block/header.jsp" />
               <mc:block position="menu" path="/block/menu.jsp" />
               <mc:block position="body" path="/block/guest.jsp" />
               <mc:block position="footer" path="/block/footer.jsp" />
           </mc:page>

To add multiple components to a container without wanting to assign them a particular position, you ommit the position attribute :


                               <mc:container layout="/layout/list.jsp">
               <mc:link page="/page/atk" label="Automation Toolkit" />
               <mc:link page="/page/wtk" label="WebToolkit" />
           </mc:page>

Displaying Components Using a Layout

A container will use a layout to display the components it holds.

A layout can be implemented using a JSP or a Servlet.

A JSP layout uses the mc:write tag in combination with the position attribute to display its components.

For example, the /layout/page/guest.jsp layout looks like this :


                               <html>
               <head><title>UltraWork</title></head>
               <body>
                   <mc:write position="header" />
                   <mc:write position="menu" />
                   <mc:write position="body" />
                   <mc:write position="footer" />
               </body>
           </html>

Nesting Containers

In order to build complex view, you will probably need to nest containers.

In this example a container is nested within a page (which is also container).


                               <mc:page id="guest" layout="/layout/page/guest.jsp">
               <mc:block position="header" path="/block/header.jsp" />
               <mc:container position="menu" layout="/layout/list.jsp">
                   <mc:link page="/page/atk" label="Automation Toolkit" />
                   <mc:link page="/page/wtk" label="WebToolkit" />
               </mc:container>
               <mc:block position="body" path="/block/guest.jsp" />
               <mc:block position="footer" path="/block/footer.jsp" />
           </mc:page>

Using Masters

Assigning a Master to a Container

You can avoid completetly redefining a container just to change a few of its attributes.

For example, if you defined a guest page using the following code :


                               <mc:page id="guest" layout="/layout/page/guest.jsp">
               <mc:block position="header" path="/block/header.jsp" />
               <mc:container position="menu" layout="/layout/list.jsp">
                   <mc:link page="/page/atk" label="Automation Toolkit" />
                   <mc:link page="/page/wtk" label="WebToolkit" />
               </mc:container>
               <mc:block position="body" path="/block/guest.jsp" />
               <mc:block position="footer" path="/block/footer.jsp" />
           </mc:page>

You can define a member page that will inherit the whole guest page component tree by writing this :


                               <mc:page id="member" master="guest" />

You can also override components beloging to the master to provide new ones :


                               <mc:page id="member" master="guest" >
               <mc:block position="body" path="/block/member.jsp" />
           </mc:page>

Adding Components to a Containment Tree

Using masters to maximize reutilization can get tricky when dealing with deeply nested structures such as the following one :


                               <mc:page id="guest" layout="/layout/page/guest.jsp">
               <mc:block position="header" path="/block/header.jsp" />
               <mc:container position="menu" layout="/layout/list.jsp">
                   <mc:link page="/page/atk" />
                   <mc:link page="/page/wtk" />
               </mc:container>
               <mc:container position="body" layout="/layout/threeColumns.jsp">
                  <mc:block position="left" path="/block/navigation.jsp" />
                  <mc:block position="center" path="/block/guest.jsp" />
                  <mc:block position="right" path="/block/news.jsp" />
               </mc:container>
               <mc:block position="footer" path="/block/footer.jsp" />
           </mc:page>

You sometimes need to redefine a component located deep into the container graph, for example the component located in the center position of the body of the page.

MC provides an easy way to do this through a dotted syntax :


                               <mc:page id="member" master="guest">
               <mc:block position="body.center" path="/block/member.jsp" />
           </mc:page>

Note: Because of the dotted syntax, you cannot use dots inside a position attribute value.