TweetFollow Us on Twitter

Nov 01 Adv WebObjects

Volume Number: 17 (2001)
Issue Number: 11
Column Tag: Advanced WebObjects

Part 3 - Cool Programming Tricks

by Emmanuel Proulx

Neat things you can do with WebObjects.

Redirecting

You already know that, in order to jump from a Web Component to another one, the syntax is simply:

WOComponent anAction() {
  return pageWithName("ComponentName");
}

But what if the page you want to jump to is external to the application? One way of statically jumping to an external page is to hardcode the URL in a static hyperlink on the page. But sometimes you need to process the request before you jump to that external page. How can you do that?

WebObjects has a utility class called WORedirect, which produces a "redirection page". This page will have the browser jump to that external URL. You can invoke WORedirect it by using the following syntax:

WOComponent anExternalAction() {
  //Compute this request...
  WORedirect r = (WORedirect)pageWithName("WORedirect");
  r.setURL("/phonypage?param=" 
           + resultOfRequest);
  return r;
}

Controlling Backtracking (Back Button)

Backtracking (clicking on the "back" button of the browser) can cause big problems, in all Web applications. The problem may arise when:

  • the user is in a first page, the system being in a certain state A
  • the user clicks on something to go to the second page, setting the system to a new state B
  • the user clicks on "back" to see the first page, thinking the state of the system is A again - but the system is still in state B! Any number of things can go wrong now.

As an example, the user might choose to see the records for Monday (state A), then click on a hyperlink marked "Tuesday". The page reloads with the new set of records for Tuesday (state B). The user then backtracks to the previous page, and decides to click button "clean" that deletes all records for the current day. The user thinks he just erased the records for Monday, but in fact he/she erased the records for Tuesday.

This can be a big problem. It is well known by the Web developers, that handle the problem in specific ways:

You can fix the problem by forcing the previous pages to reload every time the user accesses them. You do that by calling the function setPageRefreshOnBacktrackEnabled() from the Application object's constructor. This is implemented in WebObjects by setting an "already expired" expiry date of all produced pages. This solution is pretty good, but not sufficient, because WebObjects caches the pages that are produced. When a user uses the back button to an expired page, WebObjects returns the pages as it was generated previously.

You can also turn off page caching, by calling another function from the Application object: setPageCacheSize(). How does this work? By default, WebObjects keeps the 30 last pages in memory, and returns them to the browsers that ask for them. Setting the cache size to 1 prevents the user from receiving cached pages (except the current one).

Here's an example:

public Application() {
  setPageRefreshOnBacktrackEnabled(true);
  setPageCacheSize(1); //keep only the current page
  //...
}

You can also prevent the user from re-accessing your application after leaving it. The user can still browser back and forth in the system's pages, but not after exiting. This usually involves an "Exit" or "logoff" button or hyperlink, linked to an action like:

public WOComponent exitAction() { 
  WORedirect r = (WORedirect)pageWithName("WORedirect");
  r.setURL("http://www.mactech.com");

  session().terminate();

  return r;
}

You still need to call setPageRefreshOnBacktrackEnabled(true) in the Application object's constructor to force page reload, or else the user will be able to see the old defunct pages that have no associated session, instead of an honest error message saying "session timed out".

Web Components Communication

There's a number of ways pages of the same system can communicate among each other. Let's overview the different ways.

Global Variables

The different pages can share global information by setting variables inside the Application or Session objects.

Imagine a "Login" page and a "User Information" page. These would share a piece of data called the "userID". You would make an instance variable called "userID" in the Session object, like this:

public class Session extends WOSession {
  //...
  protected String userID;
  public String userID() { return userID; }
  public void setUserID(String newID) { userID = newID; }
  //...
}

Then you would set the userID in an action in the Login page:

protected String userIDField;

public WOComponent doLogin() {
  //Verify username and password
  Session s = (Session)session();
  s.setUserID(userIDField);

  UserInformation ui = (UserInformation)pageWithName("UserInformation");
  return ui;

}

Finally, you would use this information from somewhere within the User Information page:

public UserInformation () { //constructor
  Session s = (Session)session();
  actUponUser(s.userID());
}

This is simple, but can lead to potential problems. All modules from within the system have access to the global variables, and may change them, yielding possibly bad results. This may or may not be appropriate - it's up to you to decide.

Local Variables

You can send information to another page by setting a local variable instead of a global one. Let's use the same example. This time there's no Session or Application involved; the communication would happen directly. You would send the userID to the User Information page like this:

protected String username;

public WOComponent doLogin() {
  //Verify username and password

  UserInformation ui = (UserInformation)
    pageWithName("UserInformation");
  ui.setUserID(username);
  return ui;
}

You need a variable to receive the userID in the User Information page, in order to use it:

protected String userID;
public String userID() { return userID; }
public void setUserID(String newID) { userID = newID; }

public UserInformation () { //constructor
  actUponUser(userID());
}

Interface Variables

Custom Components are meant to be "black boxes"; you can use them but you don't know how they are built from the inside. In theory, you could buy libraries of components, and you don't have to have the source code in order to use them. But sometimes you need to communicate with them to let them know how they should behave. How can you do that without opening the .java file and looking at the source code? To work around this problem, we use an "interface"; a description of their publicly available members. The interface shows up in the WebObjects Builder while editing the parent component, by selecting the sub-component and opening the Inspector.

NOTE: Go to any project folder and take a look at the available files. Notice these files with the extension ".api". These files hold the interfaces for your Web Components.

The tool used for managing the interface is the API Editor. It is available in the WebObjects Builder, by clicking on the toolbar button .

Open any component and click on this button. This dialog is API Editor window:

Here's the list of things you can do in this window:

You can expose your component's variables. You do that by clicking on the button in the upper-right corner, and choosing "Add binding". You then enter the name of your variable. For each variable, you can then specify restrictions (a failure to obey these restrictions in the parent component will trigger an error message when displaying the component):

  • Required: is it mandatory to link this attribute to a value?
  • Will Set: must the attribute be linked to a variable of the parent component? (As opposed to a constant value.)
  • Value Set: specifies the type of data that can be sent to the variable. The choices are shown here:

The button "Add Keys From Class" lets you share all variables of the current component at once. This is a big time saver. I usually click on this first, and then remove the unwanted variables.

The Validation tab lets you describe a "validation scheme", a more complex restriction strategy than the one in the Bindings tab. If the user of the component fails to link the attributes to values that follow the validation condition, an error will be returned when displaying the component.

The Display tab lets you specify a documentation file (an HTML file that will show up when clicking on the help button in the Inspector), and an icon file that represents your component (shows up in the parent components instead of the default icon, e.g. ).

Interface Variable Synchronization

In WebObjects, you have control over the way values are stored in the attributes of elements (or sub-components).

The attribute's connection (also called binding) is a two-way street; if you set an element attribute in the parent component, the destination variable is automatically updated with the new value. If you set the binded variable in the element or sub-component, the parent's source variable is also changed (assuming it's not a constant). The "synchronization" between the parent and child variable happens at six specific times during the Request/Response loop, in the active WOComponent instance:

Before the generation, right before and right after calling takeValuesFromRequest()

During the action processing, right before and right after calling invokeActionFromRequest()

After the generation, right before and right after calling appendToResponse()

This process ensures that both the parent component and the element/sub-component have harmonized values at all times. It happens automatically, and relies on the existence of standard getter and setter functions in the classes of the variables. Casting is also done automatically as needed.

In the case of Custom Components, sometimes you don't want the variables to be in harmony. Sometimes, you don't even have a destination variable in the sub-component. You can turn off the synchronization of the variables and handle it by hand. You do that by overloading the Custom Component's synchronizesVariablesWithBindings() function. Then, you need to implement the variable synchronization yourself. Two functions help you do that: valueForBinding() to get the parent component's variable, and setValueForBinding() to set it to a new value. In the following example, we read in a variable from the parent, process it, and return the result in another variable:

import java.lang.Math;

public class MortgageCalculator extends WOComponent {
  //...

  public boolean synchronizesVariablesWithBindings() { 
    //Don't synchronize the parent's variables -
    //we'll do that ourselves
    return false;
    }

  public void awake() {
    //the parent thinks these variables exist:
    Double p = (Double)valueForBinding("principal");
    Double y = (Double)valueForBinding("years");
    Double i = (Double)valueForBinding("interest"); 
    if( (p==null) || (y==null) || (i==null) ) return;
    double r = i.doubleValue() / 1200;
    double cr = p.doubleValue() * r;
    double a = Math.pow(1.0+r, 12.0 * y.doubleValue());
    double b = a - 1.0;
    
    //put result back in another binding
    setValueForBinding(new Double(cr * a/b) , "payments"); 
  }

  //...
}

Getting and Sending Data to External Pages

You can't send values to external pages with global or local variables. We have to use the "standard" HTTP ways...

URL parameters

You can send data to a page by passing it URL parameters. The syntax is:
www.mactech.com/path/phonypage?param1=value1¶m2=value2...

The values have to be properly encoded (spaces replaced by plus signs (+), etc.).

TRICK: you can translate each value to comply to the URL encoding by using the function

String encodedValue = java.net.URLEncoder.encode("value to encode");
provided by Java. The result of the above line of code would be "value+to+encode". Don't encode the whole URL, just the values.

Note that URL parameters are automatically decoded and transformed into fields on reception...

Processing fields

You can receive form fields (including URL parameters) from an external page by using these WORequest functions, in the overloaded takeValuesFromRequest() of your component:

Methods Description
NSDictionary formValues() Returns key/value
pairs for all form
values.
NSArray formValueKeys() Returns the list of all
form field names
(NSArray of String).
These are used as
input for the next
methods.
String formValueForKey(String keyName) Returns the value for
the specified field
name
NSArray formValuesForKey(String keyName) Ditto. Use when
passed a list of
values.
(NSArray of String)

In the following example, we'll receive the username and password, and pre-populate the corresponding fields:

String password = ""; //connected to a "password" form field
String username = ""; //connected to a "username" form field

public void takeValuesFromRequest(WORequest r, WOContext c) {
  //Method #1
  String u = r.formValueForKey("username");
  if( (u != null) && !u.equals("") ) //not empty, assign it
  username = u; //pre-populate the username field on this login page

  //Method #2
  NSDictionary d = r.formValues(); //get all fields
  String p = d.objectForKey("password"); //extract field password
  if( (p != null) && !p.equals("") ) //not empty, assign it
    password = p; //pre-populate password field on this login page
}

Posting fields

The other way around, you can post form data to an external page, if you know how. Usually, the user navigates to an external page by clicking on a button, an image button or a hyperlink. Posting data is necessarily done by not pointing back to an action on the server, but by going directly to that external location. Note that this solution is equivalent to sending data as URL parameters. Here are some points to consider while implementing this solution:'

When using a hyperlink, submit button or image button, use a static one. You can turn a dynamic element into a static one by opening the Inspector and clicking on the button "Make Static". If you're planning to use a hyperlink, make it execute the submission of the form, like this:
<A HREF=”” onClick=”document.formName.submit(); return true;”>

Click here to submit

You should also use a static form (use "Make Static" button), and in the HTML , add some code to go to the external site. <FORM method=post ACTION=”www.othersite.com/cgi-bin/page.pl” NAME=formName>

The fields you use can be dynamic, but they don't have to be visible: you can use "hidden" fields to hide the submission of the form from the eyes of the user. This is commonly used to make it harder for the user to see data that he/she is not allowed to view. To make a hidden field, insert a custom component in your form , and in the Inspector set its class to WOHiddenField. Don't forget to set the "value" attribute.

Post-processing field posting

You might be interested in executing an action on the server before posting the form data to an external page. I have yet to see a simple way to do that. The most effective way I have found is to use a component with a form that posts itself automatically:

Use a normal button or hyperlink, connected to an action. The action would contain something like:

public WOComponent doSomethingAction() {
  //calculate value1
  //calculate value2
  //other processing...
  RedirectionPage rp = new RedirectionPage();
  rp.setField1(value1);
  rp.setField2(value2);
  return rp;
}

Create the new RedirectionPage component. It is an empty page, that consists of words "Please Wait", and the static Form with two hidden fields: field1 and field2. In the static Form's declaration, add the following action (in bold): <FORM method=post ACTION=”www.othersite.com/cgi-bin/page.pl” NAME=formName>

In the page's tag, add this JavaScript to post the form (in bold): <BODY onLoad=”document.formName.submit(); return true;”>

That's all. You may instead write a generic "Please Wait" page for your application, containing a dictionary of fields/values, and a variable target for the form. That way you would get maximum reuse.

Direct Actions

Let's do an experiment. Run any application and get in it through the front door by going to the URL:

http://localhost/cgi-bin/WebObjects.exe/AppName

Then click on a link. You should get a weird-looking URL syntax, with lots of digits that don't seem to mean anything. Here's an example URL:

http://localhost/cgi-bin/WebObjects.exe/AppName.woa/wo/nJ600003400sh6002/0.6

Let's dissect this URL. Of course, the first part is the protocol and server (http://...) followed by the WebObjects Adaptor (/cgi-bin/WebObjects.exe). Then there's the application name (AppName.woa - the extension is optional and means "WebObjects Application"). Until now, everything seems exactly like the previous URL. But what is the rest for? The wo/ tells us we are looking at a Web component. The following nJ600003400sh6002 is a randomly generated code that represents the current session, stored in the Session object as the member sessionID(). Lastly, the code /0.6 represents the page itself.

Take a look at the session identifier again. It is randomly generated. That means, when you return to the front door of the application, a new sessionID is created. This also means, after a session has expired, there's no way to point directly to the current page, if it is not the component Main.wo. This can be problematic, because sometimes you want to be able to bookmark or jump directly to a page.

This is a job for the Direct Actions. A Direct Action is a "backdoor" to your site. It is represented by a special URL syntax, like this:

http://localhost/cgi-bin/WebObjects.exe/AppName.woa/wa/actionName

Here the .woa extension is mandatory. The following /wa indicates a Direct Action, as opposed to a Component. And then there's the Direct Action's name.

Here there's no session identifier involved. The page is bookmarkable, and can be hardcoded in external Web pages and applications.

By default, Direct Actions point to a special class of your application, called DirectAction (extends WODirectAction), which is created automatically by the New Project assistant. When the user specifies a Direct Action, WebObjects calls automatically to the right function in this class, by using the Reflection API - no need to configure anything!

As an example, consider an administration page Admin.wo. It cannot be accessed directly or else any user would have total control. Creating a backdoor access to this site is very simple. The URL to use is:

http://localhost/cgi-bin/WebObjects.exe/AppName.woa/wa/Admin

and the corresponding Direct Action method is:

public class DirectAction extends WODirectAction {
  //...
  public WOComponent AdminAction() {
    Admin a = (Admin)pageWithName("Admin");
    return a;
  }
  //...
}

The important point here is to use a different Direct Action name for every "backdoor" entry point of the application, and to create a function of the same name, but with the word "Action" appended. Example: Since the Direct Action name is "AdminPage", so the function name is AdminPageAction().

TRICK: Say you want to get in through a backdoor from an external application, but keep the current session's context at the same time. You can do that by sending the session().sessionID() String out to the external application, then by going back to the desired Direct Action and passing back the session identifier in the URL parameter "wosid". This acronym means "WebObjects Session IDentifier", and it's a reserved URL/form parameter name. Here's an example URL:

http://localhost/cgi-bin/WebObjects/AppName.woa/wa/action?wosid=nJ600003400sh6002

Many more things can be done with Direct Actions. For example, in buttons and hyperlinks, Direct Actions can be used in lieu of regular actions. Also, special URL syntax can be used to access Direct Actions located in classes other than DirectAction.

Customizing Error Pages

Whenever there's an exception in your application, whether it happens in your code or in the frameworks, you get the usual, dreaded, ugly WebObjects exception page. Take a look at this sample:


Figure 1. Default ugly error page.

You don't want your users to see that - believe me. In an ideal world, you would never get an exception. But this is far from an ideal world, so let's get to work.

What you do want your users to see is a custom-made company-standards-compliant pretty page. How do you achieve that? Well, you can for sure catch exceptions as they occur (try block). Then you can redirect right away to your own nice exception page.

The following piece of code does just that, in the form of an action method:

WOComponent anAction() {
  try {
    doSomething();
    return resultPage;
  } catch (Throwable e) {
    NiceExceptionPage nep = new NiceExceptionPage();
    nep.setExceptionMessage(e.getMessage());
    nep.setTrace(NSLog.throwableAsString(e));
    return nep;
  }
}

But that's not complete. What about the other exceptions, the ones that happen outside your control? You're in luck. Whenever an uncaught exception occurs, WebObjects calls Application.handleException(). Let's see an example in which we overload this function to fire up our NiceExceptionPage:

public WOResponse handleException (Exception e, WOContext c) {
  NiceExceptionPage nep = new NiceExceptionPage(c);
  nep.setExceptionMessage(e.getMessage());
  nep.setTrace(NSLog.throwableAsString(e));

  WOResponse response = nep.generateResponse();

  return response;
}

You can even make a different error page for each of these events, by overloading the proper function:

Error handler in Application Is called ...
handleException() ... always. Default
implementation
brings up one of
the next error
pages, or if none of
them are
appropriate, brings
up the page
WOExceptionPage.
handleSessionCreationErrorInContext() ... when there was
an exception during
session
initialization. By
default, brings up
the page
WOSession
CreationError.
handleSessionRestorationErrorInContext() ... when the session
timed out and
the user is trying to
go back to an
earlier page. By
default, brings up
the page
WOSession
RestorationError.
handlePageRestorationErrorInContext() ...when the user
backtracks to an
earlier page (back
button) but the
context of that page
is lost. By default,
brings up the page
WOPage
RestorationError.

There's a second way to customize the error pages. You can fix all exception pages once and for all, for every single application on your computer or your server. It involves modifying the template files for the actual (ugly) exception pages from WebObjects' framework folders. Here's the location of these components:

Location Component Name
/System/Library/Frameworks/ WOExceptionPage.wo
JavaWOExtensions.framework/ WOPageRestorationError.wo
Resources/ WOSessionCreationError.wo
WOSessionRestorationError.wo

NOTE: when you modify these components, don't forget to

  • make a copy of the original page before starting
  • propagate the modified pages to all your Server(s) along with your application - they are not tied to your project

This will save you a lot of trouble.


Emmanuel Proulx is a Course Writer, Author and Web Developer, working in the domain of Java Application Servers. He can be reached at emmanuelproulx@yahoo.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

The beginner's guide to Warbits
Warbits is a turn-based strategy that's clearly inspired by Nintendo's Advance Wars series. Since turn-based strategy games can be kind of tricky to dive into, see below for a few tips to help you in the beginning. Positioning is crucial [Read... | Read more »
How to upgrade your character in Spellsp...
So you’ve mastered the basics of Spellspire. By which I mean you’ve realised it’s all about spelling things in a spire. What next? Well you’re going to need to figure out how to toughen up your character. It’s all well and good being able to spell... | Read more »
5 slither.io mash-ups we'd love to...
If there's one thing that slither.io has proved, it's that the addictive gameplay of Agar.io can be transplanted onto basically anything and it will still be good fun. It wouldn't be surprising if we saw other developers jumping on the bandwagon,... | Read more »
How to navigate the terrain in Sky Charm...
Sky Charms is a whimsical match-'em up adventure that uses creative level design to really ramp up the difficulty. [Read more] | Read more »
Victorious Knight (Games)
Victorious Knight 1.3 Device: iOS Universal Category: Games Price: $1.99, Version: 1.3 (iTunes) Description: New challenges awaits you! Experience fresh RPG experience with a unique combat mechanic, packed with high quality 3D... | Read more »
Agent Gumball - Roguelike Spy Game (Gam...
Agent Gumball - Roguelike Spy Game 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Someone’s been spying on Gumball. What the what?! Two can play at that game! GO UNDERCOVERSneak past enemy... | Read more »
Runaway Toad (Games)
Runaway Toad 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: It ain’t easy bein’ green! Tap, hold, and swipe to help Toad hop to safety in this gorgeous new action game from the creators of... | Read more »
PsyCard (Games)
PsyCard 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: From the makers och Card City Nights, Progress To 100 and Ittle Dew PSYCARD is a minesweeper-like game set in a cozy cyberpunk... | Read more »
Sago Mini Robot Party (Education)
Sago Mini Robot Party 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: -- Children's Technology Review Editor's Choice -- | Read more »
Egz – The Origin of the Universe (Games...
Egz – The Origin of the Universe 1.0.2 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.2 (iTunes) Description: ►►► Special offer until 2nd may : get the game at 2.99€ instead of 3.99€ ! ◄◄◄ Egz is a mesmerizing mix... | Read more »

Price Scanner via MacPrices.net

SanDisk Half-Terabyte SSD Optimized for Every...
SanDisk Corporation has announced the SanDisk Z410 SSD, a cost-competitive, half-terabyte solid state drive (SSD) that enables manufacturers to design for a broad range of desktop PCs and laptops.... Read more
Churchill Downs Racetrack Selects VenueNext t...
Churchill Downs Racetrack has announced an agreement with VenueNext to implement its technology platform for the start of Churchill Downs 2016 Spring Meet, which includes the 142nd running of the... Read more
Record 700 Million Pounds of CE Recycled in 2...
The Consumer Technology Association (CTA) reports that a record-setting 700 million pounds of consumer electronics (CE) have been recycled under the eCycling Leadership Initiative (ELI). According to... Read more
Price drops on clearance 12-inch Retina MacBo...
B&H Photo has dropped prices on leftover 2015 12″ Retina MacBooks with models now available starting at $999. Shipping is free, and B&H charges NY tax only: - 12″ 1.1GHz Gray Retina MacBook... Read more
15-inch Retina MacBook Pros available for $20...
B&H Photo has 15″ Retina MacBook Pros on sale for up to $210 off MSRP. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799 $200 off MSRP - 15″ 2.5GHz Retina... Read more
Target offers Apple Watch Sport for $50 off M...
Target has Apple Watch Sports on sale for $50 off MSRP for a limited time. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-store prices may vary... Read more
Apple restocks Certified Refurbished Mac mini...
Apple has restocked Certified Refurbished 2014 Mac minis, with models available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $... Read more
15-inch 2.2GHz Retina MacBook Pro on sale for...
Amazon.com has the 15″ 2.2GHz Retina MacBook Pro on sale for $1699.99 including free shipping. Their price is $300 off MSRP, and it’s the lowest price available for this model from any reseller (and... Read more
Apple Beats Microsoft at Own Game; Amazon Pri...
First quarter seasonality combined with an overall disinterested customer base led to an annual decline of 14.7% in worldwide tablet shipments during the first quarter of 2016 (1Q16). Worldwide... Read more
Tablets Had Worst Quarter Since 2012, says St...
The global tablet market began 2016 just as 2015 left off, down. Tablet shipments fell 10% to 46.5 million units during the Q1 2016, according to the new “Preliminary Global Tablet Shipments and... Read more

Jobs Board

Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Simply Mac *Apple* Specialist- Service Repa...
Simply Mac is the largest premier retailer of Apple products in the nation. In order to support our growing customer base, we are currently looking for a driven Read more
*Apple* Retail - Multiple Positions - Apple,...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Automotive Sales Consultant - Apple Ford Linc...
…you. The best candidates are smart, technologically savvy and are customer focused. Apple Ford Lincoln Apple Valley is different, because: $30,000 annual salary Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.