\r\n

51Degrees Pipeline Documentation  4.1Newer Version 4.4

Search

Documentation

• Examples
• Examples with a custom flow element
• Custom Engine Using Client-Side Evidence

Custom Engine Using Client-Side Evidence

Introduction

This example takes the very simple flow element described in the simple flow element example, and adds a JavaScript property to use client side evidence.

Instead of using evidence which is already available, as the simple flow element example did, this example will send JavaScript to the a client to get the evidence.

Download Example

The source code used in this example is available here:

• C# Visual Studio project
• Java project
• PHP project
• Node.js project

Dependencies

The flow element will need a dependency on the Pipeline core package

C# Java PHP Node.js

Select a tab to view language specific dependencies.

The only dependency needed for .NET is the FiftyOne.Pipeline.Core NuGet package.

The only dependency needed for Java is the pipeline.core Maven package from com.51degrees. To include this, add the following to the <dependencies> section of the project's pom.xml:

<dependency>

<groupId>com.51degrees</groupId>

<artifactId>pipeline.core</artifactId>

<version>4.1.0</version>

</dependency>

todo

Add a dependency to the fiftyone.pipeline.core NPM package to the package.json, and required it in the source with require("fiftyone.pipeline.core").

Data

The element data being added to the flow data by this flow element is a star sign. So this should have its own 'getter' in its element data. The additional property containing the JavaScript to get the date of birth is also added using the appropriate type.

C# Java PHP Node.js

Select a tab to view language specific element data implementation.

.NET supports interfaces, so the element data should have a public interface and an internal concrete implementation with easy 'setters'.

In this example, values for star sign and JavaScript are populated. So an interface IStarSign will extend IElementData to add a 'getter' for it.

Now the internal implementation of it will implement this 'getter' and add a 'setter' for the flow element to use.

Java supports interfaces, so the element data should have a public interface and a package private concrete implementation with easy 'setters'.

In this example, values for star sign and JavaScript are populated. So an interface StarSignData will extend ElementData to add a 'getter' for it.

public interface StarSignData extends ElementData {

String getStarSign();

JavaScript getDobJavaScript();

}

Now the internal implementation of it will implement this 'getter' and add a 'setter' for the flow element to use.

class StarSignDataInternal extends ElementDataBase implements StarSignData {

public StarSignDataInternal(Logger logger, FlowData flowData) {

super(logger, flowData);

}

@Override

public String getStarSign() {

return getAs("starsign", String.class);

}

void setStarSign(String starSign) {

put("starsign", starSign);

}

@Override

public JavaScript getDobJavaScript() {

return getAs("dobjavascript", JavaScript.class);

}

void setDobJavaScript(JavaScript dobJavaScript) {

put("dobjavascript", dobJavaScript);

}

}

Note that this concrete implementation of StarSignData sits in the same package as the flow element, not the StarSignData interface, as it only needs to be accessible by the flow element.

todo

Node's implementation of element data does not require concrete getters for IDE autocompletion, so elementDataDictionary can be used.

JavaScript

The client-side JavaScript for this example will be fairly simple. It will create a popup asking the user to enter their date of birth. It will then store the date of birth in a cookie named 'date-of-birth' and reload the page with the new cookie present.

The JavaScript to do this looks like:

// Ask the user for their data of birth.

var dob = window.prompt('Enter your date of birth.','dd/mm/yyyy');

if (dob != null) {

// Store it in a cookie.

document.cookie='date-of-birth='+dob;

// Reload the page with the new cookie.

location.reload();

}

Flow Element

Now the actual flow element needs to be implemented. For this, the flow element's base class can be used which deals with most of the logic. The element properties, evidence keys and the processing are all that need implementing.

C# Java PHP Node.js

Select a tab to view language specific flow element implementation.

First let's define a class which extends FlowElementBase (and partially implements IFlowElement). This has the type arguments of IStarSignData - the interface extending element data which will be added to the flow data, and IElementPropertyMetaData - as we only need the standard metadata for element properties.

This needs a constructor matching the FlowElementBase class. So it takes a logger, and an element data factory which will be used to construct an IStarSignData:

The Init method in this example will simply initialize a list of star signs with the start and end dates of each star sign and add each to a list of a new class named StarSign which has the following simple implementation:

Note that the year of the start and end date are both set to 1, as the year should be ignored, but the year 0 cannot be used in a DateTime.

The new Init method looks like this:

Now the abstract methods can be implemented to create a functional flow element.

First let's define a class which extends FlowElementBase (which partially implements FlowElement). This has the type arguments of StarSignData - the interface extending element data which will be added to the flow data, and ElementPropertyMetaData - as we only need the standard metadata for element properties.

This needs a constructor matching the FlowElementBase class. So it takes a logger, and an element data factory which will be used to construct a StarSignData:

public class SimpleClientSideElement extends FlowElementBase<StarSignData, ElementPropertyMetaData> {

public SimpleClientSideElement(

Logger logger,

ElementDataFactory<StarSignData> elementDataFactory) {

super(logger, elementDataFactory);

init();

}

The init method in this example will simply initialize a list of star signs with the start and end dates of each star sign and add each to a list of a new class named StarSign which has the following simple implementation:

public class StarSign {

private final Calendar end;

private final Calendar start;

private final String name;

public StarSign(String name, String start, String end) {

this.name = name;

this.start = Calendar.getInstance();

String[] startDate = start.split("/");

this.start.set(

0,

Integer.parseInt(startDate[1]) - 1,

Integer.parseInt(startDate[0]));

this.end = Calendar.getInstance();

String[] endDate = end.split("/");

this.end.set(

0,

Integer.parseInt(endDate[1]) - 1,

Integer.parseInt(endDate[0]));

}

public String getName() {

return name;

}

public Calendar getStart() {

return start;

}

public Calendar getEnd() {

return end;

}

}

Note that the year of the start and end date are both set to 0, as the year should be ignored.

The new init method looks like this:

private void init() {

List<StarSign> starSigns = new ArrayList<>();

for (String[] starSign : starSignData) {

starSigns.add(new StarSign(

starSign[0],

starSign[1],

starSign[2]));

}

this.starSigns = starSigns;

}

Now the abstract methods can be implemented to create a functional flow element.

public class SimpleClientSideElement extends FlowElementBase<StarSignData, ElementPropertyMetaData> {

public SimpleClientSideElement(

Logger logger,

ElementDataFactory<StarSignData> elementDataFactory) {

super(logger, elementDataFactory);

init();

}

private static final String[][] starSignData = {

{"Aries","21/03","19/04"},

{"Taurus","20/04","20/05"},

{"Gemini","21/05","20/06"},

{"Cancer","21/06","22/07"},

{"Leo","23/07","22/08"},

{"Virgo","23/08","22/09"},

{"Libra","23/09","22/10"},

{"Scorpio","23/10","21/11"},

{"Sagittarius","22/11","21/12"},

{"Capricorn","22/12","19/01"},

{"Aquarius","20/01","18/02"},

{"Pisces","19/02","20/03"}

};

private List<StarSign> starSigns;

private void init() {

List<StarSign> starSigns = new ArrayList<>();

for (String[] starSign : starSignData) {

starSigns.add(new StarSign(

starSign[0],

starSign[1],

starSign[2]));

}

this.starSigns = starSigns;

}

@Override

protected void processInternal(FlowData data) throws Exception {

// Create a new StarSignData, and cast to StarSignDataInternal so the 'setter' is available.

StarSignDataInternal elementData = (StarSignDataInternal)data.getOrAdd(getElementDataKey(),getDataFactory());

boolean validDateOfBirth = false;

TryGetResult<String> dateString = data.tryGetEvidence("cookie.date-of-birth", String.class);

Calendar monthAndDay = Calendar.getInstance();

if (dateString.hasValue()) {

// "date-of-birth" is there, so parse it.

String[] dateSections = dateString.getValue().split("/");

try {

monthAndDay.set(

0,

Integer.parseInt(dateSections[1]) - 1,

Integer.parseInt(dateSections[0]));

validDateOfBirth = true;

}

catch (Exception e) {

logger.warn("Exception getting the date of birth", e);

}

}

if (validDateOfBirth) {

// "date-of-birth" is valid, so set the star sign.

for (StarSign starSign : starSigns) {

if (monthAndDay.compareTo(starSign.getStart()) >= 0 &&

monthAndDay.compareTo(starSign.getEnd()) <= 0) {

elementData.setStarSign(starSign.getName());

break;

}

}

// No need to run the client side code again.

elementData.setDobJavaScript(new JavaScript(""));

}

else

{

// "date-of-birth" is not there, so set the star sign to unknown.

elementData.setStarSign("Unknown");

// Set the client side JavaScript to get the date of birth.

elementData.setDobJavaScript(new JavaScript(

"var dob = window.prompt('Enter your date of birth.','dd/mm/yyyy');" +

"if (dob != null) {" +

"document.cookie='date-of-birth='+dob;" +

"location.reload();" +

"}"));

}

}

@Override

public String getElementDataKey() {

// The StarSignData will be stored with the key "starsign" in the FlowData.

return "starsign";

}

@Override

public EvidenceKeyFilter getEvidenceKeyFilter() {

// The only item of evidence needed is "date-of-birth".

return new EvidenceKeyFilterWhitelist(

Collections.singletonList("cookie.date-of-birth"),

String.CASE_INSENSITIVE_ORDER);

}

@Override

public List<ElementPropertyMetaData> getProperties() {

// The properties which will be returned are "starsign" and the

// JavaScript to get the date of birth.

return Arrays.asList(

(ElementPropertyMetaData)new ElementPropertyMetaDataDefault(

"starsign",

this,

"starsign",

String.class,

true),

new ElementPropertyMetaDataDefault(

"dobjavascript",

this,

"javascript",

JavaScript.class,

true));

}

@Override

protected void managedResourcesCleanup() {

// Nothing to clean up here.

}

@Override

protected void unmanagedResourcesCleanup() {

// Nothing to clean up here.

}

}

todo

First let's define a class which extends flowElement.

This needs a constructor matching the flowElement class:

Now the abstract methods can be implemented to create a functional flow element.

Builder

Now the flow element needs one final thing, an element builder to construct it. This only needs to provide the flow element with a logger and an element data factory - as this example has no extra configuration options.

C# Java PHP Node.js

Select a tab to view language specific element builder implementation.

The element builder has one important method, and that is Build. This returns a new flow element which the element builder provides with a logger and an element data factory.

The element data factory is implemented in the element builder class to make use of the same logger factory.

The element builder has one important method, and that is build. This returns a new flow element which the element builder provides with a logger and an element data factory.

The element data factory is implemented in the element builder class to make use of the same logger factory.

@ElementBuilder(alternateName = "SimpleClientSideElement")

public class SimpleClientSideElementBuilder {

private final ILoggerFactory loggerFactory;

public SimpleClientSideElementBuilder(ILoggerFactory loggerFactory) {

this.loggerFactory = loggerFactory;

}

public SimpleClientSideElement build() {

return new SimpleClientSideElement(

loggerFactory.getLogger(SimpleClientSideElement.class.getName()),

new ElementDataFactory<StarSignData>() {

@Override

public StarSignData create(

FlowData flowData,

FlowElement<StarSignData, ?> flowElement) {

return new StarSignDataInternal(

loggerFactory.getLogger(StarSignDataInternal.class.getName()),

flowData);

}

});

}

}

todo

The Node implementation does not use separate builder classes. Instead the options are provided by optional constructor parameters.

Usage

As this example gathers its evidence using client-side JavaScript, it will need to be run in a web environment. Using a web integration will mean that the flow element can be added, and the client-side JavaScript automatically run.

C# Java PHP Node.js

Select a tab to view language specific usage.

Using a ASP.NET Core project (full example included in the source), a pipeline configuration file can be added to the 'appsettings.json' to load the new flow element and a 'JavaScriptBuilderElement' to include the client-side JavaScript:

{

...

"PipelineOptions": {

"Elements": [

{

"BuilderName": "SimpleClientSideElement"

},

{

"BuilderName": "JavaScriptBuilderElement"

}

]

}

}

Then a simple view can be added which includes '51Degrees.core.js' to run the JavaScript, and displays the message which is passed from the controller:

@{

ViewData["Title"] = "Home Page";

}

<script type="application/javascript" src="~/51Degrees.core.js"></script>

<div class="row">

@ViewData["message"]

</div>

The message is constructed in the controller in the same way as in the previous example:

Using a Spring MVC project (full example included in the source), a pipeline configuration file can be added to load the new flow element and a 'JavaScriptBuilderElement' to include the client-side JavaScript:

<PipelineOptions>

<Elements>

<Element>

<BuilderName>SimpleClientSideElement</BuilderName>

</Element>

<Element>

<BuilderName>JavaScriptBuilderElement</BuilderName>

</Element>

</Elements>

</PipelineOptions>

Then a simple view can be added which includes '51Degrees.core.js' to run the JavaScript, and displays the star sign which is passed from the controller:

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"

pageEncoding="ISO-8859-1"%>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

<title>Example page</title>

<script src="/simple-clientside-element-mvc/51Degrees.core.js"></script>

</head>

<body>

<p>${message}</p>

</body>

</html>

The message is constructed in the controller in the same way as in the previous example:

@Controller

@RequestMapping("/")

public class ExampleController {

private final FlowDataProvider flowDataProvider;

private final Random rand = new Random();

@Autowired

public ExampleController(FlowDataProvider flowDataProvider) {

this.flowDataProvider = flowDataProvider;

}

@RequestMapping(method = RequestMethod.GET)

public String get(ModelMap model, HttpServletRequest request) {

FlowData data = flowDataProvider.getFlowData(request);

model.addAttribute(

"message",

"With a date of birth of " +

data.getEvidence().get("cookie.date-of-birth") +

", your star sign is " +

data.get(StarSignData.class).getStarSign());

model.addAttribute("version", rand.nextInt());

return "example";

}

}

todo

Using a simple HTTP server, a pipeline can created containing the new flow element.

let pipeline = new FiftyOnePipelineCore.pipelineBuilder()

.add(astrology)

.build();

Then a simple view can be added which includes the JavaScript to run, and displays the star sign which is passed from the controller:

<h1>Starsigns</h1>

${flowData.astrology.starSign ? "<p>Your starsign is " + flowData.astrology.starSign + " </p>" : "<p>Add your date of birth to get your starsign</p>"}

${flowData.astrology.hemisphere ? "<p>Look at the " + flowData.astrology.hemisphere + " hemisphere stars tonight</p>" : ""}

<form><label for='dateOfBirth'>Date of birth</label><input type='date' name='dateOfBirth' id='dateOfBirth'><input type='submit'></form>

<script>

${js}

</script>

The message is constructed and returned:

Next Steps

The example for Custom On-premise Engine shows how you can extend the functionality of this flow element to use a data file rather than hard coded values.

Generated by doxygen 1.8.15