sourceforge > tacos
 
 

Setup/Installation

Installing tacos and getting setup to use it in your project is a fairly straightforward task. This document attempts to outline some of the first initial steps you may need to go through to get going.

Tapestry Library Inclusion

One of the first things you will need to do to include tacos with tapestry is to include it's library specification file in your applicationName.application configuration file. This should look something like: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC
  "-//Apache Software Foundation//Tapestry Specification 4.0//EN"
  "http://jakarta.apache.org/tapestry/dtd/Tapestry_4_0.dtd">
<application name="TacosDemo" engine-class="org.apache.tapestry.engine.BaseEngine">
    
  <description>Tacos Demo Application</description>
    
  <library id="tacos" specification-path="/net/sf/tacos/Tacos.library"/>
    
  <library id="contrib" specification-path="/org/apache/tapestry/contrib/Contrib.library"/>
  
  <page name="Home" specification-path="Home.page"/>
  
</application>

JavaScript requirements

Tacos comes bundled with most of the javascript packages it needs to run, except for the core package, dojo. Much more information can be found on obtaining and bundling dojo with your application at their website. http://dojotoolkit.org. The package provided by tacos contains only a small subset of what dojo provides, if you want to use more you will have to learn how to build your own. Dojo does make it easy to do though, this is a sample ant command that will build the "kitchen sink" version of dojo, which includes everything. 

ant -Ddocless=true -Dprofile=kitchen_sink release

The default dojo package that tacos builds is based on a custom tacos build profile script, which may be much more than you need for your application. You can find the main js directory for this in the tacos distribution under the js/ directory. Here is what the current tacos profile script looks like.

Tacos dojo package

        
// pull in the dependency list and define it in the var "dependencies". This
// over-rides the default built into getDependencyList.js. The bootstrap and
// hostenv files are included by default and don't need to be included here,
// but you can change the hostenv file that's included by setting the value of
// the variable "hostenvType" (defaults to "browser").
var dependencies = [ 
	"dojo.io.IO",
	"dojo.io.BrowserIO",
	"dojo.event.*", // NOTE: this includes topic support
	"dojo.lang.*",
	"dojo.widget.Manager",
	"dojo.widget.FloatingPane",
	"dojo.fx.html"
];

// NOTE: this MUST be included or a list of files must be output via print()
// manually.
load("getDependencyList.js");

Dojo installation

Dojo isn't hard to install, it's almost as easy as installing any other javascript package, simply dump it into your web folder under a directory that makes sense (most people use js/ or javascript/ ), and configure one tiny little thing in your javascript includes and you're done.

Warning
The djConfig script configuration point is the most important part to get right, without dojo won't know how to resolve some of the widgets tacos uses. It's also very important that the djConfig script definition be included before dojo.js is. It is also crucial to avoid assigning handling of the *.html files to the tapestry servlet, because dojo needs to load some plain html files for their widget templates.

Most typical tapestry applications have a Border component that configures the shell. Things like css/javascript includes typically go here. This example assumes that you have a similar area, if not the application of these script includes still applies, however you define your html head sections.

HTML sample template

            
         <html jwcid="shell" >
         <script type="text/javascript"> 
            djConfig = { isDebug: false, 
                         baseRelativePath: "js/dojo/", 
                         preventBackButtonFix: false };
         </script>
         <script type="text/javascript" src="js/dojo/dojo.js"></script>
        
        <body jwcid="@Body" >
            Content goes here...
        </body>
        </html>

Dojo Configuration

As you can see, the configuration is pretty simple. Here is a quick explanation of what each variable does.

  • isDebug: Sets debug output on or off. Turning this on will display all of the dojo debug log statements, as well as the tacos debug statements. This is very useful when debugging particular ajax requests, as it will display the ajax response data recieved from the server on ajax requests.
  • baseRelativePath: Sets the path to your dojo installation, relative to the root context of your web application. This allows dojo to find the rest of the files it needs to create certain widgets on the fly. In this example dojo lives under the js directory of a web application. Ie:
    • webroot/
    • webroot/js/dojo/dojo.js
    • webroot/WEB-INF/
    • webroot/css/
    • webroot/images/
  • preventBackButtonFix: Setting this to false is currently important, for some unknown reasons to myself leaving it to it's default, true, will disable the forward/back browser button functionality available in AjaxForm. (I think it has something to do with iframes).
    Note
    This setting forces however IE browsers to post ajax forms through the iframe. The side-effect of this is that you'll hear clicking sounds when the form is posted.

Library Includes

Other than the initial border page/javascript installation tacos should be no different than any other java library you install. Drop the tacos jar into your WEB-INF/lib directory along with all the other depedencies and you should be all set.