How to...

1 Start a new buffalo project}

Please follow the tutorial to create a new application, or download the binary distribution and copy to have a skeleton.

2 Add buffalo feature to existing project

If you want to use the web remoting feature, just copy the buffalo-version.jar (and commons-logging.jar if not supplied) and buffalo.js. Please refer other documents using buffalo. If you need buffalo delegate you page flow, please split the page as the demo application. Please not miss the best practice to see if your application suitable for OPOA.

3 Upgrade from former versions

To uprage is quite easy.

If you upgrade from version 1.1:

  • remove the burlap*.jar, replace with buffalo-version.jar
  • replace the buffalo.js with the lastest version
  • remove the endpoint servlet definition in spring. we need only one servlet now
  • Change the code:
    • JavaScript: endpoint change to "yourappname/bfapp";
    • Server: No need to change

If you upgrade from version 1.2.x:

  • remove the burlap*.jar, replace with buffalo-version.jar
  • replace the buffalo.js with the lastest version
  • If possible, change the java code which is inherited from BuffaloService. Replace the corrosponding method to RequestContext.getContext().getXXX. We still have backward compatibility anyway.
  • that's it.

4 Integrated with Spring

To integrated with Spring is quite simple. First you need to make sure spring can be loaded successfully (using config servlet or context listener). Please refer Spring related documents for further infomation. After that, add a config bean into any of the spring configruation files like below:

<bean name="buffaloConfigBean" class="net.buffalo.service.BuffaloServiceConfigurer">
    <property name="services">
        <entry key="testSpringService1"><ref bean="yourBeanId"/></entry>
        <!-- oterh entries... -->

That's it. When the application is started, buffalo will find this bean and load all services defined in the services property. There is no difference between the service comes from and spring. buffalo client cook them the same way. :)

5 Serializing a form on web page to an object

There is a Buffalo.Form.formToBean method from buffalo version 1.2.1, which can serialize a form to an object directly. You can see the Form demo in the demo application. Here we have a simple example showing how we transform a form to a net.buffalo.demo.form.User object.

var userObj = Buffalo.Form.formToBean("form1", "net.buffalo.demo.form.User");
buffalo.remoteCall("userService.createUser", [userObj], function(reply){

The serializing principal:

  • For simple fields like text, password, radio, select-one, will add a fieldName=fieldValue property to the object.
  • For select-many, checkbox, will add a fieldName=ListString to the object.

6 Customize events

Buffalo support customized event when doing remoting call:

EventDescriptionParameterDefault Impl
onLoadingwhen loading a requesttrue or falsea buffalo loading div will appear on top right of the screen
onFinishedwhen finished the requestnothingempty function
onErrorwhen there is an error (normally is 500 or 404 error)xmlhttp objecta red div will displayed
onExceptionwhen invoking a service, throws exceptionBuffalo.Fault objecta yellow div will displayed
onTimeoutwhen timeout, default is 10 secondsnothingalert("timeout")

If you want to customize the events, You can

var buffalo = new Buffalo(endpoint, async, {onLoading: yourLoadingFunction, onError: yourErrorHanlder ...})

Or["onLoading"] = function(state) {
        if (state) { //displaying message

7 Data binding

Buffalo support on way binding, which is, bind the javascript object value to html elements.

buffalo.bindReply(service, params, elementId)

Above code will try to make a remote call, and bind the reply result to the element directly. Or you can try Buffalo.Bind.bind(elementId, bindValue).

8 Browser forward/back

You need the buffalo-blank.html to enable this feature. The download binary contains this file.

<iframe src="buffalo-blank.html" 
id="buffalo-view-history-iframe" width="0" height="0" 

When you want to swtich the view, use buffalo.switchView(viewName), buffalo will remember the history automatically. If you don't need this feature for some specified view, use buffalo.switchPart(...) to exculde. Please reade the JavaScript API for more.

9 Access/Update Session/Cookie/ServletContext

From 2.0, You can get/set the session/cookie/context value very conveniently. Use the class RequestContext, you can have full control of those lifecycle values in a easier way.

// Get a thread-safe request context
context = net.buffalo.request.RequestContext.getContext();

// Get session value
Map session = context.getSession();
String username = (String)session.get("username");
// Update the session value, will refresh the session immediately
session.put("username", "newUsername");

// cookie
Map cookieMap = context.getCookie();
Cookie cookie = cookieMap.get("cookieName");
// update cookie
Cookie c = new Cookie("name", "value");
cookieMap.put(c.getName(), c);

// ServletContext
Map application = context.getApplication();
Object value = application.get("key");