Create builder generation behavior
In this topic ...
Implementing Generation Behavior
Extracting Input Values Specified in the Builder Call Editor
Using Other Builders in the Generation Class
Related Topics ...
You define the generation behavior of a builder with a Java class that adds one or more objects to the WebApp.
Implementing Generation Behavior
Implement the builder's generation behavior by implementing the following interface: com.bowstreet.builders.webapp.foundation.WebAppBuilder
In your generation class implement the following method:
public void doBuilderCall(GenContext genContext, WebApp webApp,
BuilderCall builderCall, BuilderInputs builderInputs,
PageLocation pageLocation) { ... }
The parameters to the doBuilderCall() method provide you with the ability to interact with the WebApp object and to place a builder call on a page. The other objects to which you have access in your builder generation class are:
- genContext -- GenContext is a system object that is passed to all the GenHandlers and builders. It is used to create builderInputs objects and to invoke other builders. This object has the lifetime of a generation.
- webApp -- A WebApp is the main executable object in the WebEngine, with collections of pages, methods, variables, and links to other models. We can call methods on the webApp object to add elements to the Web application.
- builderCall -- Represents a call to a builder. One of these is created for each entry in the builder call list, and one is created whenever a builder calls another builder.
- builderInputs -- Holds a set of builder inputs.
- pageLocation -- Holds the page location syntax.
The following code sample shows the generation class for a Hello World builder:
package com.bowstreet.examples.builders.webapp; import com.bowstreet.builders.webapp.foundation.WebAppControlBuilder; import com.bowstreet.generation.GenContext; import com.bowstreet.webapp.WebApp; import com.bowstreet.generation.BuilderCall; import com.bowstreet.generation.BuilderInputs; import com.bowstreet.builders.webapp.pagelocation.PageLocation; import com.bowstreet.builders.webapp.api.Text;
public class HelloWorldBuilder implements WebAppControlBuilder { public HelloWorldBuilder() { } public void doBuilderCall(GenContext genContext, WebApp webApp, BuilderCall builderCall, BuilderInputs builderInputs, PageLocation pageLocation) { //Create a Text builder call using the builder API Text helloText = new Text(builderCall, genContext); helloText.setName("HelloWorldText");
//Place this builder on the page(s) determined by the PageLocation in the //Builder Call Editor helloText.setPageLocation(pageLocation);
//Display input from DisplayText input in Builder Call Editor //Use "Hello, world", if no value is specified. helloText.setText(builderInputs.getString("DisplayText", "Hello, world"));
//Invoke the builder call helloText.invokeBuilder(); } }
Controlling Generation by Phase
Builder architecture allows you to control how, and when a Builder does its work. For example, we can alter the default Builder generation behavior by controlling what the Builder does in a specific phase of generation. For more about Controlling Builder Generation, see Multi-Phase Builder Generation Behavior.
Naming Generated Objects for High-Level Builders
When generating object names in high-level builders, the "Name" input should be used as a prefix, without any underscore. The word following this prefix should be use initial-caps. This allows generated objects to mimic the naming conventions used in Java. For example:
- ordersInputPage
- ordersGetData
Extracting Input Values Specified in the Builder Call Editor
We can retrieve the input values that the user specifies in the Builder Call Editor by calling the getString() (getXML(), getBoolean(), etc.) method on the builderInputs object passed to the doBuilderCall() method. For example,
String customerName = builderInputs.getString("CustomerName", null);
String customerAddress = builderInputs.getXml("CustomerAddress", null);
The above calls supply null as the value to use if the input value is empty. We can supply a value to use if the input value is empty with a call like the following, which supplies a new ID if the CustomerID value is null:
String customerID = builderInputs.getString("CustomerID", "1111");
Using Other Builders in the Generation Class
We can add builder calls in the Java code for your own builder in two ways:
Each way of adding a builder is equally valid. You may add some builder calls with the webApp object and use the Builder API to add other calls in the same generation class.
Using the Builder API
The Builder API allows you to create builder calls in your generation class just as you would create any other Java object. Once you create the builder object and set its properties (input values), we can call its invoke() method to add the builder call to the WebApp.
We can pass the input values set for the builder to the other builders that you call. For example, you could create add an Inserted Page builder call to the WebApp in your generation class and set its page location value to be the page location specified by the call to your builder.
Some builders such as Service Call and Web Service Enable, use dynamic inputs created by a coordinator, which makes it difficult if not impossible to use with the callable builder API. Using the callable builder API assumes that you know the name and data type for the builder inputs. As a result, these builders are not able to be added to the model by another builder's generation logic.
To add a Page builder call with the Builder API:
com.bowstreet.builders.webapp.api.Page page1 = new Page(builderCall, genContext);
page1.setName("Page1");
page1.setPageData("<html><body><form><span name=\"foo\"/></form></body></html>");
page1.invokeBuilder();
Using the webApp Object
To add a Page builder call with the webApp Object:
com.bowstreet.webapp.Page page2 = webApp.addPage("Page2");
try {
page2.addContents(XmlUtil.parseHtml("<html><body><form><span
name=\"bar\"/></form></body></html>"));
}
catch (java.io.IOException ioe) {
System.out.println("Error: " + ioe.toString());
}
catch (com.bowstreet.util.parser.ParserException pe) {
System.out.println("Error: " + pe.toString());
}