In a form process, the basic conception is a POJO which represents the whole form data. In Asta4D, we use @Form annotation to annotate a POJO as a form object which can be handled by the the form flow.

Also, there must be fields to represent the concrete data of a form, which can also be annotated by a set of form field annotations. There are several built-in form field annotations for common cases and you can implement your own form field annotation too(See Chapter 14, details of form flow for more details about form field annotation).

@Form
public class PersonForm extends Person{

    @Hidden
    public Integer getId() {
        return super.getId();
    }

    @Input
    public String getName() {
        return super.getName();
    }
    
    @Select(name = "bloodtype")
    public BloodType getBloodType() {
        return super.getBloodType();
    }

}

        

As the common pages of Asta4D, the HTML template of a form is as pure HTML too.

                                                                 

<form method="post" afd:render="form.SingleInputFormSnippet">

  <input name="name" type="text"/>

  <input name="age" type="text"/>

  <input id="sex" name="sex" type="radio"/><label for="sex">M</label>

  <select id="bloodtype" name="bloodtype">
    <option value="A">A</option>
    <option value="R" afd:clear>R</option>
  </select>

  <input id="language" name="language" type="checkbox"/><label for="language">M</label>

  <textarea name="memo"></textarea>
  
  <input type="hidden" name="id">

  <afd:embed target="/templates/form/singleInput/btns.html" />
</form>

        

As you see in the above example, there is no special declaration in the template, let us see how to declare a form POJO to handle the various form field types:

                                                                 

//@Form to tell the framework this class can be initialized from context
//extend from the entity POJO to annotate form field definitions on getters.
@Form
public class PersonForm {
    @Hidden
    private Integer id;

    @Input
    private String name;

    @Input
    private Integer age;

    @Select(name = "bloodtype")
    private BloodType bloodType;

    // the field name would be displayed as "gender" rather than the original field name "sex" in validation messages
    @Radio(nameLabel = "gender")
    private SEX sex;

    @Checkbox
    private Language[] language;

    @Textarea
    private String memo;

}

        

The details of annotations will be introduced later, just remember that there is always an annotation which can represent a certain type of form field.

Another point here is that you can always declare all the fields by your business type rather than string type, the framework will handle the value conversion correctly.

To render the form values to template, we have to declare a snippet which extends from the AbstractFormFlowSnippet. As the same as the built-in two classical handler traits, there are two corresponding snippet traits: OneStepFormSnippetTrait and ClassicalMultiStepFormFlowSnippetTrait.

Also as the same as handlers, a project common parent snippet is recommended to perform common customization.

public class SingleInputFormSnippet extends Asta4DSamplePrjCommonFormSnippet {

    /**
     * override this method to supply the option data for select, radio and checkbox.
     */
    @Override
    protected List<FormFieldPrepareRenderer> retrieveFieldPrepareRenderers(String renderTargetStep, Object form) {
        List<FormFieldPrepareRenderer> list = new LinkedList<>();

        list.add(new SelectPrepareRenderer(PersonForm.class, "bloodtype").setOptionData(BloodType.asOptionValueMap));

        list.add(new RadioPrepareRenderer(PersonForm.class, "sex").setOptionData(SEX.asOptionValueMap));

        list.add(new CheckboxPrepareRenderer(PersonForm.class, "language").setOptionData(Language.asOptionValueMap));

        return list;
    }
}

        

Developers are usually asked to override the retrieveFieldPrepareRenderers method to supply extra data for field rendering, commonly the list of option data is required.

SelectPrepareRenderer can be used to afford option list for select element, RadioPrepareRenderer and CheckboxPrepareRenderer can be used for radio and checbox input element.

Finally, do not forget to put your snippet declaration in your template file.

<form method="post" afd:render="form.SingleInputFormSnippet">
</form>

        

Basically, until now we have gotten a workable form flow implementation. There is only one thing left that is validation which will be described in the next section.

Asta4D allows any validation mechanism to be integrated and supports Bean Validation 1.1(JSR349 and JSR303) by default. We will explain how to use the built-in Bean Validation mechanism in this section. The later section will introduce how to customize the validation.

To use Bean Validation, just simply add validation annotations to your form POJO as following:

@NotBlank
@Size(max = 6)
public String getName() {
    return name;
}

public void setName(String name) {
    this.name = name;
}

@Max(45)
@NotNull
public Integer getAge() {
    return age;
}

        

More details of Bean Validation can be found at Bean Validation. We are also using Hibernate Validator as the implementation(the only existing one in the earth currently). See details at Hibernate Validator.

The validation will be invoked before the calling of method updateForm, if there is any validation error, the page will be forwarded to the step specified by "step-failed" which is usually the input page, and the validation error message will be rendered to page too. More details about validation message rendering will be introduced in later sections.

As recommended before, a project common parent class is recommended to afford a configured validator or any other customized validator implementation.

(Include about how to implement multiple input steps)

MUST do all the operations with side effect at request handler side, that is so we called isolating side effect.

NEVER do any operations with side effect at snippet side.

It is a little bit difficult to explain this rule. For a page, we assume that there are always only 2 types of pages. Let us see how we should divide our logic between the request handler and snippet.

We encourage developers to retrieve the data at the place where the data is required rather than retrieve a complicated data structure which holds all the necessary data for the whole page rendering in bulk. We make a convention that there are only 4 type of return value in our service layer(where the queries are performed exactly):

In the implementation of render methods, we always retrieve the entity instance one by one even we are rendering a list of entity (exactly we only have a list of entities' ids). For the concern about performance, see the later description of cache. However, there must be some situations that we cannot be satisfied with the performance by retrieving data in a too small granularity. We handle these cases as following steps:

In fact, the complicated data structures are rare in our system and most of our cases can be satisfied with the basic ORMAP entities.

The ParallelRowRender splits the rendering action to threads with the size of rendered list. If there are some heavy operations in the list rendering, ParallelRowRender is a good option to reduce the time of rendering.

Since we are encouraging developers to retrieve data by a small granularity, the cache is very important to the system. Especially we often retrieve entities one by one in the list rendering, the cache of entities is the most important thing for performance. As a matter of fact, we can use the cache more effective because of the small data granularity.

An frequently asked question is how to avoid duplicated query in the snippet class. That is actually an problem since we encourage the developers perform queries at the place where the data is required. We have the following options to combat this issue:

As we mentioned above, InitializableSnippet can be used to do some initialization work after the snippet instance is created. We do not recommend to perform common queries in init() method of InitializableSnippet, but the InitializableSnippet interface is still a good option for preparing a snippet instance.

The classical usage of InitializableSnippet is that we can set default value of declared @ContextData fields if some of them are set to null.

Though we can use various selectors to render data into the template file, we recommend to use css class name selector in common cases, which affords the best compatibility to the frond-end refactoring. We also made a convention which is called "x-" convention. we will always add a css class started with "x-" to the data rendering target, which tells the front-end guys try their best to keep the compatibility against the "x-" marked elements when they are refactoring the html sources.

Although we always use "x-" convention to render our data, there are still some acceptable exceptions in our practice:

Sometimes we need to do conditional rendering. For instance, we assume that there are two tabs which can be switched by different query parameter, a possible way is to create the target tab contents dynamically at snippet side as following:

public Renderer render(int id){
    Element elem = null;
    if(id == 0){
        elem = ElementUtil.ParseAsSingle("<div>" + id + "</div>");
    }else{
        elem = ElementUtil.ParseAsSingle("<div class="great">" + id + "</div>");
    }
    return Renderer.create(".x-target", elem);
}

          

Apparently there is bad smell in above example, we generate DOM element at snippet side, which makes front-end refactoring difficult. The recommended way is to write all the possible contents in template file and remove the unnecessary ones in snippet.

public Renderer render(int id){
    Renderer renderer = Renderer.create();
    //remove the clear mark
    renderer.add(".x-target-" + id, "-class", "x-clear");
    //then clear the left ones which is not necessary
    renderer.add(".x-clear", Clear);
    return renderer;
}

            

<div class="x-target-0 x-clear">0<div>
<div class="x-target-1 x-clear">1<div>

          

A "afd:extension" tag declares the relationship of inheritance between child template and parent template.

<afd:extension parent="parent.html">   

...

</afd:extension>   

      

A "afd:block" tag declares a referenceable block in the template file. Child template file can reference the blocks in parent template by the same tag "afd:block" with extra action declaration: append, insert, override.

<html>   
    <head>   
        <afd:block id="block1">   
            <link href="parent1.css" rel="stylesheet" type="text/css" />   
        </afd:block>   
           
        <afd:block id="block2">   
            <link href="parent2.css" rel="stylesheet" type="text/css" />   
        </afd:block>   
  
        <title>extension sample</title>   
    </head>   
    <body>   
        <afd:block id="content">content</afd:block>   
    </body>   
</html> 

      

<afd:extension parent="parent.html">   

    <afd:block append="block1">   
        <link href="child1.css" rel="stylesheet" type="text/css" />   
    </afd:block>   
  
    <afd:block insert="block2">   
        <link href="child2.css" rel="stylesheet" type="text/css" />   
    </afd:block>   
  
    <afd:block override="content">   
        <div>hello</div>   
    </afd:block>   
  
</afd:extension>

      

The result of merging the above two files by Asta4D's template engine can be found at Chapter 2, Flexible template.

A "afd:embed" tag declares an action of extracting and inserting an external file's content to the site where the "afd:embed" tag is declared.

<afd:extension parent="parent.html">   
  
    <afd:block override="content ">   
        <div>hello</div>   
        <afd:embed target="/templates/embed.html" ></afd:embed>   
    </afd:block>   
  
</afd:extension>  

      

In the embed target file, afd:block can also be used to append/insert/override the blocks in source template. Samples and the merging result can be found at Chapter 2, Flexible template.

A "afd:snippet" tag declares an Java class which assumes the duty of rendering data to the html snippet contained by the declaring tag.

<afd:snippet render="SimpleSnippet:setProfile">  
    <p id="name">name:<span>dummy name</span></p>  
    <p id="age">age:<span>0</span></p>  
</afd:snippet>

      

There is an alternative way to declare a snippet by "afd:render" attribute.

<div afd:render="SimpleSnippet:setProfile">  
    <p id="name">name:<span>dummy name</span></p>  
    <p id="age">age:<span>0</span></p>  
</div>

      

By the same way, "afd:paralell" and "afd:clear" can be used on arbitrary html tags which will be treated as the same as a "afd:snippet" tag. Note that "afd:paralell" will not be available except the "afd:render" is declared too, but the "afd:clear" will be always available even there is no declaration of "afd:render" on the html tag.

A "afd:group" tag declares a referenceable DOM element for back-end Java snippet class. It is useful to reference certain text without wrapping html tag or combine a group of coordinate html tags as a single node.

<p>We found <afd:group id="item-count">3</afd:group> matched items in our database.</p> 

<afd:group id="list-item">
  <div id="title">the title</div>
  <div id="content">the content</div>
</afd:group>


      

A "afd:comment" tag declares a comment block in the template files and it will be removed after rendering.

<afd:comment>This is comment</afd:comment>

<afd:comment>
  <div>This is comment too.</div>
</afd:comment>


      

A "afd:msg" tag declares a message managed in external files. This tag is mainly designed for i18n support, but it also can be used as a simple string replacer. Please see Chapter 15, i18n for more details.

<afd:msg key="search.result.count"></afd:message>

      

There are almost same two sets of overloaded methods: create and add. The create methods are static and can be used to create a Renderer instance. The add methods are instance methods and can be used to add a implicitly created Renderer instance to an existing Renderer instance. Both of the create and add methods return the created Renderer instance therefore chain invoking can be performed as well.

Renderer renderer = Renderer.create("#someId", "xyz").add("sometag", "hello");
renderer.add(".someclass", "abc").add(".someclass2", "abc2");

Renderer renderer2 = Renderer.create("#someId2", "xyz2");
Renderer renderer3 = Renderer.create("#someId3", "xyz3");

//add renderer2 and renderer3 to renderer
renderer.add(renderer2);
renderer.add(renderer3);

        

Note that the order of a Renderer instance being added is significant but the target instance which a Renderer is added to has no effect on the rendering order. In the following example, "add renderer2 to renderer then add renderer3 to renderer2" is completely equal to "add renderer2 and renderer3 to renderer" at above example.

//add renderer2 to renderer then add renderer3 to renderer2
renderer.add(renderer2);
renderer2.add(renderer3);


        

The following is equal too:

//add renderer3 to renderer2 then add renderer2 to renderer
renderer2.add(renderer3);
renderer.add(renderer2);


        

A instance of Renderer should not be considered as a single rendering declaration only, A instance of Renderer is exactly a rendering chain holder, you can call add method on any instance of the chain but the added Renderer instance will be always added to the tail of the chain. If the added Renderer instance is holding over than one Renderer instance in its own chain, the held chain will be added to the tail of the chain of the target Renderer.

There is also a non-parameter create method which can by used to create a "do nothing" Renderer for source convenience. In our practice, we write the following line at the beginning of most of our snippet methods.

Renderer renderer = Renderer.create();

        

In following sections, we will introduce add method only, but you should remember that there should be a equal create method for most cases. You can also read the Java doc of Renderer for more details.

Asta4D is using a modified version of jsoup library to afford CSS selector function. Currently, we support the following selectors:

Note: Because of the internal implementation of how to perform Renderer on target element, there may be unexpected temporary elements to be added into the Current DOM tree, which will be removed safely at the final stage of page production but may cause the structural pseudo selectors work incorrectly (However, the :root selector can still work well).

add(String selector, String value) can be used to render a text under the element specified by given selector. All child nodes of the target element specified by selector will be emptied and the given String value will be rendered as a single text node of the target element.

renderer.add("#someId", "xyz");

        

Long/long, Integer/int, Boolean/boolean will be treated as text rendering too.

renderer.add("#someIdForLong", 123L);
renderer.add("#someIdForInt", 123);
renderer.add("#someIdForBool", true);

        

add(String selector, String attr, String value) can be used to render attribute value of a DOM element. There are some rules will be applied for the pattern of specified "attr" and "value":

There is also an add method for attribution rendering that accepts arbitrary data as Object type: add(String selector, String attr, Object value). When the "value" is specified as a non-string value and the "attr" is specified as "+class" or "-class", A IllegalArgumentException will be thrown. When an arbitrary Object value is rendered to attribute by such method, an internal object reference id will be rendered to the target attribute instead of the original object since it cannot be treated as attribute string value directly. The object reference id can be used by variable injection for the nested snippet rendering. See the following example, we pass a Date instance to the nested snippet method:

<div afd:render="MySnippet:outer">
  <div id="inner" afd:render="MySnippet:inner">
    <span id="current-date"></span>
  </div>
</div>

        

public class MySnippet{

    public Renderer outer(){
        return Renderer.create("#innder", "now", new Date());
    }
    
    public Renderer inner(Date now){
        return Renderer.create("#current-date", now);
    }
}

        

This mechanism can be used for parametrized embedding too. Parameters can be specified by attribution rendering in the snippet method of parent template file and can be retrieved by the snippet method of child template file as same as the above example.

<!-- parent template -->
<div afd:render="MySnippet:outer">
  <afd:embed id="inner" target="child.html"></afd:embed>
</div>

        

<!-- child template -->
  <div afd:render="MySnippet:embed">
    <span id="current-date"></span>
  </div>

        

public class MySnippet{

    public Renderer outer(){
        return Renderer.create("#innder", "now", new Date());
    }
    
    public Renderer embed(Date now){
        return Renderer.create("#current-date", now);
    }
}

        

On all the rendering methods, if the specified value is null, the target element will be removed. And there is also an enumeration value of SpecialRenderer.Clear which can be used to declare a remove operation for an element too.

//if the String value is null, the target element will be removed
String txt = null;
Renderer.create("#someId", txt);

        

import static com.astamuse.asta4d.render.SpecialRenderer.Clear

Renderer.create("#someId", Clear);

        

Note that on the attribute rendering methods, if null value or SpecialRenderer.Clear are specified, as we mentioned in the previous section, the target attribute will be removed and the target element will remain.

An existing DOM element can be replaced by a new element by specifying the new element as the rendering value. The new element can be generated by DOM APIs or simply parsed from raw html source.

Renderer renderer = Renderer.create();

Element ul = new Element(Tag.valueOf("ul"), "");
List<Node> lis = new ArrayList<>();
ul.appendChild(new Element(Tag.valueOf("li"), "").appendText("This text is created by snippet.(1)"));
ul.appendChild(new Element(Tag.valueOf("li"), "").appendText("This text is created by snippet.(2)"));
ul.appendChild(new Element(Tag.valueOf("li"), "").appendText("This text is created by snippet.(3)"));

renderer.add("#someId", ul);

String html = "<a href=\"https://github.com/astamuse/asta4d\">asta4d hp</a>";
renderer.add("#hp-link", ElementUtil.parseAsSingle(html));


        

There are several utility methods in ElementUtil that can help you operate DOM easier.

ElementUtil#parseAsSingle would cause potential cross-site issues, so take care of it and make sure that you have escaped all the raw html source correctly. Since Asta4D has provided plenty of rendering methods, you should try your best to avoid create element from raw html source. If you have to do something on raw element level, your first option should be DOM APIs and parsing raw html source should be your last alternative.

Sometimes you will want to access the rendering target on raw element level and Asta4D allow you access the rendering target element by the interface of ElementSetter. ElementSetter asks the implementation of a callback method "set(Element elem)". As a matter of fact, the text rendering and attribute rendering are achieved by built-in implementation of ElementSetter(TextSetter and AttributeSetter).There is also another built-in ElementSetter implementation called ChildReplacer which can replace the children of rendering target by given element.

public class ChildReplacer implements ElementSetter {

    private Element newChild;

    /**
     * Constructor
     * 
     * @param newChild
     *            the new child node
     */
    public ChildReplacer(Element newChild) {
        this.newChild = newChild;
    }

    @Override
    public void set(Element elem) {
        elem.empty();
        elem.appendChild(newChild);
    }
}

        

You can regard the built-in TextSetter, AttributeSetter and ChildReplacer as reference implementation in case of you need implement your own ElementSetter. Following example shows how to use ChildReplacer or declare an anonymous class for ElementSetter on rendering.

Renderer renderer = Renderer.create();

renderer.add("#someId", new ChildReplacer(ElementUtil.parseAsSingle("<div>aaa</div>")));

renderer.add("#someNode", new ElementSetter(){
    public void set(Element elem) {
        if(elem.tagName().equals("div")){
            elem.addClass("someClass);
        }
    }
});


        

On element level, you can also parse element by Element#html(String html) method which will also cause potential cross-site issues. As same as the raw element rendering, parsing raw html source should be your last alternative.

For a snippet method, the returned Renderer will be applied to the target element which declares the current snippet method. In the returned Renderer chain, you can also specify recursive Renderer which is only applied to the element specified by given CSS selector.

Renderer.create("#someId", Renderer.create("a", "href", "https://github.com/astamuse/asta4d"));

        

Because the Renderer is applied after your snippet method finished, it is difficult to debug if there is something wrong. Asta4D affords rendering debug function too. There are two overloaded debug method, one accepts a log message only and another accepts a log message and a selector. The debug renderer will output the current status of rendering target element to log file, if the selector is not specified, the whole rendering target of current snippet method will be output, if the selector is specified, only the matched child elements will be output. Log level can be configured by "com.astamuse.asta4d.render.DebugRenderer".

//the whole target rendering target will be output before and after

renderer.addDebugger("before render value");

renderer.add("#someId", value);

renderer.addDebugger("after render value");


//only the a tag element will be output before and after

renderer.addDebugger("before render value for link", "a");

renderer.add("a", "href", url);

renderer.addDebugger("after render value for link", "a");


        

If your specified selector on rendering method cannot match any element, Asta4D will output a warning message to log as "There is no element found for selector [#someId] at [ com.astamuse.asta4d.test.render.RenderingTest$TestRender.classAttrSetting(RenderingTest.java:73) ], if it is deserved, try Renderer#disableMissingSelectorWarning() to disable this message and Renderer#enableMissingSelectorWarning could enable this warning again in your renderer chain".

Note that the place where the missing selector declared is output to log too, which is disabled by default since it is expensive on production environment. You can enable the source row number output by Configuration#setSaveCallstackInfoOnRendererCreation.

Sometimes, the missing selector may be designed by your logic, you can disable the warning message on your rendering chain temporarily as following:

renderer.disableMissingSelectorWarning();

renderer.add("#notExistsId", "abc");

renderer.enableMissingSelectorWarning();

        

Asta4D does not only allow you to rendering single value to an element, but also allow you to duplicate elements by list data, which is usually used to perform list rendering. java.lang.Iterable of String/Integer/Long/Boolean can be rendered directly as text rendering:

Renderer renderer = Renderer.create();

renderer.add("#strList", Arrays.asList("a", "b", "c"));

renderer.add("#intList", Arrays.asList(1, 2, 3));

renderer.add("#longList", Arrays.asList(1L, 2L, 3L));

renderer.add("#boolList", Arrays.asList(true, false, true));


        

On list rendering, the matched element will be duplicated times as the size of the list and the value will be rendered to each duplicated element. You can also perform complex rendering for arbitrary list data by RowConvertor:

render.add("#someIdForRenderer", Arrays.asList(123, 456, 789), new RowConvertor<Integer, Renderer>() {
    @Override
    public Renderer convert(int rowIndex, Integer obj) {
        return Renderer.create("#id", "id-" + obj).add("#otherId", "otherId-" + obj);
    }
});


        

Since we will return Renderer in most cases, the RowConvertor can be replaced by RowRenderer which can omit the type declaration of Renderer:

render.add("#someIdForRenderer", Arrays.asList(123, 456, 789), new RowRenderer<Integer>() {
    @Override
    public Renderer convert(int rowIndex, Integer obj) {
        return Renderer.create("#id", "id-" + obj).add("#otherId", "otherId-" + obj);
    }
});


        

The returned Renderer by RowConvertor/RowRenderer will be applied to each duplicated element by the given list data.

On list rendering, the rendering method accepts java.lang.Iterable rather than java.util.List, which afford more flexibilities to developers. Note that if the given iterable is empty, the target element will be duplicated 0 times, which means the target element will be removed.

Asta4D also afford parallel list rendering for you, simply use ParallelRowConvertor/ParallelRowRenderer instead of RowConvertor/RowRenderer:

render.add("#someIdForRenderer", Arrays.asList(123, 456, 789), new ParallelRowRenderer<Integer>() {
    @Override
    public Renderer convert(int rowIndex, Integer obj) {
        return Renderer.create("#id", "id-" + obj).add("#otherId", "otherId-" + obj);
    }
});


        

The parallel list rendering ability is provided by an utility class called ListConvertUtil which basically provides various transform methods for list data conversion like the map function in Scala/Java8. For Java8, lambda and stream api support will be added in future.

The ListConvertUtil uses a thread pool to perform parallel transforming, the size of pool can be configured by Configuration#listExecutorFactory#setPoolSize. There is also an import configuration of ParallelRecursivePolicy. When perform the parallel list transforming recursively, thread dead lock would potentially occur, so you have to choose a policy to handle this case:

We recommend EXCEPTION or CURRENT_THREAD and the default is EXCEPTION.

Snippet can be declared recursively.There is a convention that the outer snippet will always be executed on a prior order.

<div afd:render="OuterSnippet">
    <div id="inner" afd:render="InnerSnippet">  
        <p id="name">name:<span>dummy name</span></p>  
        <p id="age">age:<span>0</span></p>  
    </div>
</div>

      

In the above example, the "InnerSnippet" will be executed after the "OuterSnippet" has been executed, which also means you can configure the inner snippet dynamically.

public class OuterSnippet{

    public Renderer render(){
        return Renderer.create("#inner", "hasprofile", "true");
    }

}

public class InnerSnippet{

    public Renderer render(bool hasprofile){
        if(hasprofile){
            return Renderer.create("#name span", "Bob").add("#age span", 27);
        }else{
            return Renderer.create("*", Clear);
        }
    }

}

      

The snippet class instance is singleton in request scope and will be created at the first time a snippet is required. After the snippet class instance has been created, field value injection will be applied to the created instance once(About detail of value injection, see the later chapter). After all the field has been injected, the framework will check whether the current class implements the "InitializableSnippet" interface, if true, the init method of InitializableSnippet will be invoked once.

public static class InitSnippet implements InitializableSnippet {

    @ContextData
    private String value;

    private String resolvedValue;

    @Override
    public void init() throws SnippetInvokeException {
        resolvedValue = value + "-resolved";
    }
}

      

In the above example, the field "value" will be injected after the instance is created, then the init method will be applied to finish the complete initialization logic of the snippet class.

For the view first policy, we will treat the template files as first class things. The embed file mechanism allow you separate some view blocks as independent components at template file layer. There is also a snippet class level mechanism that afford you the same ability as embed file, which is called "Component".

Why we need "Component"? The embed file can only be include statically, but the "Component" is an extendible Java class which can be configured by arbitrary Java code and polymorphism can be easily performed too. Basically, The "Component" mechanism can help developer to build independent view component easier than static embed file.

The constructor of Component accepts a string value as an embed file path or an instance of Element, and also an optional AttributesRequire can be specified to provide some initialization parameters as same as the parametrized embedding introduced in the previous section.

    public Component(Element elem, AttributesRequire attrs) throws Exception {
        ...
    }

    public Component(Element elem) throws Exception {
        ...
    }

    public Component(String path, AttributesRequire attrs) throws Exception {
        ...
    }

    public Component(String path) throws Exception {
        ...
    }

      

public Renderer render(final String ctype) throws Exception {
    return Renderer.create("span", new Component("/ComponentRenderingTest_component.html", new AttributesRequire() {
        @Override
        protected void prepareAttributes() {
            this.add("value", ctype);
        }

    }));
}

      

Commonly, we do not render a component as above example, we usually extend from Component and expose a constructor with business initialization parameters or supply a group of business initialization methods, by which we can build an independent view component simply.

Further, Component also has a "toHtml" method which will return the html source of the component rendering result. This method can be used by ajax request to acquire a dynamically rendered component.

Asta4D use "Context" to manage data life cycle. The "Context" in asta4d-core supplies the basic data management mechanism and the WebApplicationContext from asta4d-web afford more powerful extending for web application development. Commonly, we will only use WebApplicationContext in our application. There are two ways to retrieve an instance of WebApplicationContext.

WebApplicationContext context = Context.getCurrentThreadContext();

      

public class PageSnippet {

    public Renderer render(WebApplicationContext context) {
        ...
    }
}

      

As the name of "getCurrentThreadContext" suggested, the context is managed per thread, and also that the context will be initialized before every http request is processed and will be cleared after every http request process has finished.

WebApplicationContext affords several methods to retrieving raw servlet apis and other helpful information:

The context provides a mechanism to manage data by scopes. There are only 3 scopes supplied by asta4d-core's Context, but the WebApplicationContext from asta4d-web supply more scopes to help web application development.

Normally, the data saved in context can be accessed by variable injection. If you need get data manually, you can do it as following:

WebApplicationContext context = Context.getCurrentThreadContext();

//from default scope
Integer count = context.get("saved-count");

//from session
Integer sessionCount = context.get(WebApplicationContext.SCOPE_SESSION, "saved-count");

      

You can implement your own customized scope or afford you customized implementation for existing scopes. You need extend from WebApplicationContext then override the method called "createMapForScope".(If you only want to split your data from default scope, you can simply specify a new scope name and a new scope will be created automatically, the created scope's life cycle is as the same as default scope)

public class MyContext extends WebApplicationContext {
    @Override
    protected ContextMap createMapForScope(String scope) {
        ContextMap map = null;
        switch (scope) {
        case SCOPE_SESSION: {
            HttpServletRequest request = getRequest();
            map = new MemcachedSessionMap(request);
        default:
            map = super.createMapForScope(scope);
        }
        return map;
    }
}

      

See later chapter of Asta4dServerlet for how to configure Asta4D to use the customized Context implementation instead of the default WebApplicationContext.

Since all the data query logic are performed at snippet class, we will want to avoid duplicated query on same page rendering. The recommended solution is caching your query result by cache library such as ehcache. But Asta4D also affords you an alternative solution for some simple cases, which is called ContextBindData.

ContextBindData can be treated as a lazy load instance field for Java class. It is warranted that a ContextBindData will be initialized only once in a same Asta4D context and it will only be initialized when you first call it. There are some exceptions for the warranty about initializing only once, we will explain them later.

public class PageSnippet {
    
    @ContextData
    private int count;

    private ContextBindData<Integer> data = new ContextBindData<Integer>(true) {
        @Override
        protected Integer buildData() {
            return count + 1;
        }

    };

    public Renderer render() {
        return Renderer.create("*", data.get());
    }
}

      

You should have noticed that we pass a "true" to the constructor of ContextBindData, which means we require the warranty that it should be only initialize once in the current context. If we pass nothing or pass a "false" to the constructor, the buildData method may be invoked multiple times in multi-thread rendering, but which is faster than warranted initialization simply because of skipping the multi-thread lock process.

Again, we recommend to use cache library to avoid duplicated query, but you can use ContextBindData as a simple, light weight alternative. See detail of Section 9.3, “The best way of implementing a snippet”.

All fields annotated by @ContextData in a snippet class will be initialized/injected automatically when the snippet class instance is initialized. Further, even the method parameters of snippet rendering method and request handle method are automatically injected, you can still customize the injection by extra @ContextData annotation.

Note that there are something different between field injection and method parameter injection. The fields of snippet class without @ContextData will not be injected, but method parameters will be always injected even without @ContextData.

There are several scope specified annotations can be used as convenience.

All the above annotation have the same configurable items with the original @ContextData annotation except being fixed with according data scope.

A pojo class annotated by @ContextDataSet will be treated as a variable holder. If the type of a snippet class field or a method parameter is a class annotated by @ContextDataSet, when Asta4D do injection, a new instance will be created at first, then all the fields of current instance will be scanned and all the fields annotated by @ContextData will be injected as same as the snippet class field injection. @ContextDataSet can be used to allocate all of the form data into one single instance as a convenience.

@ContextDataSet
public static class MySet {

    @ContextData
    private long f1;

    @ContextData
    private String f2;

    public long getF1() {
        return f1;
    }
    
    public String getF2() {
        return f2;
    }
}

public static class MySnippet {

    public void render(MySet holder) {
    }

}

public static class MySnippet2 {

    @ContextData
    private MySet holder;

    public void render() {
    }

}




      

Asta4D search data in context by pre configured ContextDataFinder implementation. The default implementation is WebApplicationContextDataFinder. You can supply your own search mechanism by implementing the ContextDataFinder interface or extending from WebApplicationContextDataFinder. WebApplicationContextDataFinder defines the scope search order if scope is not specified, and also returns some special data by hard coding type check:

The first 3 types are afforded by the parent class of WebApplicationContextDataFinder: DefaultContextDataFinder. To supply your own logic, you can override the findDataInContext method and the WebApplicationContextDataFinder's source can be treated as reference implementation.

All the url mapping rules can be supplied by implementing the UrlMappingRuleInitializer interface which can be configured by WebApplicationConfiguration#setUrlMappingRuleInitializer.

UrlMappingRuleInitializer's initUrlMappingRules method does not return configured rules directly, it supply a UrlMappingRuleHelper instance by parameter instead. The UrlMappingRuleHelper afford a group of methods to help developers build url mapping rules.

UrlMappingRuleHelper allows add new rule by add methods, which will be discussed in next section, let us see the global configuration methods of UrlMappingRuleHelper at first.

There several add methods from UrlMappingRuleHelper which can be used to add new url rules. According to the certain being called add method, different interface which is called handy rules will be returned for further declaration. Further, all the methods of the returned handy rule interface will return different interface according to the certain method you are calling, it is complex to describe which interface will be returned on certain case, basically we suppose that the code auto completion function of you editor would help you to know what you can do in the next step. All of these handy rules and their methods can be treated as a group of DSL to help you build your own url rules for your site. We will describe all the available methods at following regardless of which certain interface it belongs to. After that, we will also describe the basic rule of how the returned handy rules change.

I18nMessageHelper is an abstract classes which affords the basic interface for handling messages:

There are also two extended classes from I18nMessageHelper, which afford more flexible message functionalities especially about formatting message by given parameters. Configuration#setI18nMessageHelper can be used to customized which helper you want to use. The default is OrderedParamI18nMessageHelper. (I18nMessageHelperTypeAssistant#getConfiguredMappedHelper and I18nMessageHelperTypeAssistant#getConfiguredOrderedHelper can be used to retrieve a type safe configured helper.)

There are several value formatter can be used by the above helpers. Notice that The MappedParamI18nMessageHelper requires implementation of MappedValueFormatter and the OrderedParamI18nMessageHelper requires implementation of OrderedValueFormatter.

The I18nMessageHelper requires a MessagePatternRetriever implementation to retrieve message by key. There is a default implementation JDKResourceBundleMessagePatternRetriever which uses the JDK's built-in resource bundle mechanism. The base name of resource bundle files can be specified by JDKResourceBundleMessagePatternRetriever#setResourceNames which accepts a list of base name. The configured resource bundles will be passed to JDK's ResourceBundle#getBundle(String baseName, Locale locale, ClassLoader loader) to retrieve messages.

As the implementation of JDKResourceBundleMessagePatternRetriever, if the given locale is null, the default locale decision mechanism will be performed. See Section 15.1.3, “Default locale”.

Further, the JDKResourceBundleMessagePatternRetriever accepts ResourceBundleFactory to allow customize how to retrieve a resource bundle. The default is CharsetResourceBundleFactory which allows specify the encoding of message bundle files. Another built-in implementation is the LatinEscapingResourceBundleFactory, as the name suggests, the message files must be escaped by JDK's standard mechanism(via native2ascii).

The default locale will be decided by the following order and stop at the first non-null returned value.

Since the Locale.getDefault() will return the local machine's locale by default, you may need to override the default locale to ROOT at the staring of your web application.

"afd:msg" tag can be used to declare an i18n aware message in a template file. The basic usage is as following:

<section>
    <article>
        <div class="panel panel-default"><div class="panel-body">
            <!-- the inner html will be treated as default message if the key is not found in message bundle -->
            <afd:msg id="notexistingkey" key="sample.notexistingkey" p0="parameter works as well.">text here to be treated as default message.{0}</afd:msg><br/>
        </div></div>
        
        <div class="panel panel-default"><div class="panel-body">
            <!-- simply specify parameters on tag -->
            <afd:msg id="peoplecount" key="sample.peoplecount" p0="4">dummy text</afd:msg><br/>
            <afd:msg id="peoplecount" key="sample.peoplecount" p0="7" locale="ja_JP">dummy text</afd:msg><br/>
        </div></div>
        
        <div class="panel panel-default"><div class="panel-body">
            <!-- the parameter can be rendered by snippet too -->
            <afd:snippet render="ComplicatedSnippet:setMsgParam">
                <afd:msg id="peoplecount" key="sample.peoplecount" p0="4">dummy text</afd:msg><br/>
                <afd:msg id="peoplecount" key="sample.peoplecount" p0="7" locale="ja_JP">dummy text</afd:msg><br/>
            </afd:snippet>
        </div></div>
        
        <div class="panel panel-default"><div class="panel-body">
            <!-- attribute started with "@" will be treated as a key -->
            <afd:msg id="weatherreport" key="sample.weatherreport" @p0="sample.weatherreport.sunny">天気</afd:msg><br/>
            <afd:msg id="weatherreport" key="sample.weatherreport" @p0="sample.weatherreport.sunny" locale="ja_JP">天気</afd:msg><br/>
        </div></div>
        
        <div class="panel panel-default"><div class="panel-body">
            <!-- attribute started with "#" will be treated as a sub key of current key, thus sample.weatherreport.sunny will be searched -->
            <afd:msg id="weatherreport" key="sample.weatherreport" #p0="rain">天気</afd:msg><br/>
            <afd:msg id="weatherreport" key="sample.weatherreport" #p0="rain" locale="ja_JP">天気</afd:msg><br/>
        </div></div>
        
        <div class="panel panel-default"><div class="panel-body">
            <!-- treat message as text -->
            <afd:msg key="sample.textUrl"></afd:msg><br/>
            
            <!-- treat message as html -->
            <afd:msg key="sample.htmlUrl"></afd:msg><br/>
            
            <!-- treat message as text even it begins with html: -->
            <afd:msg key="sample.escapedUrl"></afd:msg><br/>
        </div></div>
    </article>
</section>

      

public Renderer setMsgParam() {
    Renderer render = Renderer.create();
    render.add("#peoplecount", "p0", 15);
    return render;
}

    

There are something need to be explained: