Clipping Programmer's Guide
The Clip Configuration File
A clip is deployed as a clip configuration file. This is an XML file with file extension .clip. The clip
configuration file contains all information needed to configure the clip.
The Clipping API consists of a number of interfaces that defines extension points to the clipping logic.
Developers may provide implementations of these interfaces and register them in the clip configuration file
by specifying the class name of the implementation. In some cases default implementations are provided,
and these can be chosen in the clip configuration file without specifying a class name.
Be aware that the order of the elements in the clip descriptor must follow the order defined in the DTD
mentioned in References. In the clip descriptor example listed in this guide, we have tried to add an element
before and/or after, to make it clear where the element fits in.
Note that deploying a robot from Design Studio will overwrite the clip configuration file, so in this
case modifications to the clip configuration file will have to be redone. To avoid doing this often, you
should choose to use a robot library at a URL. Furthermore, you could use a Property Provider to retrieve
configuration which might change often from another source than the clip configuration file.
The Clipping Logic
When a request is made for a clip e.g. in a portlet, the HTML of the clip will not be returned directly,
but instead a document with an IFRAME will be returned (see the figure below). This IFRAME will
make a new request targeting the clip configuration file; that is its source (src) URL is pointing at the
corresponding clip configuration file. The request for the clip configuration file is then handled by a servlet.
In other words all requests for clip configuration files are mapped to a servlet which means that there must
be a servlet mapping in the web application's web.xml file for this (this is automatically placed there
when you run a clipping wizard). The specific class name of the servlet may depend on where the clip
is deployed e.g. on a standard servlet engine, in a BEA WebLogic Portal, etc. The servlet contains code
(in the following called clipping logic) that will be deployed to a web server or portal and this code will
be responsible for contacting a RoboServer to run the clipping robot and for presenting the clip on the
web page. The clipping logic will send request to a RoboServer and will receive responses back from this.
Requests may take various forms, e.g. a request to restart a robot, a request telling the RoboServer that
the user has clicked on a link in the clip, etc. Request may also contain extra information to the robot e.g.
extra input object. The responses can also take many forms, e.g. content to present in the clip, an error
The figure below illustrates how this is done if the clip is deployed to a portal application, but clips deployed
to a web server will work in the same way.