In this short tutorial we are going to walk you through the steps needed to get started with the 4.0.0.ALPHA1 version of the CDK.  This will include steps needed to get setup, and constructing a simple JSF 2.0 component.

Keep in mind that this is the ALPHA1 release and not all aspects of component development are completed.  They will be as the milestone releases progress and keep an eye out at the wiki for updates.

Getting Setup

Although RichFaces CDK supposed to be used with different build tools, the ALPHA1 release includes Maven plugin only. That plugin and its dependencies have been deployed to the Jboss release repository. The "MavenSettings" article describes how to setup build environment to use that repository.

Also, ALPHA1 release does not yet include any archetypes for component projects, so it should be started as simple Maven project.

Important notice: CDK used Java 6 compiler API, hense build process should be run under JDK 6.

The Component Artifacts

There are two mandatory dependencies for component project: Jsf-api and cdk annotations. The first one is obvivious ( how is it possible to compile JSF component without API library ? ), but second one contains CDK annotations that are used by CDK to collect information about components. Because all CDK annotations are targeted for 'class', it is not necessary to include annotations library at runtime:

  <dependencies>
    <dependency>
      <groupId>com.sun.faces</groupId>
      <artifactId>jsf-api</artifactId>
      <version>2.0.0-SNAPSHOT</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>org.richfaces.cdk</groupId>
      <artifactId>annotations</artifactId>
      <version>4.0.0.ALPHA1</version>
      <optional>true</optional>
    </dependency>
  </dependencies>

Build configuration

To run CDK plugin during project build, it should be configured in the pom.xml :

  <build>
    <plugins>
      <plugin>
        <groupId>org.richfaces.cdk</groupId>
        <artifactId>maven-cdk-plugin</artifactId>
        <version>4.0.0.ALPHA1</version>
        <configuration>
        </configuration>
        <executions>
           <execution>
            <id>generate</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>

                <!-- Maven CDK plugin configuration -->
            </configuration>
          </execution>
        </executions>
      </plugin>

Project structure.

CDK uses stsndard Maven project structure with some additions:

Java sources expected at the src/main/java folder.

Faces-config.xml files should be put into src/main/config folder. Currently, the name of that folder is hardcoded and all files with .xml extension will be processed as faces-config fragments.

Renderer templates are expected in the src/main/templates folder. Once again, all *.xml files from that folder will be processed as renderer templates.

CDK puts generated files into target/generated-sources/java and target/generated-sources/java folders and appends these folders to maven Java sources/resources collections so these files will be compiled during compile phase.

Creating component files.

There are two ways to create JSF component with CDK. The simplest way is to create abstract or concrete component class and mark it with CDK RichFaces CDK annotations . The other way is using faces-config.xml file with RichFaces CDK faces-config extensions.

Create rendered from template.

To create JSF renderer using RichFaces CDK renderer template language, just create file named like "myRendered.xml" in the src/main/templates folder.

Compiling the Component

As all component files are prepared, final jar can be compiled as "mvn install" command. At the "generate-sources" Maven lifecycle phase, CDK plugin will parse source files for annotations and read faces-config.xml and then generate necessary Java files, final configuration xml file and taglibs.

Adding to an Application

What To Expect Next

Briefly talk about the features that should be in ALPHA2 - behavior support, core API integrations, easy ajax integration, etc...