Database Manager for JumpStart

If you use Oracle or SQLServer, you can always access the database with a SQL Interface: just use the client provided with your database.

A database client is useful for many tasks: I usually manage the cache, look for the fields I have to use in code, do mass changes to assets accessing directly to the database.

But if you use a recent Jump Start for development, you do not have such a luxury... apparently.

Actually, Jump Start Kit ships with HSQLDB as a database. It is a java only database running embedded in tomcat. In fact, it HAS an SQL client, already included in his jar. But there was no way to activate it... until now. Here is the trick.

The simplest way I found is just to add the file dbman.jsp file under the App_Server/apache-tomcat-6.0.18/webapps/cs. The code of this script is simply:

<%
String s = "jdbc:hsqldb:file:"+getServletContext().getRealPath("/")
+"../../default/data/hypersonic/csDB";
org.hsqldb.util.DatabaseManagerSwing.main(new String[]{ "--url",s });
%>

This code tries to be independent of the actual installation folder of the database, but I have tested so far only in my installation.

Now you can call http://localhost:8080/cs/dbman.jsp and you will have access to the following window:

Please note this works only with the JumpStartKit running in your local machine because it opens a new GUI window, not a web interface.

Released FatStart: Eclipse based FatWire development kit

Sometimes you are a victim of your own success. In the last few weeks I had so much to do that I had not the time to post anything. But since I started a couple of new FatWire projects, this gave me the opportunity to release another open project I was thinking of: FatStart.

What is FatStart?

Basically, FatStart is a template for FatWire Content Server site development that solves a few very well known problems in FatWire development:

• It allows you to use eclipse (without plugins!) as a development enviroment  (instead of the awkward ContentServerExplorer!)
• It let you store the source code AND the structural assets under a version control system like subversion or git.
• It allows many developer to collaborate having each one his private FatWire Jump Start instance
• It allows to deployment  a website on a production FatWire server without resorting to publishing

The trick is that you store structural assets in json format, write your jsp in eclipse then publish them easily at any time using a javascript installer, both in your local development Jump Start or in the production server.

I know that there are already 2 Eclipse plugins for Fatwire development, but they are far from satisfactory. My solution tried to grab ideas from them but I am using an unmodified eclipse (no plugins) and just javascript to deploy the content in FatWire. The result works pretty well.

The project is basically the same distribution kit I developed for FatPhone but it is now standalone and I provided also the eclipse configuration files.

How FatStart works?

Just to give a taste of how the system works, please give a look to a few screenshots below.

Once you checked out FatStart from the GitHub repository and imported it in eclipse (also you have to do some tweaking explained in the README), this is what you will see:

Now you can edit your jsp directly in eclipse. You can also create your content model directly in Eclipse in Json format. For example this is the format of a content definition:

{
 "AssetType": "fsContent_CD",
 "internalname": "fsArticle",
 "internaldescription": "FatStart Article",
 "parentselectstyle": "selectboxes",
 "RequiredSingleParentList": "fsCategory",
 "RequiredAttrList": "fsText",
 "OptionalAttrList": "fsAbstract"
 }

The required fields are  described in the developer manual, in the section related to XMLPost of FlexAssets.

The work done can be deployed at any time in FatWire for test  calling the installer: 

http://localhost:8080/res/install.html. 

For example if you change the JSP of  the fsLayout template, you can deploy this way:

If you instead change a content definition, you can deploy it as well this way:

That is all.

 The installer is incremental and will replace existing assets and elements with the new version.  

FatStart Benefits

Basically, since all the site configuration is stored in source files, it can be stored in a version control system.

Each developer can have his own version of the site, and when something else change the code, he has only to update the source code of current version, using common merging techniques, and deploy it in his JumpStartKit.

Once the application is ready, the deployer have only to checkout the source code and install it in the production server.

There are a few limitations. So far the installer can only deploy assets and templates, but it does not create sites, flex families, treetabs or users and roles. Those configurations should be performed manually, although it not a big deal to do so. 

So far the system is in use in a couple of sites I am developing and is robust enough to be used for day to day development. Anyway it is still an alpha release so I recommend precautions (although, once the assets are created in Fatwire, there is no so much differences from creating them manually). 

Any comments is welcome and I recommend the group FatwireDev I manage to discuss it.

Use the subtypes, Luke!

You already use assets types... so you already have the force with you!

But sometimes asset types are just not enough. So you have to learn how to use the force better.

For example, let's assume you have a  lot of Page, but those Pages should be  rendered in different way, if they are placed in different location of the siteplan. So which implementation strategy are you going to use?

I have seen a lot of different solutions to this problem, very often involving  complex logic on the siteplan or extra parameters.

If you use the position in the siteplan, it can break easily, while extra parameters are a pain in the ass when it comes to caching.

Actually, the correct solution is to use subtypes.  More in the detail:

• create a subtype for the different page renderings,
• select the subtype when you create a page
• use the subtype to dispatch to the correct rendering code.

Create a subtype and assign it

Go into the Admin panel, select Page and open it: you will see the subtype node; this will give you the opportunity to add a new subtype:

Now, when you create or edit a page, you can now see a pull down allowing to choose your subtype:

Recognize the subtype in the code

Now you can forget about passing spurious parameters or complex siteplan logic. When it comes to to render a page, read the subtype with asset:getsubtype, the call a different template according to the subtype. For example (look at the bold code):

<asset:getsubtype 
 type='Page'
 objectid='<%= ics.GetVar("cid") %>'
 output='subtype'/>
<render:calltemplate
 tid='<%= ics.GetVar("tid") %>' site='<%= ics.GetVar("site") %>'
 c='<%=ics.GetVar("c") %>' cid='<%=ics.GetVar("cid") %>' slotname='Body'
 tname='<%=ics.GetVar("subtype")+"/Body"%>'>      
</render:calltemplate>

This is a typical case for a "Body" template; if you have defined  Home and  Body subtypes, the code will dispatch to an "Home/Body" template and a "Content/Body" template according to the subtype of the page.

How JRebel saved my life (almost)

This post is both an advice and a short story in the life of a Fatwire consultant.
Some time ago I faced one of the most challenging tasks I can remember. It was not particularly hard from the technical side but it was very hard given the time constraint and the environment I had to work.

Basically I had to "fix" (let's say so) an URL Assembler to create some special behaviours for some specific assets. Normally I develop my URL assembler in the Jump Start so I can restart quickly and freely. In that special case, I had to work on a development server because the URL Assembler was actually dependent on the content.
The problem was the specific development server was hosted in a JBoss server in a pretty slow machine, and shared by two other developers that were working on it at the same time.

Restarting the development server was taking each time something close to 5 minutes, and everytime I restarted it, immediately I received phone calls, instant messaging or people coming to my desk very angry saying "have you restarted again"? The time constraint was also very tight, I had to complete that task in a couple of days... but it was very likely I had to restart a number of times because it was a trial and fail process. The situation was looking desperate and I was ready to admit failure and face the consequences, when someone suggested to use JRebel. the dynamic code reloader for Java.

While I was aware of the existence of that tool, I never considered it. I was expecting a complex installation procedure, a very slow server afterwards, a lot of incompatibilities. But I was desperate enough to give at least a try.
To my great surprise, installation was very easy (just copy a jar in a folder and copy and paste a configuration in the launcher script). And when the application server was restarted it was looking to work perfectly. So I did the last step: I ensured that the compiled binaries of the class went directly in the classes directory of the cs.war and I started to code.

Every time I was building the class (actually just saving a class in Eclipse since it recompiles automatically) it got reloaded, without affecting the rest.   A miracle!  I was able to complete the task on time, and without other peole yelling at me.

The bottom line is: when you have to code in Fatwire something that is a class... JRebel is very likely to be a great time saver (and a life saver as well, sometimes...).

Assets as classes, Templates as methods

When you design a content model and its related templates in FatWire, it helps thinking  you should consider Asset types as classes, and Templates as methods, that apply to those classes to render the content.

Although it may sound odd, here a few examples.

Let's start from a Page (that is a common asset you normally use as is). Which methods can you apply to this class? Well, methods here always refers to rendering methods.

It is common you want to display a page like a full page. Because normally header and footer are managed by the Layout, you can call the method Body. So Page/Body is a template (working like a method) that renders a Page in full, as a body. Another case that happens is that I just want to render the Page  like a simple Link. Here another method can help, let's call it  Page/Link. It is also very common you want also render a Summary with Page/Summary.

Now let's consider another type, for example a user defined type like Article; if it is a class, which methods we should use? Obviously we can think of something like before: Article/Body to render an article as the body of a full webpage, Article/Link to render it as a simple linke, and Article/Summary to render just a summary of it.

The underlying idea

Now, it is important to understand that we should use common method names, and  for a precise reason: if you add to a container an Article or a Page, and you want  to render, for example, a list of summaries to Page or Articles, you can do it without having to write  code to distinguish the different cases.

So, good rules to follow when designing (or naming) the templates are:

• decide and use a common naming conventions for templates. For example Summary,Link,Body etc
• give a type, and better a subtype, to each template you use
• reserve the "apply to many type templates" only to a few templates that (like the Layout) really apply to different types

You have to consider that whey you perform a "call template", calling the same template name for different types must template equivalent in function  for that type.

Put simply, a call template for "Summary" must call the Page/Summary if the requested asset is a Page; or Article/Summary if the page is an Article. And both must produce valid html, good for any summary in the design of your site.

This is one of the most powerful (and misunderstood) feature in Fatwire ContentServer.

When to use Basic Assets

Nowadays Flex Assets are used in a predominant way to build your Fatwire website.
Basic Assets are however still there, and there are some cases when I consider (and use) them.  Here is a couple of examples:

Data Migration

Basic Assets are more close in their underlying structure to a database table than the Flex Assets. So it is viable to fill them with database queries. It is much more difficult to do so with Flex Assets.

For example recently I had to migrate a large dataset that was not expected to change. It was simpler to create a basic asset and then move data in the generated table than use a flex asset and the Bulk Loader (that is nonetheless available for those tasks, as well).

User Generated Content

Another case is to store User Generated content: for example, user registration. Instead of building a full feature Flex Asset (using for example the Asset API) it was simpler just to create a plain basic asset and register users creating new instances of that asset.

Is is also faster to create an instance of a Basic Asset than of a Flex Asset, and this can be a winning feature sometimes.

A, PD, CD, P, C and F… oh my!

Confused by the names of the various elements of a flex family?

It is actually pretty simple.

In a flex family you have basically contents (e.g. fp_C) organized in categories (e.g. fp_P) or parents.

You can define many subtypes for contents and parents. Those subtypes are called Content Definitions (e.g. fp_CD) and Parent Definitions (e.g. fp_PD). There is an asset to define each subtype of  a content and an asset to define each subtype of a parent.

A definitions is basically a collection of attributes, so you define as the first step the attributes (e.g. fp_A) then group them in definitions.

Finally, there are filters (e.g fp_F). They are used to apply some post processing to assets when they are created or updated. For example copying fields, image resizing to create thumbnails, etc.

Installation of ContentServer on DB2

When you install ContentServer on DB2, there is an important step in the installation manual that can be easily overlooked. When you create a database, you have to select pages to be 32k. The default is 4, and also the image in the installation manual shows 4k, so you can  easily forget it. If you don't set pages to 32k, installation will misteriously fail...  And this is a problem that can be very hard to track.

FatPhone 0.2 released

I am pleased to announce the release of version 0.2 of FatPhone. This version is the first to be actually usable to build  a real, although pretty  simple, iPhone website.

Here is the list of the new features.

Flex Family content

Flex content is most significant improvement of this release. In 0.1 there were only pages and templates, and the code was good for building the siteplan, but it was not supporting any real content. In this release there is finally the content, in the form of a flex asset with a flex definition.

To provide flex content however I had to introduce the whole Flex Family concept and, more important, to make them installable with the installer. This turned out to be a lot of work.  I think the work with the installer is now mostly done, so I can focus adding more features to the site.

Installation prerequisites are now a little bit more complex, since you need to create a Flex Family before installing FatPhone. Once you have done it, the creation of the required Attribute Editors, Attributes and Content Definitions is performed by the installer.

Installing FatPhone is not hard but at some point I may create a video to clarify the procedure.

Basically you have to create a FlexFamily as follows:

Text Content

I introduced a content asset (type fp_C, subtype fpMultiText) . It is  rendered as follows:

Those assets can be added as children of pages:

A page is now rendered combining the siteplan children (Pages) and the direct children of a page (fp_C), as follows:

Redirect to the Home Page

Another small feature  is that now you can reach the home page simply accessing the file "/fp/index.html" (or just "/fp/" if you have configured index.html as index pages).. This page will redirect to site catalog entry that will in turn locate the home page by name and redirect to the  page named fpHome.

Fixed Bugs and Future Directions

I fixed a few bugs. The most annoying was one preventing the install to work if you don't have firebug active (!), and this was reported by Anuhya of Sayam (thank you).

Next releases I will implement the navigation and extend the number of content types available, to render the full set of the capabilities of iWebKit. Stay tuned!

Ensure success for your Fatwire project / 1

These days I am discussing the plan for a Fatwire project. I was asked (and it is not the first time)  what to do to ensure success.

I decided to share some  thoughts (at least the less technical ones, those  more generally applicable). Since the post is long, I have split it in a sequence of posts.

While planning your website, you will have to take a few precautions. Fatwire ContentServer is not Joomla, where all you have to do is to pick a design and code a few templates to render your site design.

Fatwire is a complex Enterprise Content Management system, where Enteprise actually means something more than just a high price. More specifically it means:

• flexible (but complex) content model definition

• powerful but very specific tag library, hard to use correctly unless you know the big picture

• high performance but complex cache management

Content Model Definition

Let's start with the Content Model definition. Content Models in Fatwire are very rich, much  richer and complex than the average. A Fatwire website is truly defined by his ContentModel.

A good content model will make easy to manage your site. A bad content model will make  it a pain.

Content Model is not just  articles (with title, author, summary and text), although I have seen sites built this way...

Content Model in Fatwire are pretty complex because they impact  both the editorial interface, the template coding  and, most important, the caching strategy.

So here my advices about the content model.

Do:

• Grab your site design (your nice photoshop mockups) and ask someone competent to design the content model.
• A good design will recognize common elements (and  distinguish different elements as well) and exploit the common patterns of your site (summary, boxes, links etc)
• Test the content model BEFORE starting to code  templates

How to test a content model? It is easy: once configured the content model in Fatwire, and before you code the templates,  ask your editorial team to compose some key part of the site like the home page. You will immediately learn if the Content Model is right or not.

Do not

• Throw your site design to inexperienced  developer, allowing them to code  the content model directly on the backend, with no design and no plan.
• Rush to code the content model without ensuring it works for your Editorial Team
• Deploy the site just coded without stress testing it

Very likely,  this way you will get either a very expensive static site ( that is using the SitePlan for everything). Very often, inexperienced developers create a  new entire FLEX FAMILY for each content.

(a flex family is a group of related content, and creating a flex family for each content is a devastating but common error).

This will induce a lot of template coding errors that will in turn will result a site impossible to edit and very very very slow...

In the next post I will tell more about the relation between template and cache.

Stay tuned.