Embedding Direct to Web Components

Using a Direct To Web component is not much different than using any other reusable component. In this section you create a D2WQuery that searches for Listing entities based on the address. The procedure is the following:

1. Add the Direct to Web and the Direct to Web Generation frameworks to your project. The path for these frameworks is /System/Library/Frameworks and the file names are JavaDirectToWeb.framework, JavaDTWGeneration.framework, and JavaEOProject.framework.

2. Decide which Direct to Web component you want to use and become familiar with its API.

   See the “D2W” class reference in the WebObjects API Reference for summaries of these components.

3. Put a WebObjects tag for the component in the page that is to display it.

   <WEBOBJECT NAME=MyD2WQuery></WEBOBJECT>

   This is a step you can complete in WebObjects Builder. The reusable components are available from the “DirectToWeb” palette.

4. Make the appropriate bindings for the component.

   MyD2WQuery:D2WQuery {

   entityName="Listing";

   displayKeys="(address.city,address.state, address.zip)";

   queryDataSource=listingDisplayGroup.dataSource;

   }

   All embedded components require an entityName binding to specify the entity the page works with. Extra bindings could be required, depending on the functionality of the page. For example, List pages require a dataSource binding. If you want to use a named configuration, specify it with a pageConfiguration binding. See Named Configurations for more information about named configurations.

   You can also complete this step in WebObjects Builder.

5. If necessary, implement the action method for the component.

6. You can customize embedded Direct to Web components using the Web Assistant. You can launch the Web Assistant using the appletviewer tool.

   When the Web Assistant acts upon an application that was not generated using Direct to Web, it does not automatically track which page is displayed. Thus you must set the task and entity for the page you want to modify in Expert mode. For example, if you want to customize a list page for Customers, click Expert mode and select the list task and the Customer entity. You can then customize a component in the same way you customize Direct to Web pages. Also, when you click Update to send the new settings to the application, the browser does not automatically refresh your page. You must either click the Reload button in your browser or (especially when you select a new task or entity) you must renavigate to the page.

By default, your component appears in the Neutral look.

Linking to a Direct to Web Page

The second way to use Direct to Web in you application is to link directly to a dynamically generated page of the appropriate type. The D2W class defines methods that create components (inspect, query, list, and so on) defined for an entity in a session. The returned component objects implement the appropriate interface:

QueryPageInterfacequeryPageForEntityNamed (String entity,

    WOSession session);

ListPageInterface listPageForEntityNamed(String entity,

    WOSession session);

EditPageInterface editPageForEntityNamed(String entity,

    WOSession session);

InspectPageInterface inspectPageForEntityNamed(String entity,

    WOSession session);

SelectPageInterface selectPageForEntityNamed(String entity,

    WOSession session);

EditRelationshipPageInterfaceeditRelationshipPageForEntityNamed

    (String entity, WOSessionsession);

QueryAllPageInterface queryAllPage(WOSession session);

To create a named configuration page, you use the method

WOComponentpageForConfigurationNamed

    (String namedConfiguration,WOSession session);

To link to a Direct to Web page, you need to implement an action method that returns a Direct to Web component implementing the appropriate page interface.

<WEBOBJECTname=D2WListPage>D2W list page</WEBOBJECT>

D2WListPage:WOHyperlink {

    action = d2wList;

}

importcom.webobjects.directtoweb.*;

.

.

.

public WOComponent d2wList(){

    ListPageInterface lpi =

        D2W.factory().listPageForEntityNamed("Listing",session());

    lpi.setDataSource(listingDisplayGroup.dataSource());

    lpi.setNextPage(this);

    return (WOComponent)lpi;

}

publicclass MyListPage extends WOComponent {

    public WODisplayGroup myDisplayGroup;

...

    public WOComponent showD2WQuery(){

        QueryPageInterface qpi=

            D2W.factory().queryPageForEntityNamed(“Customer”,session());

        qpi.setNextPageDelegate(new NextPageDelegate() {

            // delegate implementation

            public WOComponentnextPage(WOComponent sender) {

                EODataSourceds;

                NSArray objectsToAdd;

                Enumeratione;

                ds =((QueryPageInterface)sender).queryDataSource();

                objectsToAdd= ds.fetchObjects();

                e = objectsToAdd.objectEnumerator();

                while (e.hasMoreElements()){

                    EOEnterpriseObjecteo;

                    eo =(EOEnterpriseObject)e.nextElement();

                    MyListPage.this.myDisplayGroup.

                        insertObjectAtIndex(eo,0);

                }

                return MyListPage.this;

            }

        });

        return (WOComponent)qpi;

    }

}

<HTML>

    <WEBOBJECT name=Head></WEBOBJECT>

    <BODY>

        <WEBOBJECT name=BodyContainer>

        <WEBOBJECT name=Body></WEBOBJECT>

        </WEBOBJECT>

    </BODY>

</HTML>

BodyContainer:WOBody {

    filename = "Background.gif";

    framework = "JavaDirectToWeb";

    bgcolor="#c0c0c0";

    TEXT = "#000000";

    LINK = "#0000F0";

    VLINK = "#0000F0";

    ALINK = "#FF0000";

}

Head : D2WHead {

    _unroll = true;

}

Body: WOComponentContent {

    _unroll = true;

};

Specifying the Custom Component

The custom property-level component must be a reusable component that defines two keys: object and key. The value for object specifies the enterprise object that the reusable component manipulates, for example, a Customer object. The value for key specifies the key of the property that the component manipulates, for example, firstName.

You can get the property by defining two instance variables in your component:

EOEnterpriseObjectobject;

String key;

and using the EOKeyValueCoding method valueForKey:

Stringfirst = object.valueForKey(key);

To store a value for the property, you use takeValueForKey:

object.takeValueForKey(first,key);

If you are using a nonsynchronizing component, you need to get the values for the object and key bindings using the valueForBinding method before you get or store the property.

EOEnterpriseObjectobject = valueForBinding(“object”);

String key = valueForBinding(“key”);

EditStatePopup Listings shows an example custom component called EditStatePopup that uses a pop-up list to edit US states. The example lists the .html, .wod, and .java files that specify the custom component.

Using the Custom Component With Direct to Web

Once the custom component has been compiled, you can use the Web Assistant to instruct your Direct to Web application to use it. Follow these steps to configure your application to use the pop-up list state editing component for the state attribute on the ListingAddress edit page:

1. Open the Web Assistant. See Customizing Your Application With the WebAssistant.

2. Click the “Expert mode” button.

   In Expert mode, you can make changes that affect all pages for a given task.

3. Select the Properties tab.

4. Select the edit task and the ListingAddress entity.

5. Click state in the Show column.

6. In the right column, choose D2WCustomComponent from the pop-up list.

7. Enter the name EditStatePopup in the Component text box.

You can also use the Web Assistant to configure your application to use a custom component on every edit page by following these steps:

1. Select the edit task and “*all*” for the entity.

2. Select the data type your component handles in the type browser in the second column.

3. In the right column, choose D2WCustomComponent from the pop-up list.

4. Enter the name of your component in the Component text box.

You can also configure your application to use the custom component by setting rules with the rule editor instead of using Web Assistant. To do so, use the rules shown in Listing 3-5. (To open the user.d2wmodel in the Resources group of Project Builder’s main window, drag its icon in Project Builder onto the RuleEditor icon in the Dock.)

Listing 3-5  Setting Rules With Rule Editor

((task= “edit”) and (entity.name = “ListingAddress”)

    and (propertyKey = “state”)

    => componentName = “D2WCustomComponent”

((task = “edit”) and (entity.name= “ListingAddress”)

    and (propertyKey = “state”)

    => customComponentName= “EditDatePopup”

You also need to set the assignment class (Assignment) and the priority (100) for each rule. For more information about using the rule editor, see Adding Rules to Define the Default Behavior.

Freezing Your Modified Direct to Web Template

You can freeze a page based on your Direct to Web template using the Web Assistant. See Generating Components for more details. Make sure that your template is selected in the template pop-up list in the third column of the Web Assistant.

In the example above, the editList action is missing from any component created by freezing the NEUListPage2 template.

Sometimes you add components to your Direct to Web template that have child components. For example, tables, WOConditionals, WORepetitions, and any reusable components with a WOComponentContent dynamic element all have child components. If you add such components to your Direct to Web template, add an attribute called _unroll and bind it to YES. This attribute enables Direct to Web to include the component’s children when you freeze the template.

Creating the Direct to Web Template

The easiest way to create a Direct to Web template is to modify one that the Web Assistant generates. The edit-list page most closely resembles the list page.

1. For this example, begin with the project you created in the last section, Modifying a Direct to Web Template. You should have a modified NEUListPage2 Direct to Web template in your project.

2. Create a Direct to Web template called “NEUEditListPage” based on the NEUListPage by following steps 2–4 in Modifying a Direct to Web Template.

3. Open NEUEditListPage.wo in WebObjects Builder. Follow the directions below to modify the template.

4. Remove the first and last columns of the main table. The left column contains an icon that opens the edit page. The right column contains an icon that deletes the record. Since the list page provides these functions, they are not duplicated on the edit-list page.

5. Now wrap the main table inside a WOForm. The easiest way to do this is to use the source view. Find the line

   <WEBOBJECTNAME=NavBar></WEBOBJECT>

   Change it to

   <WEBOBJECT NAME=NavBar></WEBOBJECT><WEBOBJECTNAME=Form1>

   Find the first </CENTER> tag in the file. Add a closing </WEBOBJECT> above this line.

6. In the next three steps, you change the Return hyperlink into a submit button and add a Save submit button that saves the changes to the database. Find the line

   <WEBOBJECT NAME=ShowCancel><WEBOBJECTNAME=BackLink><WEBOBJECT

   NAME=ReturnButton></WEBOBJECT></WEBOBJECT></WEBOBJECT>

   Add

   <WEBOBJECTNAME=SubmitChanges></WEBOBJECT>

   between the last two </WEBOBJECT> tags. The line should now look like this:

   <WEBOBJECTNAME=ShowCancel><WEBOBJECT NAME=BackLink><WEBOBJECT

   NAME=ReturnButton></WEBOBJECT></WEBOBJECT><WEBOBJECTNAME=SubmitChanges>

   </WEBOBJECT></WEBOBJECT>

7. In the bindings file, find the bindings for the ReturnButton WebObjects element. Change it so it reads as follows:

   ReturnButton:WOImage {

   alt = "Cancels changes";

   border = "0";

   filename = "CancelMetalBtn.gif";

   framework = "JavaDirectToWeb";

   name = "Cancels changes";

   }

8. Add the following bindings to the bindings file:

   Form1:WOForm {

   action = backAction;

   }

   SubmitChanges: WOImageButton{

   action = saveChanges;

   alt = "Saves your changes";

   border = "0";

   filename = "SaveMetalBtn.gif";

   framework = "JavaDirectToWeb";

   name = "Saves yourchanges";

   }

   The backAction method is defined by the NEUEditListPage component’s superclass, D2WListPage.

9. Switch back to the layout view to check for HTML syntax errors.

10. Save the NEUEditListPage.wo file.

11. Modify NEUEditListPage.java by adding the saveChanges method defined in Listing 3-6.

    
    
    

    Listing 3-6  Implementation of the saveChanges method in NEUEditListPage.java

    publicWOComponent saveChanges() {

    WOComponent nextPage = this.nextPage();

    try {

    session().defaultEditingContext().saveChanges();

    } catch (Exception exception){

    ErrorPageInterface epi= (ErrorPageInterface)

    D2W.factory().errorPage(session());

    epi.setMessage(exception.toString());

    epi.setNextPage(this);

    nextPage = (WOComponent)epi;

    } finally {

    return nextPage;

    }

    }

This Java code tries to save changes to the session’s editing context. If it fails, it returns an error page. Otherwise, it returns to the page that called it.

Adding Rules to Define the Default Behavior

When a Direct to Web application launches, it looks for rules in two files in your project, user.d2wmodel and d2w.d2wmodel, and merges them with the rules defined in the Direct to Web framework. The Web Assistant modifies the rules in the user.d2wmodel file. For basic customization tasks you don’t need to edit this file by hand. When you add rules that change the default behavior of your application, you modify the d2w.d2wmodel file.

Defining the default behavior of a new task page also informs the Web Assistant of the new task. Specifically, the Web Assistant collects a list of tasks based on the task =“taskName” clauses on the left-hand side of rules.

Direct to Web provides an application called RuleEditor to edit the rules.

For the edit-list page example, you need to

• revise the Web Assistant rules in the user.d2wmodel file

  The Web Assistant created two rules when you generated the NEUEditListPage Direct to Web template. These rules state that the NEUEditListPage can and should be used with the list task. Since you are creating an edit-list task, which exclusively uses the NEUEditListPage Direct to Web template, these rules must be changed.

• create a d2w.d2wmodel file and put rules that define the edit-list page default behavior in it

Adding a Hyperlink to the New Task Page

Now that Direct to Web can display the edit-list task page, you need to add a hyperlink to the list page to bring up the edit-list page.

1. Modify the editList method in NEUListPage2.java so it matches the implementation in listing below:

   
   
   

   Listing 3-7  Implementation of the editList method in NEUListPage2.java

   publicListPageInterface editList {

   ListPageInterface lpi =(ListPageInterface)D2W.factory().

   pageForTaskAndEntityNamed(“editList”,entity().name(),

   session());

   lpi.setNextPage(this);

   lpi.setDataSource(displayGroup().dataSource());

   return lpi;

   }

   The edit-list page uses the same interface as the list page (ListPageInterface) because the pages are very similar. The action method editList creates a new page using pageForTaskAndEntityNamed because the factory has no special method to create an edit-list page. You could add such a method if you like. See Modifying the Direct to Web Factory.

   To specify the page to display when the user cancels the edits, the action method invokes setNextPage. When the user clicks the Cancel button, this list page will display. Finally, the action method sets the data source for the display group so it matches the list page’s data source. This ensures that the edit-list page displays the same objects the list page displays.

2. Build and launch your application. Navigate to a list page. Click the Edit button.

   The edit-list page should appear. You can type in a field to edit its contents. If you click cancel, the edits are discarded. If you click save, the edits are saved to the database. You can page through the displayed objects with the navigation bar at the top of the screen. When you move from one page to another, the edit-list page discards the edits.

3. You can use the Web Assistant to further customize the edit-list page.

Hooking Up the Main Component

To implement login authentication, you need to edit the Main component and add some custom Java code. Open Main.wo in WebObjects Builder and add a new action called “login” returning null, as shown in Figure 3-2.

Change the binding for the action attribute of the Login button by dragging from the login action to the Login button, as shown in Figure 3-3. Choose “action” from the menu that pops up to bind it.

Add Logic

When you add an action to the Main component, WebObjects Builder generates Java code for the method based on the inputs specified in the Add Action dialog. In Main.java, you should see this code for the login action you added:

publicWOComponent login() {

    return null;

}

Clicking the Login button causes its action binding to be resolved. Since the action binding is “login”, this calls the login method defined in the component. The login method simply returns null, which returns a new instance of the component calling the method in WebObjects. In our example, this means a new instance of the Main component is created, returned, and displayed when the Login button is clicked. See the WebObjects API Reference for the WOComponent class to better understand this behavior.

Rather than return the calling component (Main), you can add logic that returns a different page depending on the success of the authentication. To authenticate a user, you need to add some data to authenticate against. For now, simply add fields to Main.java. Later on, you’ll implement authentication against a data source.

Add these fields:

   private final String _username = “bucky”;

    private final String _password= “longfang”;

You should notice that there are two instance variables already in Main.java, username and password. If you switch to WebObjects Builder, you can see that these variables are bound to the value attribute of the Username and Password WOTextFields, respectively. When the Login button is clicked, the strings contained in these textfields are automatically put into their corresponding variables, username and password. This means that you can add logic to test the value of each textfield against login information in a data store, or in this simple case, against variables in the class.

Before you add authentication logic, look at the defaultPage method in the class:

publicWOComponent defaultPage() {

    if (isAssistantCheckboxVisisble()){

        D2W.factory().setWebAssistantEnabled(wantsWebAssistant);

    }

    return D2W.factory().defaultPage(session());

}

In an uncustomized Direct to Web application, this returns the queryAll page. See Query Pages for more information. If a user successfully authenticates, they will see this page. You will alter the login method to return this page if the user authenticates successfully. To do this, use a simple conditional:

if (_username.equals(username) && _password.equals(password))

If the conditional is true, return the default queryAll page. Otherwise, return the Main page with the login form. The complete code for Main.java is shown below:

importcom.webobjects.foundation.*;

import com.webobjects.appserver.*;

import com.webobjects.directtoweb.*;

public class Main extends WOComponent{

    public String username;

    public String password;

    public boolean wantsWebAssistant= false;

    private final String _username= “bucky”;

    private final String _password= “longfang”;

    public Main(WOContext aContext){

        super(aContext);

    }

    public WOComponent defaultPage(){

        if (isAssistantCheckboxVisible()){

            D2W.factory().setWebAssistantEnabled(wantsWebAssistant);

        }

        return D2W.factory().defaultPage(session());

    }

    public boolean isAssistantCheckboxVisible(){

        return null == NSProperties.stringForKey(“D2WWebAssistantEnabled”)

        || NSProperties.booleanForKey(“D2WWebAssistantEnabled”);

    }

    public WOComponent login(){

        if (_username.equals(username)&& _password.equals(password))

            return defaultPage();

        return null;

    }

}

Add Better Logic

In a deployed application, you would likely want to authenticate users to information in a data store. Fortunately, WebObjects make this easy for you. By packaging the username and password into a dictionary object, you can use the EOUtilities class to query a data store for a match of the given username and password. To use EOUtilities, be sure to import the com.webobjects.eoaccess package.

The following code example uses the RealEstate EOModel. The isAuthenticated method checks to see if the given username and password match an Agent entitity’s login and password attributes, respectively. Here is the code:

publicboolean isAuthenticated() {

    NSMutableDictionary userCredentials= new NSMutableDictionary();

    if (username == null ||password == null)

        return false;

    userCredentials.setObjectForKey(username,"login");    userCredentials.setObjectForKey(password, "password");    NSArray foundObjects =

    EOUtilities.objectsMatchingValues(session().defaultEditingContext(),

    "Agent", userCredentials);

    if (foundObjects.count()== 1)        return true;

    NSLog.out.appendln("Authenticationfailed.");    return false;}

Lastly, you want to modify the login method as follows:

publicWOComponent login() {

    if (isAuthenticated())

        return defaultPage();

    return null;

}

When a user successfully authenticates, the default Direct to Web page is returned.