XeoPrimerWebComponentsLibraryPart2 < WebXEO

WebXEO Web>XeoPrimer>XeoPrimerWebComponentsLibraryPart2 (2011-04-04, NicolauGrosskopf) (raw view)
-- Main.PedroRio - 19 Jan 2011
---+ XEO Web Components - Introducing the API

In the previous chapters you generated viewers using XEO Studio's Scaffolding tool and went [[WebXEO.XeoPrimerWebComponentsLibrary][through an explanation of the basics of XEO Viewers]] as well as [[WebXEO.XeoPrimerLibraryViewers][customized an edit viewer]] for the LIB_Book Object Model. In this chapter we'll introduce the Java API to use when creating your own custom viewers and beans, before that, however, you should create some instances of Object Models so that some of things you'll do in this chapter are visible.

Go the Main_Library.xvw viewer and add an entry for the list viewer of the LIB_Publisher Object Model with the following code:
<pre><verbatim><xvw:menu text='Publishers'
 value="{viewerName:'LIB_Publisher/list.xvw', boql:select LIB_Publisher}"
 target='Tab' serverAction="#{viewBean.listObject}" icon='resources/LIB_Publisher/ico16.gif'/>
</verbatim>
</pre>

And create a publisher with any name you like (Wrox Press, for example). Now add two book instances (for example book _Beginning Spring Framework 2_ and _Professional Apache Tomcat 6_), for the author you can use the previously created "John Doe" (or create a new one) and for the publisher use the newly created "<em>Wrox Press</em>" instance. The task in this section is to add a new tab to the LIB_Publisher and LIB_Author edit viewers, to display the list of each books that publisher/author has worked on. This will also be used to introduce the Java API that can be used.

Start by creating a new Java class in the _org.examples.viewer.beans_ package with the name _LibPublisherEditBean_ and make it extend the _netgest.bo.xwc.xeo.beans.XEOEditBean_ class, then open the LIB_Publisher/edit.xvw file and change the <em>classBean </em>property to _org.viewers.examples.viewers.beans.LibPublisherEditBean_ this will associate the viewer with this bean.

Next, add a new tab element, to the tabs container already present in the viewer, just like the following:
<verbatim><xvw:tabs>
<xvw:tab label="Nucleus">
      <xeo:bridge bridgeName='nucleus' >
          <xvw:columns>
              <xvw:columnAttribute width="150" label="Nucleus" dataField="SYS_CARDID"/>
          </xvw:columns>
      </xeo:bridge>
      </xvw:tab>
                    
          <xvw:tab label="Published Books">
          </xvw:tab>
</xvw:tabs></verbatim>

In order to display a list of Object Model instances you'll use the _xeo:list_ component which is essentially like the _xeo:bridge_ component used before, but tailored to display any list of instances (and not only lists that come from collection attributes). Since you'll be displaying books just use the book's title for the column. Type the following code in your viewer:
<verbatim><xvw:tab label="Published Books">
   <xeo:list targetList="#{viewBean.dataList}" >
       <xvw:columns>
           <xvw:columnAttribute width="150" dataField="title"/>
        </xvw:columns>
   </xeo:list>
</xvw:tab></verbatim>

Notice the "targetList='#{viewBean.dataList}'" property. It tells the _xeo:list_ component that its data source should come from the _dataList_ property of the current bean. Switch to the LibPublisherBean and create a method like the following (you'll need to import _netgest.bo.xwc.components.connectors.DataListConnector_):
<verbatim>public DataListConnector getDataList(){ }</verbatim>

The _DataListConnector_ interface represents a list of elements to display in a _xvw:gridPanel_ component (or any component that derives from the _xvw:gridPanel_ component, actually, like the _xeo:bridge_ and _xeo:list_ components). For the _xeo:bridge_ and _xeo:list_ components there's an implementation of the interface that allows to use elements from a _boObjectList_ instance. Compose the method with the following:
<verbatim>public DataListConnector getDataList(){
        String boqlExpression = "";
        boObjectList listBooksOfPublisher = ObjectListManager.list(getEboContext(), boqlExpression);
        return new XEOObjectListConnector(listBooksOfPublisher);
    }</verbatim>

To create a list of instances you only need a XEOQL expression and a Context to pass to the list method of the ObjectListManager class. The resulting set of instances is passed to the constructor of the XEOObjectListConnector which is an implementation of the DataListConnector interface for lists of XEO Model instances. The getEboContext() method is available for any bean that extends the XEOBaseBean (the case of the WebXEO.XEOEditBean which is the bean you're extending in this situation)

The only situation here is what will be the XEOQL expression to retrieve all books from the current publisher, to do that, use the following query:
<verbatim>String boqlExpression = "select LIB_Book where publisher = " + getXEOObject().getBoui();</verbatim>

The _getXEOObject()_ method is available in the WebXEO.XEOEditBean and returns the current _boObject_ instance being edited (in this situation, the publisher instance); since relations between instances are done using the instance's BOUI (Business Object Unique Identifier), you use the getBoui() method to complete the query. If the BOUI of the current publisher is 12345, the query would be _select LIB_Book where publisher = 12345_.

If you do this, open the list of Publishers, open the "Wrox Press" instance and select the "Published Books" tab you should see the list of books like depicted in figure XWCIA.1.

<img width="559" alt="" src="%ATTACHURL%/LibPublisherBooks.png" height="410" />

__Figure XWCIA.1 - List of books published by "Wrox Press"__

A note before moving on to the next viewer. List ( _xeo:list_) components are usually found inside list viewers which are associated with the XEOBaseList bean, and that bean has a specific method to open an edit viewer from the double click of an item in the list. The WebXEO.XEOEditBean does not have such a method and if you try double clicking on a line of the "Published Books" list it will trigger an error, to prevent that from happening you'll either have to implement a method to respond to the double click event, or disable that via the _onRowDblClick_ property, like in the following code:
<verbatim><xeo:list targetList="#{viewBean.dataList}" onRowDblClick="">
    <xvw:columns>
      <xvw:columnAttribute width="150" dataField="title"/>
   </xvw:columns>
</xeo:list></verbatim>

Also, a _xeo:list_ component includes a default toolbar with the "New" button, which creates a new instance for that list. The problem here, again, is that the "New" button assumes the existence of a method that will perform that action and that method is available in the XEOBaseList bean (but it's not on the WebXEO.XEOEditBean). So, if anyone presses the "New" button on this viewer an error will be triggered; the solution to that will be either disabling the button, or implementing the method. Since there's not much sense in creating a book directly from the publisher's page, hiding the button seems a better choice and to do that use the _renderToolBar_ property of the _xeo:list_ component, which will hide the entire toolbar of the list. The following code is the final version for this viewer.
<verbatim><xeo:list targetList="#{viewBean.dataList}" onRowDoubleClick="" renderToolBar="false">
    <xvw:columns>
       <xvw:columnAttribute width="150" dataField="title"/>
   </xvw:columns>
</xeo:list></verbatim>

As an exercise, do the same to the LIB_Author edit viewer (i.e. add a tab with all books that that author has ever published). You'll need to do exactly the same as in the publisher's viewer, but the XEOQL expression is a little different.
---+++ Custom rendering of columns

Very often you'd like to make a custom render for a given column, instead of just presenting its value. The _xvw:columnAttribute_ component which is used in gridPanels, list and bridges has precisely a property that lets you create your own custom render. For this example you'll take the list viewer of LIB_Book and change of state column so that instead of the state being the label "Available" / "Unavailable" it will display a small icon representing each state.

The first step is creating a new Java bean, based on the XEOBaseList (to replace the one in the LIB_Book list viewer), name it LibBookListBean and make it extend the _netgest.bo.xwc.xeo.beans.XEOBaseList_ bean (create it in the org.example.viewer.beans package). Open the LIB_Book list viewer and replace the _beanClass_ property with _org.example.viewer.beans.LibBookListBean_. Next you'll need the icons representing the state of the book, you can use the two following icons ( <img alt="book_add.png" src="%ATTACHURL%/book_add.png" /> <img alt="book_delete.png" src="%ATTACHURL%/book_delete.png" /> ) and save them as "book_available.png" and "book_unavailable.png" in the _webapps/default/Extras/Icons_ folder (you can use any other icon you'd like).

Open the LibBookListBean and create the following method:
<pre><verbatim>public GridColumnRenderer getMyRenderer() { }</verbatim>
</pre>

The _GridColumnRenderer_ is an interface that WebXEO.ColumnAttribute components accept in order to change the renderer of its value. The GridColumnRenderer interface has a single method definition which is:
<pre><verbatim>public String render(GridPanel grid, DataRecordConnector record, DataFieldConnector field)</verbatim>
</pre>

The _render_ method will return the value to be displayed on a given column (for each row), it returns a string which can be HTML code (allows you to display images, tables, or anything html provides). This method will be called once for every line in the corresponding gridPanel/list/bridge component for the given column where the renderer is being applied.

The render method receives three parameters. The WebXEO.GridPanel (could be a List or Bridge component, because both extend from WebXEO.GridPanel) where the column attribute is placed, a DataRecordConnector instance and a DataFieldConnector instance. A DataRecordConnector is an interface representing a specific line in a list of elements. You used the DataListConnector interface before to display the list of books of a publisher; each of those books in a DataListConnector is represented by a DataRecordConnector. The DataFieldConnector is yet another interface which is tied to the DataListConnector and DataRecordConnector because it represents the value (and metadata) of a given column within a single line.

In order to complete this custom renderer, change the LIB_Book list viewer to the following:
<verbatim><xeo:formList>
            <xeo:list enableGroupBy='true'>
                <xvw:columns>
                    <xvw:columnAttribute width="100" dataField="title" groupable='true'/>
                    <xvw:columnAttribute width="20" dataField='state' renderer='#{viewBean.myRenderer}'/>
                    <xvw:columnAttribute width="100" dataField="publisher"/>
                    <xvw:columnAttribute width="100" dataField="edition"/>
                    <xvw:columnAttribute width="100" dataField="authors"/>
                    <xvw:columnAttribute width="100" dataField="isbn"/>
                </xvw:columns>
            </xeo:list>
        </xeo:formList></verbatim>

Now go back to the bean and type/paste the following (inside the getMyRenderer method):
<verbatim>return new GridColumnRenderer() {
            
   @Override
   public String render(WebXEO.GridPanel grid, DataRecordConnector record, DataFieldConnector field) {
      String state = field.getValue().toString(); //Retrieve the value of state lov
         if(state.equals("0"))
            return "<img src='Extras/Icons/book_add.png' title='Available'/>";
         else
            return "<img src='Extras/Icons/book_delete.png' title='Unavailable'/>";
          }
            
   };</verbatim>

If you recall from the LIB_Book Modeling phase, the state attribute was connected to a XEO Lov, which had two values, "0" for Available and "1" for Available. You'll only have to check what's the value of the state attribute and return an HTML string with the link to the image (as depicted in the previous code). Save the bean, launch the project and go the list of books, the result should now be like the one depicted in figure XWCIA.2, bellow.

<img width="730" alt="LibBookListCustomRenderer.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerWebComponentsLibraryPart2/LibBookListCustomRenderer.png" title="LibBookListCustomRenderer.png" height="166" />

__Figure XWCIA.2 - List viewer with custom renderer for a column__

_

In the [[WebXEO.XeoPrimerWebComponentsMovement][next chapter you'll learn how to create a more complex viewer, for the Movement Model]].
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who
png	LibBookListCustomRenderer.png	manage	9.5 K	2011-01-21 - 11:37	PedroRio
png	LibPublisherBooks.png	manage	16.3 K	2011-01-20 - 15:43	PedroRio
png	book_add.png	manage	0.7 K	2011-01-21 - 09:34	PedroRio
png	book_delete.png	manage	0.7 K	2011-01-21 - 09:34	PedroRio
Topic revision: r10 - 2011-04-04 - NicolauGrosskopf
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar