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.

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.

A javascript interface to CatalogManager

FatPhone installer requires  creation of elements, as well as assets. But XMLPost does not create those elements, at least for Templates, so the installer has to create those elements calling directly CatalogManager .

I wrote a Javascript class that does just this:  interfaces with CatalogManager for creating and querying rows. Since this class is useful by itself, I am writing this  post as documentation for general usage.

Code is available in the FatPhone github public repository:  the file is named  catalogmanager.js.  It is released under the GPL. You can download and use in your project freely. There is also a test html page to test and call it interactively.

Now, 2 important warnings:

• You cannot use it locally. You have to copy the code in the static area of your FatWire installation site, and invoke the javascript with a browser. Security restrictions prevent executing remote http calls from locally loaded files.
• It is not 100% complete: does not offer access to every feature of CatalogManager.  Nonetheless, in the current state,  it is useful to create, update and delete rows, perform simple queries and  check if a row exists.

It can also already perform generic queries, but the returned result  is just the HTML of the response. I should parse the HTML and return the answer in json format to be more useful.

To summarize the available functions:

1. Create a new Catalog Manager object.
2. Login into content server.
3. Select a row (returning the result in)
4. Check for the existence of a row
5. Add a row
6. Edit a row
7. Delete a row

Creating a new Catalog Manager object

var cm = new CatalogManager(url)

where url is the Fatwire ContentServer base url (tipically http://www.yoursite.com/cs/),

Login into FatWire

cm.login(username, password, loginFunction, errorFunction)

where username and password are your FatWire credentials.  If login is ok, loginFunction is called, otherwise errorFunction is called.

Select a Row

Once you are logged on , you can execute calls. The simplest call is:

cm.selectRow(tablename, where, what, callbackFunction)

this will perform a query on the given tablename, specifying a where condition  and what (fields) to search for. The callbackFunction will be called with the result.

For example,

 cm.selectRow(Page, "id", "name='Home'", alert)

will show in an alert box the result of searching the Page table for records with name Home, and will return his id. A simple regular expression can extract the id from the returned result. I do exactly this in the installer, you can check the source code of install.js to see an example.

In an ideal world,  I should parse the returned html in a structured javascript object (an array of maps, for example). If you want to improve the code before I will do it... your help is appreciated.

Check for existence of a row

cm.checkExist(tablename, selwhere, found, notFound)

This function perform a limited parsing of the result to see if the row in tablename, specified in the selwhere, was found or not. The appropriate callback function is called according to the result.

Add a row

cm.addRow(tablename, data, nextStep)

tablename is a string, the name of a row, while data must be a map. For example, this call create a new Element in the ElementCatalog (assuming that elementName, fileBody, fileName and fileFolder are defined, of course):

cm.addRow("ElementCatalog", {
 "elementname" : elementName,
 "url" : fileBody,
 "url_file" : fileName,
 "url_folder" : fileFolder
 }, nextStep)

The function nextStep is called with a status object  passed as the first parameter. The status is a map that has at least 3 keys:

• ok is a boolean telling if the result is successful or no not
• answer is the unparsed answer
• parsed is a boolean telling if the answer was parsed. If true there are also the following fields defined (parsed from the CatalogManager returned status)
  • result
  • reason
  • err
  • command

Edit a row

cm.editRow(tablename, data, nextStep)

tablename is a string, the name of a row, while data must be a map and nextStep is a function called with the status of the result.

Both data and the return status have the same format as in addRow, except that the data must specify the id field to make the call work.

Delete a row

cm.deleteRow(tablename, data, nextStep)

tablename is a string, the name of a row, while data must be a map and nextStep is a function called with the status of the result.

Both data and the return status have the same format as in addRow, except that the data must specify an id field to make the call work successfully. Actually, in the delete the id is the only required field, any other field in this call is just ignored

Create a new asset using json and jquery

I am a bit silent in the blog these days because I am very busy  building an easy installer for FatPhone.

In the process I am learning a lot of new stuff. Well, not exactly new stuff, it is actually  old stuff in a new dress. Anyway I am excited to discover how using jQuery it is possible to implement in simple JavaScript what previously has to be done in complex Java.

Basically the  biggest challenge of the FatPhone installer is to implement the creation of new asset, not just loading Elements. I want to use Javascript instead of CatalogMover, and I am having some success in this process.

A jquery asset creator

In this post I am talking about one of the "secrets" of the upcoming FatPhone installer. I mean,  asset creation using jQuery.

It is not all jQuery. Fatwire side, I am using the entry point for the XMLPost. You usually use XMLPost with the XMLPost utility.

Since it is not so easy to use it, I decided to keep the XMLPost on Fatwire side but write in jQuery the client side. Let's see how.

Describe in JSON (instead of XML)

Let's assume we want to create a new asset, for example a Page, with name "Home" and description "HomePage".

You can describe this stuff in json, so this is the body of the Home.json file:

{
 "AssetType": "Page",
 "publication": "FatPhone",
 "name": "Home",
 "description": "HomePage"
}

"AssetType" is there because we are going to use the XMLPost entry point to create the Asset, and it requires a field "AssetType" to decide which type of asset is going to create.

Also "publication" is required to define to which site the  new asset will belong.

The other fields are just fields of the asset.

Write the jquery post script

The HTML containing the jquery script is:

1. In the header load jquery

<script type="text/javascript"
 src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js">
 </script>

2. Define the url to access the XMLPost entry point:

<script type="text/javascript">
 var csUrl = "/cs/ContentServer"
 + "?pagename=OpenMarket/Xcelerate/Actions/RemoteContentPost"
 + "&authusername=fwadmin&authpassword=xceladmin"
</script>

Note that here I am assuming that the script will be called from the same host where is ContentServer. Also as username and password are the standard ones. Of course this should be true only if you are in a local installation... So remember to change username and password.

3. Now let's write a new function:

<script type="text/javascript">
 function createAsset(fromFile, toUrl) {
   $.getJSON(fromFile, function(data) {
     $.post(toUrl, data, function(result) {
       alert(result)
      })
    })
 }
 </script>

What this script does:

a) it reads the Home.js (containing json data) and stores the data in a local javascript variable.

b) it performs a post with the read data, using as target the XMLPost entry point (the url we have already defined before).

c) finally it displays the result with an alert window.

4. It is  now time to create a button that will trigger the execution of the function; we put the button in the HTML body:

<body>
  <input type="button" value="Create Home Page"
    onClick="createAsset('Home.js',csUrl)"/>
</body>

That's all. Let's test it.

An example

If everything is fine, clicking on "Create Home Page" button you will receive a messagge announcing that the asset has been created sucessfully:

If you inspect the backend you should be able to see the page in the site plan as well:

If things don't  work I recommend  checking carefully urls, username and password, and  inspect execution with FireBug.

Typed templates

A very interesting concept in Fatwire is that templates are "typed".

Unfortunately, this is also a concept very easily misunderstood.

The idea is:

• You define a number of content types
• Then you apply a set  of standard templates to that content type (like method of a class in OOP)
• Name of the templates should be standardized

For example, you can have News, Articles and Blog posts as content types.

The best way is to decide for a number of common way of render the content: for example: Summary, Detail, Link.

So you can expect to have something like this:

News/Summary
News/Detail
News/Link
Article/Summary
Article/Detail
Article/Link
Blog/Summary
Blog/Detail
Blog/Link

If you follow those conventions,  combining templates becames very easy. You can add in a page a Blog or an Article and then replace with a News.

Just call the template as it should (using a call:template that specify the c and only the Summary - the "relative" way). This way rendering an Article as a summary is the same as rendering a Blog as a summary.

But you start to give different names to template without following any conventions... your code will became a mess.

And you won't exploit the "typed template" approach built-in in Fatwire.