Pre-configured web content tools

This page will provide instructions on how to setup web content tools that are pre-configured. ie you add the tool from the Site Info > Edit Tools like you do a normal tool, and it is already setup with the URL.

1. Go to SAKAI-SRC/web/web-tool/tool/src/webapp/tools/

Have a look at sakai.iframe.xml. This is the file we will be using as the skeleton. We will give it a unique tool name and description, and then give it the URL to load in. Copy it to something like my.custom.xml

2. Edit SAKAI-SRC/web/web-tool/tool/src/webapp/tools/my.custom.xml

Fill out the id, title and description attributes:

<?xml version="1.0"?>

<registration>
	<tool id="my.custom"
		title="My custom web tool"
		description="A web tool that I have customised">

		<!-- what properties? -->
                <configuration name="source" value="" />
		<configuration name="height" value="600px" />
		<configuration name="reset.button" value="false" type="final" />

		<!-- what site categories? -->
		<category name="course" />
		<category name="project" />
      	        <category name="portfolio" />
		<category name="myworkspace" />

		<!-- Allow this to be set -->
		<configuration name="functions.require" /> 
	</tool>
</registration>

Now, in order to give it a customised URL, we need to edit its properties. Find this block:

<!-- what properties? -->
<configuration name="height" value="600px" />
<configuration name="source" value="" />
<configuration name="reset.button" value="false" type="final" />

and replace it with this block:

<!-- what properties? -->
<configuration name="height" value="600px" />
<configuration name="sakai.properties.url.key" value="my.custom.url" />
<configuration name="reset.button" value="false" type="final" />

Note the replacement of source with sakai.properties.url.key and its value my.custom.url

Save this file.

2. Edit SAKAI-SRC/web/web-tool/tool/src/webapp/WEB-INF/web.xml

We need to add two blocks for each customised tool you add, to this web.xml file.

First the filter-mapping (put it amongst the other filter-mapping blocks):

<filter-mapping>
        <filter-name>sakai.request</filter-name>
        <servlet-name>my.custom</servlet-name>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher>
        <dispatcher>INCLUDE</dispatcher>
    </filter-mapping>

and then the servlet (again, put it amongst the other servlet blocks):

<servlet>   
        <servlet-name>
           my.custom    
        </servlet-name>
        <servlet-class>
            org.sakaiproject.web.tool.IFrameAction
        </servlet-class>
        <init-param>
            <param-name>template</param-name>
            <param-value>web/chef_iframe</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
     </servlet>

Note that whatever you put for the tool id in the tool.xml file, MUST match the filter-name and servlet-name blocks. In this example, the unique tool id is my.custom.

Save this file.

4. Rebuild the web tool

From SAKAI-SRC/web/, run maven sakai for Maven 1 or mvn clean install sakai:deploy for Maven 2 to rebuild and redeploy the web tool

5. Add the URL you want to use for this tool to sakai.properties

To tie it altogether, you need to add the URL that you want to use for this tool to sakai.properties.
This needs to match what you put in the tool configuration parameter for the sakai.properties.url.key value. In this example, the unique tool url key is my.custom.url.

Add this to sakai.properties:

my.custom.url=http://some.url.here/

Save, restart Sakai and if all is well you will be able to access this new tool in Site Info > Edit Tools, add the tool to your site and when you click on it, it will render the contents of the URL you gave in sakai.properties for my.custom.url in the main iframe.

6. Dynamic configuration

There are a set of placeholder parameters you can add to your URL to make it customised to a site or even a user. When these are added to a URL, they are expanded to their proper value.

In sakai.properties, add the following set of parameters:

iframe.allowed.macros=${USER_ID},${USER_FIRST_NAME},${USER_LAST_NAME},${SITE_ID},${USER_ROLE},${SESSION_ID}

You don't need to add them all if you don't want to, just the ones you want.

Now you can make your URL something like this:

my.custom.url=http://some.url.here/helloworld.jsp?fname=${USER_FIRST_NAME}&lname={USER_LAST_NAME}

and for each user that clicks on the new tool, their first name and last name will be sent along as parameters to the URL you entered.

6. Dynamic configuration - make your own

You can expand the default set of parameters above by making your own site specific property. Using the Sites editor, click 'Properties' and enter some key-value pairs.

e.g.
If you have a property for every site called
course-department

then you would add this property to the Site (see screenshots below) and then in sakai.properties make it available:

iframe.allowed.macros=${USER_ID},${USER_FIRST_NAME},${USER_LAST_NAME},${SITE_ID},${USER_ROLE},${SESSION_ID},${SITE_PROP:course-unique-id},${SITE_PROP:course-section-key}

And use these as you do the default set of parameters.

See the screenshots below for an example:

Adding properties in the Sites editor

Acknowledgements

Thanks to Seth Theriault for helping me out with this in the first place