LAMS Custom Tags

Table of Content

1.1 Tabbed Pages and FCK Editor Optimisations

2 Using the LAMS Tags
3 Tags

3.1 html
3.2 head
3.3 User
3.4 LAMS and Tool URL
3.5 CSS
3.6 HeadItems
3.7 Date
3.8 STRUTS-textarea
3.9 textarea
3.10 DefineLater Tag
3.11 Help Tag

3.11.1 1. Contextualised Tool Help
3.11.2 2. Page-specific Help
3.11.3 3. Style Attribute

3.12 Role
3.13 Image Button Wrapper Tag
3.14 Configuration
3.15 Out

4 Developing A New Tag

LAMS has a custom tag libary, LAMS, and tools may have their own tags.

Tabbed Pages and FCK Editor Optimisations

See: Tab Controller + FCK Editor Custom Tags

Using the LAMS Tags

The code for the tags is in lams_central.jar.

In your project, add the following lines to the taglibs.xml file in the xdoclet merge directory:

<taglib>    <taglib-uri>tags-lams</taglib-uri>    <taglib-location>/WEB-INF/lams.tld</taglib-location> </taglib>

Then copy the lams.tld from lams_central/web/WEB-INF to <your project>/web/WEB-INF.

In your jsp files, include the tag library:

<%@ taglib uri="tags-lams" prefix="lams" %>

Tags

html

The lams:html tag should be used for all jsp pages as it sets the page direction and lang attributes on <HTML> tag.

The locale filter sets a variable in the session for the desired page direction (left to right, right to left) based on the user's locale.

It also supports the xhtml parameter sued by Struts, so if you would normally use <html:html xhtml="true">, you can use <lams:html xhtml="true"> and your web pages will have "xmlns="http://www.w3.org/1999/xhtml" as per the Struts tag and any Struts tags in the pages should behave correctly as our tag sets the Struts Globals.XHTML_KEY in the page scope.

For example, if the user's locale is en_AU then <lams:html> will become <html lang="en-AU" dir="LTR"> in the html sent to the browser. If the user's locale was ar_JO then it will be converted to <html lang="ar-JO" dir="RTL">.

head

The lams:head tag should be used for all jsp pages as it sets the UTF-8 encoding and pragma statements that stop the pages being cached in a browser. The caching can be an issue when LAMS is upgraded.

User

The User tag allows you to access the simple user details from the UserDTO object, which is stored in the shared session. It does not support the theme details properly yet - we will add them when we work out what is required.

The tag has a single paramter "property", which is the name of the property from the UserDTO to be accessed. This may be: userID, firstName, lastName, login, email or theme. Note that userID will return an Integer and theme will return a CSSThemeVisualElement. All the others will return a String.

The implementation is done using reflection so you can access any public property in the UserDTO bean. So if new properties are added, they should automatically work with the tag.

LAMS and Tool URL

Two tags are to help with printing out paths in your jsps. If you need to put in the basic LAMS url (the one defined in the configuration file e.g. http://localhost:8080/lams/) then use <lams:LAMSURL/>. If you want to put in the basic URL for your webapp (e.g. http://localhost:8080/lams/tool/lanb11/ ) then user <lams:WebAppURL/>.

All of the urls end with a "/".

If you are going to use the tags repeatedly in one page, you might think about "caching" the value, rather than having it recalculated each time.

CSS

The stylesheet needed will eventually be based on the user and user's organisation. Tools should use <lams:css/>, which will write out the user's preferred stylesheet. At present, it just refers to default.css, but this will be changed in the future to be the user's stylesheet and the default stylesheet (which is the same as aqua.css). See also LAMS Themes or Skins

Example:

<%@ page language="java" pageEncoding="UTF-8" contentType="text/html;charset=utf-8" %> .... <c:set var="lams"><lams:LAMSURL/></c:set> <c:set var="tool"><lams:WebAppURL/></c:set>  <\!DOCTYPE HTML PUBLIC "-//W3C//DTD hTML 4.01 Transitional//EN"> <lams:html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <lams:css/>

Export portfolio pages are designed to be run offline, so for these use <lams:css localLinkPath="../"/>. The "../" indicates the path back to the "root" of the export portfolio zip file. The css files are put in the export zip file by the export portfolio core code, and the localLink option will cause the css statement to refer to the local copy.

HeadItems

Many of our authoring and monitoring pages include the same common javascript and css files. So there is a tag "headItems" that bundles up most of them. This tag has no parameters.

So:

<%@ page language="java" pageEncoding="UTF-8" contentType="text/html;charset=utf-8" %> .... <\!DOCTYPE HTML PUBLIC "-//W3C//DTD hTML 4.01 Transitional//EN"> <lams:html> <head> <headItems/>

will

Set the content type (<meta http-equiv="content-type" content="text/html; charset=UTF-8">)
Call the CSS tag (<lams:css />)
Link to the FCKEditor stylesheet (<link href="${lams}css/fckeditor_style.css" rel="stylesheet" type="text/css">)
Include common.js, fckeditor.js, fckcontroller.js, tabcontroller.js from lams-central
Include xmlrequest.js from the tool's includes/javascript folder.

Have a look at the noticeboard tool's file web/authoring/authoring.jsp to see it in use.

Date

The Date tag produces a full date/time including timezone, using the JSTL <fmt:formatDate> to localise the date format. The tag takes up to three parameters

value: Mandatory value, must be of type java.util.Date. This is the date to be shown.
style: Optional. Set to "short" if the normal date format produces a String that is too long for the screen layout
type: Optional. Defaults to "both". Same as the fmt:FormatDate type value.

Please the style and type parameters only in rare cases. Normally you should only supply the value parameter - this will allow us to keep our dates consistent across the system. The other parameters have only been included for rare cases when the normal format is just not suitable.

Typical example:

<lams:Date value="${GateForm.map.startingTime}"/>

Sample outputs:
en_AU: 1 February 2006 03:04:05 PM EST
cy_GB: Wed Feb 01 15:04:05 EST 2006
en_US: February 1, 2006 3:04:05 PM EST
zh_CN: 2006?2?1? ??03?04?05? EST

STRUTS-textarea

The basic idea is replace \r\n (or \n in *nix) to <BR> tag, so it can display break line normally.

It is 100% compatible with STRUT HTML textarea tag. The content saved into database thru this tag is compatible with FCKedit as well, which replace those specific characters for HTML interceptor, such as &, < or >. Unfortunately, this tag must bind some Javascript stuff, I put these script into common.js. Furthermore, it must embed between STRUTS <html:form> tag, which means it does not work in pure HTML textarea way.

Simple instruction:

Include
$<lams_web_root>/includes/javascript/common.js

in your JSP page
Include
<%@ taglib uri="tags-lams" prefix="lams" %>
Change STRUTS HTML tag
<html:textarea ?>

to

<lams:STRUTS-textarea ?>
To display content, don?t forget add ?escapeXml=false". It is same handling with FCKEditor field.

textarea

This tag provides same function with STRUTS-textarea tag but it is used inside normal HTML form. You can use any attributes which will be rendered exactly same. So, you can treat it as normal HMTL textarea tag. But two things need be careful:

name attribute is mandatory.
It also need common.js.

DefineLater Tag

All tools need to have a define later screen, which is displayed to the learner when the "define later" flag was turned on in authoring.
To make our pages more consistent, there is a tag that will display the message and a "Try Again" button.

The tag just lays out the fields - you need to define the message and the button name in your language file.

Use of this tag is not compulsory - if your screen needs additional information that won't work well with the tag then don't us the tag. However if your page is the normal looking define later page, please use the tag for consistency.

The tag takes two parameters defineLaterMessageKey, which is the key to the message in your language file, and buttonTryAgainKey, which is the key to the name of the button in your language file. They default to "define.later.message" and "button.try.again" respectively so if you use these keys in your language file then you don't need to include any parameters.

(in language file) define.later.message=Please wait for the teacher to complete the contents of this activity. button.try.again=Try again  (in jsp) <div id="page-learner">     <h1 class="no-tabs-below">         ${activity.title}     </h1>     <div id="header-no-tabs-learner">     </div>     <\!--closes header-->      <div id="content-learner">         <lams:DefineLater/>     </div>      <div id="footer-learner">     </div>     <\!--closes footer-->  </div>

(in language file) define.later.error=Please wait for the teacher to complete the contents of this activity. try.again.button=Try again  (in jsp) <div id="page-learner">     <h1 class="no-tabs-below">         ${activity.title}     </h1>     <div id="header-no-tabs-learner">     </div>     <\!--closes header-->      <div id="content-learner">         <lams:DefineLater defineLaterMessageKey="define.later.error" buttonTryAgainKey="try.again.button" />     </div>      <div id="footer-learner">     </div>     <\!--closes footer-->  </div>

Help Tag

The Help tag allows you to add a link to a relevant and/or contextualised external help page. The purpose of this help page is to provide assistance the user through details help documentation (e.g. for using a tool).

The Help Tag can be used two method:

1. Contextualised Tool Help

The link is constructed from two parameters the tool signature (string) and module name (string) i.e. authoring. The tag will display a uniform, help button icon that is aligned to the right.

It is recommended that you use this tag only if you have a default help URL set for your tool. If your default help URL is not set or has a null value then the tag will display nothing. Also note, that it is important that the tool signature value is correct and matches your tool's signature. If the tool signature is incorrect an error will be produced and a cross icon (see below) will be displayed on the page:

For further details on the tool's help URL see Tool ContractTypical example:

<lams:help toolSignature="lanb11" module="authoring"/>

It is possible to used a static variable from an imported class. Example:

<lams:help toolSignature="${NoticeboardConstants.TOOL_SIGNATURE}" module="authoring"/>

The help URL is constructed in the following format:

<default-help-URL><module>#<toolSignature><module>-<locale>

Typical Output (from above example):

<img src="http://localhost:8080/lams/images/help.png"  onclick="window.open('http://wiki.lamsfoundation.org/display/lamsdocs/lanb11authoring#lanb11authoring-enAU', 'help')"/>

2. Page-specific Help

The link is constructed from a single parameter, the page address (string) i.e. My+Page. The tag will display a uniform, help button icon that is aligned to the right.

For further details on the system help URL see LAMS Configuration Settings

Typical example:

<lams:help page="My+Page"/>

The help URL is constructed in the following format:

<systemdefault-help-URL><page>

Typical Output (from above example):

<img src="http://localhost:8080/lams/images/help.png"  onclick="window.open('http://wiki.lamsfoundation.org/display/lamsdocs/My+Page', 'help')"/>

The icon used is from the common image directory. The icon looks like this:

3. Style Attribute

The default CSS for the help icon makes its placement awkward if not used in the tab environment of author and monitor. If you want to use this tag elsewhere, try the style attribute:

<lams:help style="no-tabs" page="My+Page"/>

Role

Role names for admins and managers are stored in the database as 'COURSE ADMIN' and 'COURSE MANAGER'. To display the internationalised version of a role name, do (for example):

<fmt:message>role.<lams:role role="${role.name}" /></fmt>

This example has the message key in the format 'role.GROUP.ADMIN' (for example). The tag simply translates 'COURSE' to 'GROUP' and replaces the whitespace.

Image Button Wrapper Tag

The Image Button Wrapper tag is used to consistently display two (or more) adjacent image buttons (buttons with css background-image applied) in both left-to-right (e.g. english) and as well in right-to-left (e.g. arabic) directional rendering of the webpage.

Typical use:

<lams:ImgButtonWrapper>     <a href="http://wiki.lamsfoundation.org/pages/editpage.action#"  onclick="submitMyItem()" class="button-add-item"> 	<fmt:message key="label.add" />     </a>     <a href="javascript:;"  onclick="cancelMyItem()" class="button space-left"> 	<fmt:message key="label.cancel" />     </a> </lams:ImgButtonWrapper>

The above code produces the following output:

<div id="button-table" class="space-bottom-top">     <div id="button-row"> 	<a href="http://wiki.lamsfoundation.org/pages/editpage.action#"  onclick="submitMyItem()" class="button-add-item"> Add </a> 	<a href="javascript:;"  onclick="cancelMyItem()" class="button space-left"> Cancel </a>     </div> </div>

Configuration

The configuration tag is used to get a value from the Configuration table. For example, to get the current version, use <lams:Configuration key="Version"/>.

This is an alternative to using

<% String version = Configuration.get(ConfigurationKeys.VERSION);%> .... <c:set var="authorurl_params">?loadFile=lams_authoring.swf&....&version=<%=version%>&....</c:set>

The advantage to using the tag is that you avoid scripting, and if a value is needed inside a scriptless tag then scripting is out. The disadvantags is that you have to use the hardcoded version of the configuration parameter (e.g. version) rather than the constant defined in the ConfigurationKeys class.

Out

The out tag is used to replace new line characters \n in a string with the <br> html element.

value: Manadatory. The text to output
escapeHtml: Optional. Escapes the String characters in a String using HTML entities.

Developing A New Tag

If the new tag may be used in more than one module, it should go in the main tag library in lams_central.

If it is a complex tag, then write a taglib class in the package org.lamsfoundation.lams.web.tag package, in lams_central. Use XDoclet to define your tag details, and then the lams.tld file will be generated when webdoclet is run.

If it is a simpler tag then use a .tag file. Tag files (.tag) should be placed in the /WEB-INF/tags/ folder of the relevant project module.

If the tag is for a particular tool, then it can be left in the tool's project. However it should be done in the same way - a .tag if it is simple or a taglib class using XDoclet if complex.