Introduction

A WODisplayGroup is a versatile way of fetching objects from the database and displaying them.

Some of the options a WODisplayGroup can provide you are:

• paginate your results
• filter your results using queryOperators and pattern matching
• display Master/Detail pages

Creating a WODisplayGroup with WOLips

• If you have moved your development to WOLips, the "default" display group is created using the Display Group component editor.

• If you choose to use the Display Group editor, behind the scenes you are actually modifying your component's .woo file. In general you shouldn't modify the .woo file by hand. The Apple docs define this file as containing information that describes WODisplayGroup objects (and a couple of other things like character encoding). The .woo archive is stored in your component's bundle (.wo) and is used to create and configure the display groups at runtime. There is currently no graphical representation in WOLips to tell you whether the WODisplayGroup has been initialized in the component editor. This was something that WOBuilder showed you in the Layout display mode. You'll have to go into the Display Group editor to determine whether it has been configured or not. The other change from WOBuilder is that an instance variable for your WODisplayGroup with the same name that has been defined in the Display Group editor must be added to the .java file. This is no longer automatic. The end result is that WebObjects will automatically instantiate your display group when the page is created using information contained in the .woo.

• The .woo file is optional if all the information required to initialize the display group is contained in the Java file. This is the key to being able to create a display group programatically and leave the automatic initialization behind. By doing this, you will free yourself from several limitations that an automatically initialized WODisplayGroup is forcing on you behind the scenes. The real aim of this document is to show you where the limitations are, and how you can get around them by initializing the WODisplayGroup yourself in the .java file. This will allow you to configure your display groups in a much more powerful and flexible manner for use in your components. The drawback, as with everything in WebObjects, is that as you get further away from the "default" implementation, your need to understand what you are doing increases significantly. Fortunately this document (will soon be!) here to help you fill in the gaps of your understanding!

  Info

  So, if you have chosen the display group which is automatically initialized from the .woo, here is a brief description of the UI elements you see in the Display Group editor:
• You should name your display group. The convention is to have the entity name in lower case followed by display group (accountDisplayGroup).
• You must select the entity from your model that you wish to fetch from the database and display in your application (Account).

  Warning
  title Missing
  Need description for Master/Detail display groups here

• If you would like to page your results, a convenient way to do so is to set the "Entities per batch" you would like to display on your page. If you think of results pages for Google searches or flickr photo pages, a good rule of thumb is about 10 items per page. You can use the WOBatchNavigationBar component to paginate the results for you.
• You can set how you want your query to the database to be processed in the display group fetch. Do you want the text item at the start of the data (prefix), somewhere in the data (contains) or ending the data (suffix).
• The "Fetches on Load" tells the component whether the values for the entity to be displayed should be fetched from the database when the page is initially created or not.
• The sorting pull down allows you to tell the display group which attribute of the entity to sort on when the entities are displayed in a list. Below the attribute you select, you can choose whether you want the attribute to be sorted in ascending or descending order, or whether it should be left unsorted.
• The Fetch Spec pull down allows you to select a named fetch specification that you have created in your entity model to allow you to filter your array of objects before you return them to the page. This gives you greater flexibility to filter and sort on multiple attributes and give complex qualifications for the entity's attributes.

Here is the resulting .woo file:

Creating a WODisplayGroup with Xcode

• If you are still using Xcode and WOBuilder/EOModeler, getting started with WODisplayGroups requires very little code and most of the display choices can be wired up in WOBuilder. To get started you simply drag the entity you wish to display from your EOModel into the component where you want to create the WODisplayGroup. Another option is to drag a relationship from your EOModel which will automatically set up a WODisplayGroup with Master/Detail information already set. Another option is to create a DisplayGroup component using the template available to you in XCode under the "Add a new file" option.