Fatwire (now Sites) API was defined around 1995 and was pretty cool... for the hostoric period when it was developed . At that time XML was pretty new and everyone was wondering which purposes it could have. The obvious idea was to use it as an extended programming language syntax.
Originally Fatwire API was based on a executable XML format, and every function is a tag. The whole idea was later moved in the JSP world with custom tag libraries. So what you have today is a set of JSP tags to do everything you need, including loops, conditions and variable management.
The problem is that the power of the tag based programming is very low compared to what you can do in Java, so you end up using a crippled Java managing a pretty primitive and verbose environment.
A great example of this problem is the code needed to retrieve an attribute. You have to do all of this:
<assetset:setasset
name="a"
type='<%=ics.GetVar("c") %>'
id='<%= ics.GetVar("cid") %>'/>
<assetset:getattributevalues
name="a"
attribute="Title"
listvarname="Title"
typename="PageAttribute" />
<ics:listget listname="Title"
fieldname="value"
output="title"/>
Now finally you get the attribute value in the single variable "title" (that you still need to access as ics.GetVar("title"))
What this code does? Simple: it retrieves a java object (what is today called a Pojo) that is a value object holding part of the current asset. Then the code extracts from the Pojo the requested attribute as an IList.
An IList is the internal datastructure used by Fatwire (that is actually a cached result set, and it is more similar to a table than a list). Finally, you can extract the field value from the first row of the IList.
The code is so long and verbose because it uses the tag syntax (definitely not a good programming language syntax) and also exposes details (the IList) that should be encapsulated in some object. Ideally, the Pojo that encapusale the asset should be also have the attributes internally, not to be retrieved separately.
Enter AgileSites, the open source Framework for Sites and Fatwire for Agile development. It offers a way simpler API to do the same operations: extracting an attribute.
Because AgileSites provides a way to code your template in Java (as explained in this post) , while keeping the full ability to invoke the Fatwire API, it was not too hard to implement wrapper cpde that makes this very frequent occurrence much easier.
In AgileSites you write:
Asset a = e.getAsset();
String title = a.getString("Title");
The "e" variable holds the current enviroment (actually it wraps the ICS object with additional features) . Since you can assume that the variable c and cid refers to the current asset, the whole
<assetset:setasset
name="a"
type='<%=ics.GetVar("c") %>'
id='<%= ics.GetVar("cid") %>'/>
becames just
Asset a = e.getAsset();
Now the a variable holds the current asset and provide a number of methods to extract various informations. Since extracting attributes is way the commonest occurrence, a method getString is provided. The equivalent of
<assetset:getattributevalues name="a" attribute="Title" listvarname="Title" typename="PageAttribute" /> <ics:listget listname="Title" fieldname="value" output="title"/>
is then just
a.getString("Title")
How it works? First, all the underlying ILists are created lazily when needed with an unique name to avoid clashes. Then since the lists used to extract attributes uses always a field value, it is not necessary to specify that parameter. As a result, all you need to do is to specify is the name of the attribute and in which data type you want to convert it.
Actually there is much more. The API allows to access multiple fields, create links and even define slots and so on. But I will talk of this in future posts. Stay tuned.