Download pulse

Set up a sub-project

Learn how to create a sub-project and include it into the pulse build process. This guide will lead you through the process step by step. From creating the directory layout to creating your own first bundle and component.

Create the directory skeleton for the sub-project

The basic skeleton of a pulse sub-project is really simple. It is contained in its own directory which consists of six top-level directories and the build.properties:

  • bundles: a directory which will contain all files of any bundle which will be created in the sub-project. You can also add bundles of the pulse distribution to this folder to overwrite files of the distribution with your customizations.
  • components: this directory will contain all files and source code for each components in the sub-project. Like all other folders, this folder can be used to overwrite files from the pulse distribution.
  • conf: this folder can be used to overwrite files from the pulse distribution.
  • lib: for additional libraries required by the sub-project.
  • web: web resources of the sub-project.
  • xsl: the main XSL files of the subproject.

Basically this is a simplified version of the pulse project layout. For all out following examples we will name the project's root directory "examples-for-pulse" and put it next to the unpacked source distribution which will be inside a folder named "pulse-source-dist".

Add the sub-project to the build properties

To add the project to the pulse build process, you will first have to go into the root folder of the pulse source distribution and edit build.project.properties. Look for the following line:

#####################################################################
# additional projects
#####################################################################
build.additional=

and change this to

#####################################################################
# additional projects
#####################################################################
build.additional=../examples-for-pulse

Now we still need build.properties for the sub-project. Let's start by copying build.project.properties and removing everything which is not needed. Your version should look similar to the one below:

# overwrite on copy task
build.copy.overwrite=true

# components to be included
pulse.components=
# bundles to be included
pulse.bundles=

# additional projects
build.additional=

# advanced build settings
pulse.dist.include-library-licenses=true
admin.ext-js.folder=

Now check whether the project can be built, by typing ant in the root folder of the pulse distribution (pulse-source-dist).

Create the directory skeletons for "example" component and bundle

!
A short introduction to bundles and components in general can be found in the "Download & Install" section. If you haven't done so yet, we strongly suggest that you read the introduction first.

Creating the "example" component

Now we start to prepare a new bundle and a new component to be used throughout the development section.

Let's create the component first: Go to the components folder in examples-for-pulse and create a new folder example.

Note that by convention all component names start with a lower case letter.

Within the new component's folder create three additional folders: resources for web resources (e.g. images and JavaScript), src (Java and other source code), xsl (XSLT output templates). Within the src folder you create another subfolder named java which will be the root for all your component Java sources.

The resources folder (if present) must not be empty or the build will fail. To fix this problem, simply create an empty file within the folder (e.g. dummy.file).

Creating the "Example" bundle

As a convention all bundle names start with a capital letter.

So we will create a folder named Example in the bundles directory as the root folder for the "Example" bundle. Within the new bundle's folder we make two subfolders: resources for web resources (e.g. images and JavaScript) and xsl for XSLT output templates.

As you can see, both structures are simple and rather similar to each other.

 

Add the necessary configuration

:
Remember the golden rule: Components provide – bundles expose.

Don't know the rule yet? Consider reading this first.

Include the bundle and the component in the sub-projects build properties

First of all, we have to include both the bundle and the component in the build process. To do this open the build.properties in examples-for-pulse and edit the following lines to match:

# components to be included
pulse.components=example
# bundles to be included
pulse.bundles=Example

A configuration for the bundle

The main configuration of each bundle is in a file named bundle.xml in the bundle's root folder. Let's start with the most simple configuration for a bundle, which still exposes nothing (but then we didn't create anything yet). So please create the following bundle.xml in examples-for-pulse/bundles/Example:

<?xml version="1.0" encoding="utf-8"?>
<bundle>
    <!-- controllers exposed by this Bundle -->
    <controllers/>

    <!-- the implementations of org.torweg.pulse.site.content.Content exposed by this Bundle -->
    <content-mappings/>

    <!-- the Joblets of this Bundle -->
    <joblets/>
</bundle>

Assign a configuration to the component

Just like each bundle has its main configuration in its root folder within bundle.xml, each component is configured by a component.xml in its respective root folder. So this is the component.xml to place in examples-for-pulse/components/example.

<?xml version="1.0" encoding="utf-8"?>
<conf:component xmlns:conf="http://pulse.torweg.org/container">
    <!-- all JPA entities provided by this component -->
    <jpa-entities/>
    <!-- all packages of this components which are enabled for JAXB, 
        i.e. they contain a "jaxb.index" -->
    <jaxb-endorsed/>
</conf:component>

Check if it works

Go to the root folder of the pulse source distribution and type ant. The build should complete successfully.

Now check whether the deployed webapp contains all files. Go to the root folder of the deployed webapp and enter the resources/components directory. It should contain a folder example with the dummy file from examples-for-pulse/components/example/resources. Also check the resources/bundles directory whether it contains a folder named Example. Finally check whether WEB-INF/bundles/Example and WEB-INF/components/example exist and contain their main configuration files.