Getting Started

Because an exemple is so much more usefull than a big explanation, here comes a typical simple WebJS page.

The following displays all blog entries with an edit link.

Java controler [Blog.java]

@WebPage(path="blog.html", page="template/blog.html", script="js/blog-server.js")
public class Blog {
        
        @WebPart
        @Default
        public void displayBlogEntries(Request request, Bindings bindings) throws WebException {
                bindings.addProperty("blogEntries", BlogService.getInstance(request).getBlogEntries());
        }
        
        @WebPart
        @Selector("#edit")
        public void displayEditForm(Request request, Bindings bindings) throws WebException {
                String id = request.get("id");
                bindings.addProperty("editBlogEntry", BlogService.getInstance(request).getBlogEntry(Integer.valueOf(id)));
        }
}

HTML Template [blog.html]

<html>
        <head>
                <script src="js/blog-client.js" type="text/javascript" />
        </head>
        <body>
                <div id="content">
                        <div class="blog">
                                <div class="blog-entry">
                                        <div class="blog-entry-actions">
                                                <a class="blog-entry-edit" href="#">Edit</a>
                                        </div>
                                        <div class="blog-entry-content">
                                                <div class="blog-entry-title"/>
                                                <div class="blog-entry-text"/>
                                        </div>
                                        <hr/>
                                </div>
                        </div>
                        <form id="edit" style="display: none;">
                                <div class="edit-form">
                                        <div class="edit-content">
                                                <input type="hidden" name="entry-id" />
                                                <label for="entry-title">Title</label>
                                                <div><input type="text" name="entry-title" /></div>
                                                <label for="entry-text">Text</label>
                                                <div><textarea name="entry-text"></textarea></div>
                                        </div>
                                        <div class="edit-actions">
                                                <button id="edit-ok" type="button">OK</button>
                                                <button id="edit-cancel" type="button">Cancel</button>
                                        </div>
                                </div>
                        </form>
                </div>
        </body>
</html>

Server-side JS [blog-server.js]

// Fills the blog entries using a template (if needed)
WebJS.checkBindings(["blogEntries"], function(){
        $(".blog-entry").template(blogEntries.toArray(), function(entry, index) {
                this.appendTo(".blog");
                this.attr("id", "blog-entry-"+entry.id);
                this.attr("data-pk", entry.id);
                this.find(".blog-entry-title").text(entry.title);
                this.find(".blog-entry-text").text(entry.text);
        });
});

// Fills the edit form (if needed)
WebJS.checkBindings(["editBlogEntry"], function(){
        $("#edit input[name=entry-id]").val(editBlogEntry.id);
        $("#edit input[name=entry-title]").val(editBlogEntry.title);
        $("#edit textarea[name=entry-text]").val(editBlogEntry.text);
});

Client-side JS [blog-client.js]

$(function(){

        // On edit click, we execute the displayEditForm and unhide the div
        $(".blog-entry-edit").click(function(event){
                var pk = $(this).parents(".blog-entry").attr("data-pk");
                WebJS.executeWebPart("displayEditForm", {id: pk}, function() {
                        $("#edit").css("display", "block");
                });
                return false;
        });
});

Explanation

WebJS basic principles

When it receives an HTTP request, WebJS works in 4 simple steps :

  1. Find the corresponding @WebPage class using the path attribute
  2. Execute the asked @WebPart method (if not precised, the @Default one)
  3. Execute the server-side JavaScript corresponding to the script attribute of the @WebPage annotation. The execution context is the web page corresponding to the page attribute.
  4. Filter the HTML result user the web part @Selector annotation using jQuery.

Application to our example

If we apply this to just putting http://localhost:8080/<YourWAR>/webjs/blog.html in your browser URL bar :

  1. It corresponds to the Blog class.
  2. No parameter is given so displayBlogEntries method will be used. So blogEntries binding property will be filled.
  3. Our server-side JavaScript is executed with our HTML template to fill the #blog div with entries from blogEntries binding variable. (search WebJS.checkBindings for more informations about its use)
  4. The HTML result is fully sent because no selector is given to the @WebPart

Application to an Ajax request

On the client side, every Edit link is bound to a WebJS.executeWebPart call. This is an Ajax request to a specific @WebPart by its method name. So, if we apply the WebJS rules to this Ajax request, it gives :

  1. It corresponds to the Blog class, because path is identical to the original web page.
  2. displayEditForm is called because this @WebPart is asked. So, the blog entry corresponding to the given id is bound to the editBlogEntry bind variable.
  3. Our server-side JavaScript is executed with our HTML template to fill the #edit form with entry from editBlogEntry binding variable.
  4. Only #edit is sent back according to the @WebPart @Selector annotation. So #edit will be updated on the browser and will be displayed by the callback (line 7).

What's next ?

Now that you have WebJS basic principles in mind, you can go to the Sample Project section to go forward with this blog example.

Or simply read the Documentation.