Integrating a Tapestry Component Library into the Palette

If you have your own library of Tapestry components you can make it available via the palette for Tapestry application developers with a small amount of effort.

The following paragraphs use the component library supplier descriptor at:

http://www.mjhenderson.com/tapestry/components/supplier-mjhenderson.com.xml

to illustrate the supplier descriptor file structure.

Define your component libary supplier descriptor file

The supplier declaration must conform to the supplier DTD: 

<?xml version="1.0" standalone="no" ?>

<!DOCTYPE supplier PUBLIC "-//Michael J Henderson//Tapestry Palette Supplier 0.1.6//EN"
			"http://tapestrypalette.mjhenderson.com/dtd/supplier-0.1.6.dtd">

Declare your supplier information

The outermost tag of the supplier descriptor declares your company name. The palette uses this information to create the folder containing your libraries. You can define the label for the folder, a URL to your home page which will be used to create a link from the palette inspector to your web-site. You should add a description inside the supplier tag for the palette inspector, but it is not mandatory. 

<supplier id="mjhenderson"
             label="www.mjhenderson.com"
             homePage="http://www.mjhenderson.com/tapestry/components/">
     <description>Assorted Tapestry component libraries</description>
</supplier>

Declaring a library

After the description you are free to define as many component libraries as you wish. The library declaration provides the palette with the information it needs to download the library and add it to the application specification. 

<library id="dynamic"
	 label="Dynamic Block"
	 preferredNamespace="dynamic"
	 specificationPath="/com/mjhenderson/tapestry/components/dynamic/Dynamic.library"
	 downloadURL="http://www.mjhenderson.com/tapestry/components/dynamic/dynamic.jar"
	 version="0.1">

    <description>
    Dynamic Block is designed for situations when you want to be able to place different
    components onto a page according to some decision made at runtime.
    	
    The same effect can be achieved with the Tapestry Conditional or Block components but
    these both require the selection of components to be a design-time decision. DynamicBlock
    allows you to defer the decision until runtime.
    </description>

    <documentationURL>
       http://www.mjhenderson.com/tapestry/components/
    </documentationURL>

</library>

The library tag requires the following attributes:

Nested inside the library declaration you may include a description of the library to be displayed in the palette inspector when the library is selected in the Repositories section, before it is downloaded and added to the project.

After the description you may also add an optional documentationURL to provide a link to the home page of the library component reference documentation so that a potential user of your library may browse the documentation prior to downloading the library.

Adding license terms

You may nest a license declaration inside the library declaration. If the license is included the user will be prompted to agree to the license terms when they drag the library onto the application specification to add it to the project. 

<license>
Copyright 2005 Michael Henderson
	
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
or implied.

See the License for the specific language governing permissions
and limitations under the License.
</license>

Adding libraries required by your library

If your library depends on other libraries which are not included with the Tapestry distribution you can declare them after the description and documentationURL (and the license if it is included). Each library should be declared as a dependency, containing the URL to a version of the library. These dependencies will be downloaded and added to the project build path along with the component library. 

<dependency>
    http://www.ibiblio.org/maven/groovy/jars/groovy-1.0-beta-10.jar
</dependency>

Using the supplier descriptor

With this supplier descriptor file completed and published on the web, any user can add the library to the palette by adding the URL of the supplier descriptor to the list in the Tapestry Palette > Remote Libraries preferences page in Eclipse. All you have to do is publicize the fact that you have a descriptor and it's location.

Perhaps soon there will be a central registry of supplier descriptors so that the palette can include them automatically.