The XINS Front-end Framework is based on a calling convention. You will need to declare this calling convention in the impl.xml file to be able to use the framework:

<calling-convention name="xinsff" class="org.xins.server.frontend.FrontendCallingConvention" />

Templates are used for the presentation layer. The templates (also refered as XSLT) transform the XML returned by the function in HTML (or XHTML, WAP, iHTML).

The location of the templates is specified using the templates.<api name>.xinsff.source runtime property. The value must be a URL (file URL or http URL).

Examples:

The requests can accept special parameters.

XINS FF includes the possibility to cache the templates. Caching the templates will increase the response time as the XSLT file doesn't need to be parsed again and compiled (in case you use XSLTC). On the other side caching the templates will increase the memory usage of your web application.

I would advice to disable the cache during the development of the application and to enable it when deploying the application on production.

Enabling/disabling the cache is done by the templates.cache runtime property. The value can be true or false. If the value is not set, the cache is enabled by default.

If you execute the Control command, you have at the bottom of the page a few links to manage the cache. The flush link will clear the cache. The cache will be filled as the pages are used. The second link will clear the cache and reload all the templates in the cache.

XINS Front-end Framework includes some settings to help you having a secure web application.

You first need to specify the login page. This is done be defining the xinsff.login.page bootstrap property.

Once this property set, all pages except the login page and the Control command will redirect to this page if the user is not logged in. If you have other pages that you would like to be accessible to everybody, you will need to specify them as a comma separated list in the value of the xinsff.unrestricted.pages bootstrap property.

There can be some case where you want the user to have certain privileges to access a specific page, so you want to check for the access to this page inside the function. For this purpose, if you create an error code named NotLoggedIn and you return this error code from the function, the framework will redirect it to the login page.

To indicate that the a customer is logged in is done by putting the session ID as session property with the value Boolean.TRUE. The session ID is put as a cookie in your browser using the SessionId cookie name.

The workflow is the redirection between pages.

You can specify the default command by setting the xinsff.default.page bootstrap property. The browser will be redirected to this page when no command is specify in the request.

You can specify the redirection by returning a output parameter named redirect to your function. Note that the parameter will need to be declared in your function specification.

You can redirect a command to another page by setting the xinsff.redirect.<function name> bootstrap property. If the function exists, the function is executed and if the result of the function is successful, the browser is redirected to the value of the property. If the function does not exist, the browser is directly redirected to the value of the property.

It is also possible to specify conditional redirection. The conditions are defined using XPath using the generated XML source as XML to evaluate the XPath. The bootstrap property looks like xinsff.redirect.<function name>[xpath]. If none of the condition matches, the page is redirected to the xinsff.redirect.<function name> bootstrap property value. And if this property is not set the page is not redirected.

The function name is the concatenation of the command name with the action name. For example if the command is Login and the action is okay, the front-end framework will try to execute the LoginOkay function. The show action is the default action, so the Login command with the show action will try to execute the Login function.

The session is used to stored information about the user or about the state of the application for this user. The session needs to be declared as a shared object so that the session can be accessible from every function.

<instance name="_session" getter="getSessionManager" class="org.xins.server.frontend.SessionManager" />

Then you can use the session by calling _session.setProperty(propertyName, propertyValue) or _session.getProperty(propertyName). Session property names should be in lowercases. All session properties are put in the XML using <param name="session.propertyName">propertyValue</param>. Also all input parameters are stored automatically in the session. The session also contains a _inputs property which contains a Map with the input parameters and their values of the request.

If you put in the session an object which is of type org.xins.common.xml.Element or a java.util.List of Element objects, then this (or these) object(s) will be put in the data section of the generated XML.

Let's have a look of what the XML produce by the front-end calling convention is.

<commandresult command="SearchPet">
  <parameter name="session.petName">test</parameter>
  <parameter name="input.command">SearchPet</parameter>
  <parameter name="input.mode">source</parameter>
  <parameter name="input.action">Okay</parameter>
  <parameter name="input.petName">test</parameter>
</commandresult>

Here is an example of the of result when the request is invalid:

<commandresult command="Login">
  <parameter name="input.password"/>
  <parameter name="input.command">Login</parameter>
  <parameter name="input.mode">source</parameter>
  <parameter name="input.email">testtest.com</parameter>
  <parameter name="input.action">Okay</parameter>
  <parameter name="error.type">FieldError</parameter>
  <data>
    <errorlist>
      <fielderror type="mand" field="password"/>
      <fielderror type="format" field="email"/>
    </errorlist>
  </data>
</commandresult>

From it, the XML can be translated to anything (WAP, iHTML, text) using XSLT. We will more focus in this part in transforming the XML to XHTML and using cascading style sheets (css).

For an example, I suggest you have a look at the Pet store demo XSLT files located in the demo\xins-project\apis\petstore\xslt directory.