Getting started guide

Welcome to the Ceddl4j getting started guide. If you are unfamiliar with CEDDL, please first read our introduction article and the CEDDL specification.

1. Hello world example

Let’s start with a ‘Hello world’ example. We create a data layer object, a page sub object and a pageInfo sub object. On the pageInfo sub object we set the pageID to ‘Hello World’.

DigitalData ddb = DigitalData.create() // Create the Digital Data base object
    .page()                 // Create and go to the page sub object
    .pageInfo()             // Create and go to the pageInfo sub object
    .pageID("Hello World!") // Set the pageID to "Hello World"
    .endPageInfo()          // Leave the pageInfo object, we are back at page
    .endPage();             // Leave the page object, we are back at Digital Data

To get the data layer contents as a Java String, simply call the toString() method on the DigitalData object. A couple more examples can be found here.

Basically this is all you need to know to use Ceddl4j. You can find all fields which you can set this way in both the Ceddl4j JavaDoc and the Ceddl specification.

2. Adding custom fields

The Ceddl specification allows you to add custom fields to any Object. Ceddl4j provides a custom(String, Object) for this. Custom fields can be Strings, numeric or Date.

DigitalData ddb = DigitalData.create()
    .page()
    .pageInfo()
    .custom("stringExample", "example")
    .custom("numericExample", 42)
    .custom("dateExample", new Date())
    .endPageInfo()
    .endPage();

3. Attributes and categories

Attributes and categories can be used just like regular Objects:

DigitalData ddb = DigitalData.create()
    .page()
    .attributes()
    .attribute("country", "us")
    .endAttributes()
    .category()
    .primaryCategory("FAQ pages")
    .category("subCategory1", "ProductInfo")
    .endCategory()
    .endPage();

Since attributes and categories are used a lot, Ceddl4j also offers a short-hand syntax:

DigitalData ddbshort = DigitalData.create()
    .page()
    .addAttribute("country", "us")
    .addPrimaryCategory("FAQ pages")
    .addCategory("subCategory1", "ProductInfo")
    .endPage();

4. Adding Security objects

You can add CEDDL security Objects directly after adding an Object.

DigitalData ddb = DigitalData.create()
	.cart()
	.addItem()
	.productInfo()
	.productName("Example product name")
	.security("Analytics", "Personalisation") // Make productName only available
                                            // to the Default, Analytics and
                                            // Personalisation access categories
	.description("Example description")
	.security("Analytics")    // Make description only available to the
                              // Default and Analytics access categories
	.productURL("http://www.exampleproducturl.com")
	.defaultSecurity() // Make productURL only available to
                       // the Default access category
	.endProductInfo()
	.endItem()
	.endCart();

This isn’t supported (yet) for the shorthand attributes and categories syntax. But you can use the normal syntax instead.

Also note that Ceddl4j only generates the data layer. It’s doesn’t offer methods to enforce these security settings.

The privacy object which defines the access categories works like any regular Ceddl4j Object.

DigitalData ddb = DigitalData.create()
	.privacy()
	.addDefaultAccessCategory()
	.domains("nonexistent-store.com", "audit.com")
	.endAccessCategory()
	.addAccessCategory()
	.categoryName("Analytics")
	.domains("calc.com")
	.endAccessCategory()
	.endPrivacy()

5. Using the Digital Data setters

For building the data layer in a more modular way, you can also create the sub objects directly and call the setters on the DigitalData Object.

Page page = new Page()
.pageInfo()
.pageID("Hello World")
.endPageInfo();
	
DigitalData ddb = DigitalData.create()
    .setPage(page);

6. Extending the specification with new Objects

Sometimes adding custom fields to existing attributes isn’t enough, but you want to add new Objects. The CEDDL specification includes an example (HealthCare insurance) that adds 3 custom objects (Member, Application and Plan).

Ceddl4j provides a CustomObject base class for these custom objects. You also need to extend the DigitalData Object to add the custom objects.

Or implementation of the HealthCare Insurance example can be found in the examples folder.