BlocksDefinition

A Cocoon block is a zipped archive, just like JARs and WARs.

The suggested extension of a cocoon block is ".cob" (for COcoon Block).

The suggested MIME type is "application/x-cocoon-block".

A Cocoon Block (COB from now on) includes a directory called

   /COB-INF

which contains all the block metadata, classes and jars. The directories

{{{ /COB-INF/classes

• /COB-INF/lib}}}

are used for classes and jar files. (This follows the WAR paradigm)

The main COB descriptor file is found at

  /COB-INF/block.xml

This file contains markup with a cob-specific namespace and will include the following information:

• block implementation metadata:
  • unique URI identifier
  • short name
  • description
  • author
  • licence URL
• provided components(s):
  • the roles of the components that this block exposes (optional)
• dependencies:
  • the URI(s) of the blocks on which this blocks depends on (optional)
• inheritance:
  • the URI of the extended block. (optional)
• sitemap:
  • the location inside the block file space of the sitemap (optional, if not found defaults to '/sitemap.xmap')
• parameters:
  • the parameters required to be asked at deployment time (optional)

What about "implements"?

The main COB configuration file (optional) is found at

  /COB-INF/block.xconf

and contains the configurations that are used by the components included in the block.

Block configuration at deployment time

Blocks will contain configurations written at block-release time but some information is deployment dependent. The block deployment descriptor contains a list of those parameters that are required to be entered at deployment time.

Since these configurations will be rather context-dependent tokens, these can be considered more as properties. An example of a descriptor could be:

{{{ <properties>

• <property name="username">

  • <default>guest</default> <description>The name of the user</description>

  </property>

• ..

• </properties>}}}

This needs to be synced with the block.xml discussion

then, these values will be accessible in the usual block.xconf using {name} style. For example {{{... <datasources>

• <datasource name="rbdms">

  • <username>{username}</username>

  • ..

  </datasource>

</datasources> ...}}}

Exposed Services

A block exposes two types of services:

• components
• resources
• pipelines ??

Accessing components

The block.xml descriptor includes the list of components which are exposed and made available by the block.

Blocks that depend on this block use the component role (as they normally did with block-less cocoon) and the component manager will load the appropriate component. Everything is done by the component manager and the block manager thru block.xml and wiring information.

What happens with role name conflicts?

Accessing resources

Following IoC practices, there isn't (and there should not be) a way for a block to directly access another block.

This means that one block doesn't know where the blocks it depends on are located, both on disk *and* on the URI space as well.

Blocks access the blocks they depend on through a block-specific protocols that is able to dereference the block instances thru wiring.

For example, the myblock.cob/sitemap.xmap file could contain a global matcher which works like this:

{{{ <map:match pattern="**/*.html">

• <map:generate src="{1}.xml"/> <map:transform src="block:skin:/stylesheets/document2html.xslt"/> <map:serialize/>

• </map:match>}}}

please note the

  block:skin:/stylesheets/document2html.xslt

which indicates

• block -> use the block protocol

• skin -> use the 'skin' prefix to lookup the block behavior URI and thus

the block which implements it for this block (the block manager knows this)

• /stylesheets/document2html.xslt -> it will ask the sitemap of the skin

block to produce that resource.

The above implies that all resources that a block provides are provided by its sitemap. There is no way for a block to access directly the content of another block.

Dereferencing navigation

Not only does a sitemap need to connect to the resources contained in the blocks it depends on, but the resulting pages as well.

For example, things like

   <form action="block:web-service:/post">...</form>

should be transformed into some accessible URL such as

   <form action="/servizio-web/post"/>...</form>

before being sent to the browser.

This is performed by a block-aware link transformer put right before the serializer.