|
This is a simple example using only Xkins. This means that this examples do not use Velocity, Struts or Xkins Forms. This example
is just for show you how Xkins resources, paths and extensibility between Skins work. Xkin Components are show in Xkins Forms example
web.xml declaration
First, you must declare Xkins servlet in order to load Xkins. Xkins are loaded to ServletContext, so they are accesed from XkinProcessor facade.
<servlet>
<servlet-name>xkins</servlet-name>
<servlet-class>net.sf.opentranquera.xkins.core.XkinsServlet</servlet-class>
<init-param>
<param-name>config</param-name>
<param-value>/xkins-forms-definition.xml</param-value>
</init-param>
<init-param>
<param-name>debug</param-name>
<param-value>8</param-value>
</init-param>
<init-param>
<param-name>detail</param-name>
<param-value>8</param-value>
</init-param>
<init-param>
<param-name>defaultSkinName</param-name>
<param-value>invierno</param-value>
</init-param>
<init-param>
<param-name>autoReload</param-name>
<param-value>3000</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
Here we declare a default skin (invierno), configures configuration file and tell Xkins to monitor our definition changes in order to reload them automatically when they change.
You can also define a listener and context properties in order to start Xkins engine:
<context-param>
<param-name>xkins.config</param-name>
<param-value>/WEB-INF/xkins-faces-definition.xml</param-value>
</context-param>
<context-param>
<param-name>xkins.autoReload</param-name>
<param-value>1000</param-value>
</context-param>
<context-param>
<param-name>xkins.loader</param-name>
<param-value>
net.sf.opentranquera.xkins.core.loaders.XkinsXMLLoader
</param-value>
</context-param>
<listener>
<listener-class>
net.sf.opentranquera.xkins.core.loaders.XkinsLoaderServletContextListener
</listener-class>
</listener>
Xkins-definition file:
This is a piece of a xkin-definition file we will use in our examples, where we are declaring 2 skins: skin1 and skin2:
Click here to see the file.
In this example, Skin2 extends Skin1.
Skin1 declares 3 templates: frame, field and button.
Skin2 overwrites resources "back", "tipoLetra" and "colorLetra", frame's resources, field template content and buttons resources.
JSP file:
These skins can be used in JSP in the following way:
<%@page contentType="text/html"%>
<%@ taglib uri="/WEB-INF/tld/xkins.tld" prefix="xkin" %>
<%@ page import="net.sf.opentranquera.xkins.*" %>
<%
//skin change on reload
String skin=XkinProcessor.getCurrentSkinName(request);
if(skin.equals("skin1")) {
skin="skin2";
} else {
skin="skin1";
}
XkinProcessor.setCurrentSkinName(request, skin);
%>
<html>
<head><title>Skin: <xkin:xkinName/></title></head>
<body>
<center>
<form>
<xkin:template name="frame">
<xkin:templateParameter name="width">40%</xkin:templateParameter>
<xkin:templateParameter name="title">Xkins Demo</xkin:templateParameter>
<xkin:templateParameter name="buttons">
<xkin:template name="button">
OK
<xkin:templateParameter name="action">
javascript:alert('OK');
</xkin:templateParameter>
</xkin:template>
<xkin:template name="button">
Change Skin
<xkin:templateParameter name="action">
javascript:top.location.reload();
</xkin:templateParameter>
</xkin:template>
</xkin:templateParameter>
<xkin:template name="field">
<xkin:templateParameter name="label">
First name
</xkin:templateParameter>
<xkin:templateParameter name="data">
<input type="text" name="nombre">
</xkin:templateParameter>
</xkin:template>
<xkin:template name="field">
<xkin:templateParameter name="label">
Last name
</xkin:templateParameter>
<xkin:templateParameter name="data">
<input type="text" name="apellido">
</xkin:templateParameter>
</xkin:template>
<xkin:template name="field">
<xkin:templateParameter name="label">
Phone
</xkin:templateParameter>
<xkin:templateParameter name="data">
<input type="text" name="telefono">
</xkin:templateParameter>
</xkin:template>
<xkin:template name="field">
<xkin:templateParameter name="label">
e-mail
</xkin:templateParameter>
<xkin:templateParameter name="data">
<input type="text" name="email">
</xkin:templateParameter>
</xkin:template>
</xkin:template>
</form>
</center>
<jsp:include page="../footer.jsp"/>
</body>
</html>
By using template tag, it commands the Processor to use each template. TemplateParameter tag is used to pass a parameter for the template. The bodyContent built-in parameter is passed through template tag body content.
In runtime, if skin name is set to "skin1", generated HTML by this JSP page would be:
In runtime, session attribute defined in Skin.ATTR_SKIN_NAME is used to determine skin name. Login will be responsible to set this attribute properly according to user?s preferences. If no vaule is set, default skin name is assumed. Default skin name can be declared as an init parameter in web.xml XkinServlet declaration.
If skin name is "skin2", the generated HTML would be:
Using Xkins in this way is posible but a little confussing, so it's better to write your own tags to clarify
Xkins usage, or you can use Xkins Forms Tags or JSF integration.
Xkins taglibs
Xkins has some utility taglibs. We have seen an example of such taglibs in example using:
- TemplateTag
- TemplateParameterTags.
But there are some more tags that you can use to access Xkin's resources, paths, and other useful things:
PathTag:
This tag is used to access paths from Skins definitions.
Example:
<xkin:path name="backgrounds"/>
Will produce this output (assuming skin1 set in session) :
/xkins/skins/skin1/backgrounds
ResourceTag
You can access Skin resources with this tag.
Example:
<xkin:resource name="back"/>
<xkin:resource name="tipoLetra"/>
Output produced by this tag (assuming skin1 set in session):
/xkins/skins/skin1/backgrounds/bg.gif
Arial
Skin name management:
XkinTag
Allows you to set current Skin name in Session.
SaveActualXkinTag
This tag saves current skin name value set in session. This is used along with RestoreActualXkinTag and is useful if you need to change Skin during a JSP.
RestoreActualXkinTag
This restores value saved by SaveActualXkinTag
XkinNameTag
This writes to output the name of the current skin.
Example
Use Skin X set in session
<xkin:saveAcualXkin/>
<xkin:xkin name="skin2"/>
<xkin:xkinName/>
Use Skin2 templates, resources, etc.
<xkin:RestoreAcualXkin/>
Again, use Skin X set in session
Using Xkins in a no-web environment
You don't need a web environment in order to use Xkins. You can use Xkins in a context where no httpession exists.
For instance, if you are in a java class where you need to send an e-mail and you want e-mail text to use a template defined by Xkins, you can code as follows:
Xkins xks = (new XkinsLoader()).loadSkins("/config/xkins/mail-templates.xml");
Skin skin = xks.getSkin(XkinProcessor.DEFAULT_SKIN);
XkinProcessor xkpBody = new XkinProcessor();
Template tmpBody = skin.getTemplate("mail");
xkpBody.setTemplate(tmpBody);
xkpBody.addParameter("text", "This is a text");
this.sendMessage(xkpBody.processContent());
Your mail-templates definition will have a Skin with a mail template that receives a "text" parameter:
<?xml version="1.0" encoding="UTF-8"?>
<xkins>
<!-- SKIN default -->
<skin name="default" url="/skins/default">
<processor type="net.sf.opentranquera.xkins.processor.VelocityTemplateProcessor"/>
<template name="mail">
<content><![CDATA[
<table>
<tr bgcolor="cyan">
<td>$text</td>
</tr>
</table>
]]></content>
</template>
</skin>
</xkins>
Your mail will has the following body:
<table>
<tr bgcolor="cyan">
<td>This is a text</td>
</tr>
</table>
|
