Customizing BrowserField2 Advanced Components

Marcilio Mendonca

DEV49

September 29, 2010

Session Surveys

• Remember to complete your breakout session evaluation in one of two ways:

– On your BlackBerry® smartphone – use the DEVCON 2010 mobile guide, from Pyxis

– Login to My Scheduler at one of the Cyber Zone locations or on your PC

Why should Icare about

BrowserField2?

I seem to be happy with

BrowserField1 ...

What’s the Point?

Source Code Snippet from a Real BrowserField1 Application

// Dealing with Low Level ComponentsrenderingSession = RenderingSession.getNewInstance();renderingSession.getRenderingOptions().setProperty(...)...browserContent = renderingSession.getBrowserContent(…)browserContent.finishLoading();

// Managing ThreadsPrimaryResourceFetchThread thread = new PrimaryResourceFetchThread();...// Managing Resource ConnectivityHttpConnection connection = Utilities.makeConnection(url, head, null);...// Managing HTTP Cookies_cookieManager.storeCookies(cookie, urlHost);...// Managing Page HistorygetHistoryPosition(BrowserContent browserField);...// Others: handling HTTP redirects, errors, UI issues

Source Code Snippet from a Real BrowserField1 Application

// Dealing with Low Level ComponentsrenderingSession = RenderingSession.getNewInstance();renderingSession.getRenderingOptions().setProperty(...)...browserContent = renderingSession.getBrowserContent(…)browserContent.finishLoading();

// Managing ThreadsPrimaryResourceFetchThread thread = new PrimaryResourceFetchThread();...// Managing Resource ConnectivityHttpConnection connection = Utilities.makeConnection(url, head, null);...// Managing HTTP Cookies_cookieManager.storeCookies(cookie, urlHost);...// Managing Page HistorygetHistoryPosition(BrowserContent browserField);...// Others: handling HTTP redirects, errors, UI issues

Low Productivity!

- 1,279 lines of code- Too much focus on low-level “stuff”

BrowserField1 Application Rewritten as a BrowserField2 Application

...Screen screen = new MainScreen();

// Manage the Specifics of Your BrowserFieldBrowserFieldConfig config = new BrowserFieldConfig();

// Create the BrowserFieldBrowserField browserField = new BrowserField(config);

// Request Web Content and Show it on the Screenscreen.add(browserField);Application.getApplication().pushScreen(screen);browserField.requestContent(“http://www.blackberry.com”);...

BrowserField1 Application Rewritten as a BrowserField2 Application

...Screen screen = new MainScreen();

// Manage the Specifics of Your BrowserFieldBrowserFieldConfig config = new BrowserFieldConfig();

// Create the BrowserFieldBrowserField browserField = new BrowserField(config);

// Request Web Content and Show it on the Screenscreen.add(browserField);Application.getApplication().pushScreen(screen);browserField.requestContent(“http://www.blackberry.com”);...

HIGH Productivity!

- 30 lines of code- Focus on what matters: Your business!

BrowserField2I can easily customize it!

BrowserField1

Make Up Your Mind!

Agenda

1. Quick Overview of BrowserField2 API

2. Our Demo: BF2CUSTOM

3. Customizing BrowserField2 Advanced Components– BrowserFieldController

– BrowserFieldConnectionManager

– BrowserFieldErrorHandler

– BrowserField Debug API

4. BrowserField2 in BlackBerry OS 6.0

5. Summary

Goal of This Presentation

To illustrate how advanced BrowserField2 components can be

customized to suit a variety of reported BF2 developer’s needs

Quick Overview of BrowserField2

BrowserField 1 API- RenderingApplication- RenderingSession- BrowserContent

BrowserField 2 API

• The BrowserField 2 API (a.k.a. BF2) is a Public API release along with BlackBerry OS 5.0 that allows a developer to embed Web content into a BlackBerry Java application

• Advantages of BF2 over BF1: high productivity, strong integration with the Javascriptengine, built-in functionality (e.g., connectivity, cookie management, navigation history)

BF2CUSTOM – OUR DEMOA BrowserField2 application that illustrates how to

customize BF2 advanced components

BF2CUSTOM

BF2CUSTOM – App Entry Point

// BF2 customization applicationpublic class BF2Custom extends UiApplication{

/*** Application Entry point*/ public static void main(String[] args) {

BF2Custom theApp = new BF2Custom(); theApp.enterEventDispatcher();

}

/*** Creates a new BF2Custon object*/public BF2Custom() {

// Push a screen onto the UI stack for rendering.pushScreen(new BF2CustomScreen());

} }

BF2CUSTOM – BF2CustomScreen

// BF2 customization application screenfinal class BF2CustomScreen extends MainScreen {

BrowserField _browserField;

public BF2CustomScreen() {// Create the BrowserField_browserField = createBrowserField();

// Our Customizations will go here...

}

public void createBrowserField(){BrowserFieldConfig config = new BrowserFieldConfig();config.setProperty(...);return new BrowserField(config);

}// a couple of inner classes for customization go here

}

What’s Being Covered?

BF2CUSTOM DEMO

BrowserFieldController- Overview- Extending the Default Controller- Creating a New Resource Handler

BrowserFieldConnectionManager- Overview - Specifying a New ConnectionFactory

BrowserFieldErrorHandler- Overview- Customizing Error Handling Display

BrowserFieldDebugger- Overview- On-Device Debugger Sample- Desktop Debugger Sample

BrowserFieldControllerHandling navigation and resource requests

BrowserFieldControllerHandling Navigation and Resource Requests

BrowserFieldController

BrowserField

Your BF2 Application

requestContent(“www.blackberry.com”)

handleNavigationRequest()

<<default implementation>>

ProtocolController

Navigation Request = Page Request (e.g., html)Resource Request = Page Resource Request (e.g., image, css, js)

YourBrowserFieldControler

either one

ProtocolControllerExtending the Default Controller

• Requirement: BF2CUSTOM must enforce that only domains authorized by the user can be accessed• Solution: Extend ProtocolController and check if domain is accessible; if not, ask user to authorize or decline access

User has Authorized

ProtocolControllerExtending the Default Controller

class MyProtocolController extends ProtocolController {

// Navigation Requestspublic void handleNavigationRequest(BrowserFieldRequest request) { boolean accessGrantedByUser = true;String domain = URI.create(request.getURL()).getHost();if ( !trustedDomains.contains(domain) && userHasAuthorizedAccess(domain) ){

trustedDomains.addElement(domain); } else { accessGrantedByUser = false; }if ( accessGrantedByUser ) {

super.handleNavigationRequest(request);}

}// Resource Requestspublic InputConnection handleResourceRequest(BrowserFieldRequest request) {...

}}// Attach new controller to the BrowserFieldProtocolController myController = new MyProtocolController(browserField);browserField.getConfig().setProperty(

BrowserFieldConfig.CONTROLLER, myController);

ProtocolControllerUsing Handlers to Address Different Protocols

BrowserFieldController

<<default implementation>>

ProtocolController

TransportResourceHandler

DeviceResourceHandler

ModuleResourceHandler

http, https

file, data

local

your protocol

YourHandler- handleNavigation()- handleResource()

BrowserFieldNavigationRequestHandler

BrowserFieldResourceRequestHandler

BrowserFieldResourceHandler- handleNavigation()- handleResource()

ProtocolControllerCreating a New Request Handler

• Requirement: BF2CUSTOM must handle the “shared:///” protocol to load resources from a “shared space”

• Solution: Create a New Navigation/Resource Request Handler

<html><head><title>BF2Custom</title></head><body><img src=“http://www.rim.com/img1.jpg”/><img src=“shared:///img2.jpg”/><a href=“shared:///bf2custom_index.html”>Click here</a>

</body></html>

ProtocolControllerCreating a New Request Handler

class SharedResourcesHandler implements BrowserFieldNavigationRequestHandler, BrowserFieldResourceRequestHandler {

public void handleNavigation(BrowserFieldRequest request) {InputConnection connection = handleResource(request);if ( connection != null ) {

browserField.displayContent(connection, "shared:///");}

}

public InputConnection handleResource(BrowserFieldRequest request) { return getInputConnectionForSharedSpace(request);

}

public InputConnection getInputConnectionForSharedSpace(request) { ... // Helper method

}}

// Attach the handler to your controllerSharedResourcesHandler handler = new SharedResourcesHandler(browserField);myController.setNavigationRequestHandler("shared", handler);myController.setResourceRequestHandler("shared", handler);

BrowserFieldControllerOther Possible Customization Scenarios

Cases where customizing the BrowserFieldController might be worth it:

• Controlling access to resources• Supporting new resource location protocols • Http basic authentication (401)• Caching• Logging & statistics

BrowserFieldConnectionManagerConnecting to network resources

BrowserFieldConnectionManagerConnecting to Resources via HTTP(S)

BrowserFieldConnectionManagerDefaultBrowserFieldConnectionManager

BrowserFieldControllerProtocolController/TransportResourceHandler 1. http://www.blackberry.com/bbtorch.png

2. makeRequest()

Internet

3. Connects to the resourcevia WIFI, BIS, MDS, cellular, …

4. InputConnection

BrowserFieldConnectionManagerConnecting to Resources via HTTP(S)

BrowserFieldConnectionManager- InputConnection makeRequest(BrowserFieldRequest request)

<<default controller>>

ProtocolController

TransportResourceHandlerhttp, https

<<net.rim.device.api.io.transport>>

ConnectionFactory- setTimeLimit()- setAttemptsLimit()- setPreferredTransportTypes()- setDisallowedTransportTypes()

WIFI, MDS, BIS, TCP_CELLULAR, …

<<net.rim.device.api.io.transport>>

(Your)ConnectionFactory

BIS, WIFI,TCP_CELLULAR, MDS…

cookies, debugger

YourBrowserFieldConnectionManager- InputConnection makeRequest(BrowserFieldRequest request)

cookies, debugger

<<internal default implementation>>

DefaultBrowserFieldConnectionManager

BrowserFieldConnectionManagerSpecifying Your Own ConnectionFactory

• Requirement: BF2CUSTOM needs to enforce a particular connection order, disallow certain types of connections and specify timeout values

• Solution: Create a ConnectionFactory and attach it to your BrowserField

// Create the factorypublic ConnectionFactory createCustomConnectionFactory() {

ConnectionFactory factory = new ConnectionFactory();// Set timeout parametersfactory.setAttemptsLimit(1);factory.setTimeLimit(5000);factory.setTimeoutSupported(true);// Specify the order of connectionsfactory.setPreferredTransportTypes( new int[] {

TransportInfo.TRANSPORT_TCP_WIFI, TransportInfo.TRANSPORT_BIS_B, TransportInfo.TRANSPORT_MDS, TransportInfo.TRANSPORT_WAP} );

// Disallow cellular connectionsfactory.setDisallowedTransportTypes( new int[]

{TransportInfo.TRANSPORT_TCP_CELLULAR} );}// Attach the factory to the BrowserFieldConnectionFactory factory = createCustomConnectionFactory();browserField.getConfig().setProperty(

BrowserFieldConfig.CONNECTION_FACTORY,factory);

BrowserFieldErrorHandlerHandling BrowserField2 unexpected situations

BrowserFieldErrorHandlerHandling BrowserField2 Unexpected Situations

BrowserFieldErrorHandler- displayContentError()- requestContentError()- resourceRequestError()- navigationRequestError()

Uses BrowserField to display errors

YourBrowserFieldErrorHandler- displayContentError()- requestContentError()- resourceRequestError()- navigationRequestError

(E.g., uses a Dialog to display errors)

BrowserField

BrowserFieldErrorHandlerCustomizing BrowserField Error Handling

• Requirement: BF2CUSTOM needs to use a Dialog to notify users about BrowserField errors and to additionally save errors in a log file

• Solution: Extend BrowserFieldErrorHandler and attach it to your BrowserField

// Create the ErrorHandler classpublic class MyBrowserFieldErrorHandler extends BrowserFieldErrorHandler {public void displayContentError(String url, String errorMessage) {String error = "Error: (url=" + url + "): " + t.getMessage();Dialog.ask(Dialog.D_OK, error);logMessage(“BrowserFieldError: “ + error );

}public void displayContentError(String url, InputConnection connection, Throwable t) { displayContentError(url, t.getMessage());

}public void requestContentError(BrowserFieldRequest request, Throwable t){displayContentError(request.getURL(), t.getMessage());

}}// Attach the Error Handler to the BrowserFieldBrowserFieldErrorHandler eHandler = new MyBrowserFieldErrorHandler();browserField.getConfig().setProperty(BrowserFieldConfig.ERROR_HANDLER,eHandler);

THE BrowserField2 DEBUG APIDebugging JavaScript in BrowserField2

The BrowserField Debug APIDebugging BrowserField Scripts

BrowserFieldScript- getName()- getSourceLines()- setBreakpoint()- clearBreakpoint()

BrowserField

YourBrowserFieldDebugger- hitBreakpoint()- handleStep()- registerScript()- reportException()- notifyCompileError()- xmlHttpRequestRequest()BrowserFieldScriptObject

- getField()- enumerateFields()- getObjectClass()

BrowserFieldDebugContext- resume()- stepInto()- eval()- getFunctionName()- getLineNumber()

net.rim.device.api.browser.field2.debug

BrowserFieldDebugger

The BrowserField Debug APIImplementing Your Own Debugger

public class MYBrowserFieldDebugger extends BrowserFieldDebugger {public void registerScript(BrowserFieldScript script) {

_scripts.add(script)}public void registerInlineScript(BrowserFieldScript script) {

_inlineScripts.add(script)}public void hitBreakpoint( BrowserFieldDebugContext context ) {

_currentContext = context;ScriptResource resource = findScriptResource( context );ScriptResourceScreen screen = new ScriptResourceScreen(resource);screen.setActive( context.getLineNumber() );screen.display( _contentScreen );

}public void stepOver() {

_currentContext.stepOver();}public Object eval(String expression) {

return _currentContext.eval(expression);}

}

// Attach the Debugger to the BrowserFieldbrowserField.setDebugger(new MyBrowserFieldDebugger());

The BrowserField Debug APIOn-Device BrowserField Debugger Application

The BrowserField Debug APIDesktop BrowserField Debugger Application

BrowserField

BrowserField2 IN BLACKBERRY OS 6.0What’s new?

BrowserField2 in BlackBerry OS 6.0What’s New?

• High-quality HTML rendering backed up by Webkit– 10x faster layout time, strong support for HTML5, 100% acid3

• Improved touch screen experience – pinch to zoom, text reflow

• State-of-the-Art Javascript Engine – 3.2x faster, more reliable

• The API’s interface did not change except for discontinuing the Debug API

Webkit

BlackBerryBrowser

BrowserFieldApplication

Curious About Upcoming Debug Capabilities?

• Please refer to session DEV37 – Your Best Options for Web Development Tools

Summary

1. Quick Overview of BrowserField2 API

2. Our Demo: BF2CUSTOM– Customizing advanced BF2 components

3. Customizing BrowserField2 Advanced Components– BrowserFieldController

– BrowserFieldConnectionManager

– BrowserFieldErrorHandler

– BrowserField Debug API

4. BrowserField2 in BlackBerry OS 6.0– High-quality HTML rendering, improved touch screen, state-of-the-

art Javascript Engine, same API but Debug API was discontinued

Switch Now to BrowserField2and raise your

(and your team's) Productivity

to a new level!

Final Message

For More Information

• Other sessions– DEV08: Creating Hybrid Applications – Building Web

Applications Using Java Components

– DEV37: Your Best Options for Web Development Tools

• BlackBerry DevZone website:– http://www.blackberry.com/developers

– Download BlackBerry development tools and simulators

– Developer Resource Center

– Web Community Forum

• Development community:– Developers Blog: http://devblog.blackberry.com

– Twitter: http://twitter.com/BlackBerryDev

Thank You

Marcilio Mendonca

DEV49

September 29, 2010