Common Rules

This chapter provides examples of some common rules you can use to customize applications. It first provides a section listing common left-hand side qualifier keys. You use these keys to tell the rule system which part of an application to affect with a particular rule.

Left-Hand Side Qualifier Keys

Most rules that you write are likely to use the following keys in the left-hand side qualifier:

You can further restrict a left-hand side qualifier using these keys:

Confirmation Dialog

Problem: By default when you query on an entity without supplying a qualifier, you are presented with a dialog to confirm the action, as shown in Figure 15-1. This behavior is intended to warn users about performing unqualified queries of the data store, which could fetch hundreds or thousands of records.

Figure 15-1  Confirm dialog on unqualified queries
Confirm dialog on unqualified queries

Solution: Use the rule system to override the default behavior.

The confirmation dialog appears when a user invokes an unqualified query (a query with no search criteria). Whenever you want to modify the behavior of a controller in a Direct to Java Client application, you should first consult Controllers and Actions Reference. If you look for EOQueryController, you’ll find an XML attribute called runsConfirmDialogForEmptyQualifiers. This is the switch you’re looking for. So to disable the confirmation dialog, add this rule to your application’s d2w.d2wmodel file:

Left-Hand Side:
*true*
Key:
runsConfirmDialogForEmptyQualifiers
Value:
"false"
Priority:
50

Window Size

Problem: You want to specify a minimum width and height for all windows in your application.

Solution: Use the rule system.

To set the minimum width of all windows in your application to 512 pixels, use this rule:

Left-Hand Side:
(controllerType='windowController')
Key:
minimumWidth
Value:
512
Priority:
50

To set the minimum height of all windows in your application to 350 pixels, use this rule:

Left-Hand Side:
(controllerType='windowController')
Key:
minimumHeight
Value:
350
Priority:
50

Widget Alignment

Problem: You want to right-align all widgets that contain numbers.

Solution: Write a rule.

To right-align all widgets in your application whose attribute’s value class is a number type, use this rule:

Left-Hand Side:
((not (attribute= nil)) and (attribute.valueClassName='NSNumber') or (attribute.valueClassName='NSDecimalNumber'))
Key:
alignment
Value:
"Right"
Priority:
50

Custom Controllers

Problem: You’ve subclassed one of the core controller classes (EOFormController, EOListController, EOQueryController) and you want to use it in place of the default controller throughout the application.

Solution: Write a rule.

To use a custom subclass of EOQueryController called QueryController in the package com.mypackage, use this rule:

Left-Hand Side:
((task='query')and (controllerType='entityController'))
Key:
className
Value:
"com.mypackage.QueryController"
Priority:
50

To use the custom subclass only for a specific entity, use this rule:

Left-Hand Side:
((task='query') and (entity.name="<entity name>"))
Key:
className
Value:
"com.package.CustomQueryController"
Priority:
50

Custom Class for Widgets

Problem: You want to use a custom widget class for a particular widget in your application.

Solution: Write a rule.

To use a custom widget class for the creditCardNumber attribute of a Person entity, use this rule:

Left-Hand Side:
((entity.name='Person') and (attribute.name="creditCardNumber"))
Key:
widgetController
Value:
"com.client.CustomController"
Priority:
50

CustomController is a subclass of EOWidgetController:

package com.client;
 
import javax.swing.*;
import com.webobjects.foundation.*;
import com.webobjects.eogeneration.*;
import com.webobjects.eointerface.swing.*;
 
public class CustomController extends EOWidgetController {
 
    public CustomController(EOXMLUnarchiver unarchiver) {
        super(unarchiver);
    }
 
    protected JComponent newWidget() {
        return new JPasswordField("");
    }
}

Custom Attributes for Controllers

Problem: You want to set custom attributes for a particular type of controller throughout your application.

Solution: Write a rule.

The Direct to Java Client Assistant allows you to set attributes for controllers such as horizontallyResizable, editability, and label. The attributes for each controller are listed in Controllers and Actions Reference. To disable horizontal resizing for all modal dialogs in an application, use this rule:

Left-Hand Side:
(controllerType = "modalDialogController")
Key:
horizontallyResizable
Value:
"false"
Priority:
50

Continuous Change Notification

Problem: You want to implement continuous change notification for a particular controller.

Solution: Write a rule.

Starting with WebObjects 5.2, some controllers can implement continuous change notification. To implement continuous change notification for a dynamically generated controller using rules, you must first identify the controller and then write a rule with a right-hand side key of prefersContinuousChangeNotification and value of true.

The example application Admissions in Enhancing the Application could benefit from continuous change notification. In the section Add Custom Code, you added custom business logic that calculates a rating for a particular student record. By default, the rating is updated after the user tabs out of one of the fields that is part of the rating calculation. By applying continuous change notification to one of those fields, however, the rating updates each time a user makes a change in one of those fields.

The user interface element to which you’ll add continuous change notification is the Student form window, as shown in Figure 15-2.

Figure 15-2  Field to add continuous change notification to
Field to add continuous change notification to

The first step is to identify the form controller in the rule system. The best way to do this is to open Assistant and make a trivial change to that controller, such as changing the default window location. Doing so writes a rule to the application’s user.d2wmodel file. That rule’s left-hand side is how the controller is identified in the rule system. By copying the left-hand side of that rule to the application’s d2w.d2wmodel file, you can customize its behavior and characteristics by adding right-hand side keys and values.

Here is the rule to implement continuous change notification in this example:

Left-Hand Side:
((task = 'form') and (entity.name = 'Student'))
Key:
prefersContinuousChangeNotification
Value:
"true"
Priority:
50

If you implemented the validation methods in Validation, you may see many validation exception dialogs when you implement continuous change notification, depending on what kind of validation you implement.