XeoPrimerLibraryViewers < WebXEO

WebXEO Web>XeoPrimer>XeoPrimerLibraryViewers (2011-04-04, NicolauGrosskopf) (raw view)
-- Main.PedroRio - 17 Jan 2011
---+ XEO Library Viewers

In the [[WebXEO.XeoPrimerWebComponentsLibrary][previous chapter]] you created the list/edit/lookup viewers for the LIB_Author Object Model (without the need to create a specific Java Bean to implement custom behavior). In this chapter you'll create the remaining viewers and the respective Java Beans (when necessary) to implement custom behavior.

The first step to speedup the viewer creation is using XEO Studio's scaffolding tool as before to generate the basic structure for most of the viewers. Again, go to the "XEO Studio" menu, choose "Utilities" -&gt; "XEO Scaffolding", press "ok" to skip the warning and choose the LIB$1.0 Package from the list (if you had already customized the Author viewers you would have to be careful not to choose that Object Model, because Scaffolding overrides existing viewers)

If you do that, you'll have one folder for each Object Model created inside the _webapps/default/viewers_ folder. ( *Entries added to the Main.xvw viewer?*). Create a new entry in the Main_Library.xvw viewer for the list of books.

Just like in the previous chapter, add the following entry to the Main_Library.xvw, right bellow the entry for the list of authors:
<verbatim><xvw:menu text='Books'
           value="{viewerName:'LIB_Book/list.xvw', boql:select LIB_Book}"
           target='Tab' serverAction="#{viewBean.listObject}" /></verbatim>

You can leave the list viewer, for now, this part we'll focus on the Book's edit viewer. XEO Studio's Scaffolding will have generated an edit viewer that should look like the one depicted in figure LibViewers.1

<img width="800" alt="" src="%ATTACHURL%/LIBBookScaffolding.png" height="497" />

__Figure LibViewers.1 - The preview of the viewer generated by scaffolding to edit a LIB_Book instance__

As you can see in figure LibViewers.1, the attributes of a book are all displayed one beneath the other, and collection attributes are displayed as tabs. The general structure of this viewer is the following:
   * xeo:formEdit 
      * xvw:rows 
         * xvw:row and xvw:cell per xvw:attribute
      * xvw:tabs 
         * xvw:tab with xeo:bridge component
         * xvw:tab with xeo:bridge component

To give it a more clean look you'll rearrange the components and introduce some new ones, to achieve the result depicted in figure LibViewers.2 (and LibViewers.3).

<img width="800" alt="LibBookFinal.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerLibraryViewers/LibBookFinal.png" title="LibBookFinal.png" height="398" />

__Figure LibViewers.2 - Preview of the final result desired for the first tab (General)__

And the "Additional Information" tab will be like the one depicted in figure LibViewers.3

<img width="800" alt="LibBook2ndTab.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerLibraryViewers/LibBook2ndTab.png" title="LibBook2ndTab.png" height="427" />

__Figure LibViewers.3 - Preview of the final result desired for the second tab (Additional Information)__
---+++++ Building the viewer step-by-step

In order to give you a more in-depth view of composing a viewer, we'll create it step-by-step. First, start by removing all of the content generated by the Scaffolding tool (except the basic components _xvw:root_, _xvw:viewer_ and _xeo:formEdit_). Add a _xvw:tabs_ component (a tab container) under the _xeo:formEdit_. As child elements of the _xvw:tabs_ component, add two xvw:tab components (actual tabs) add the label property to each of them ("General" to the first and "Additional Information" to the second), the viewer definition should be like the following:
<verbatim><xvw:root xmlns:xvw="http://www.netgest.net/xeo/xvw" xmlns:xeo="http://www.netgest.net/xeo/xeo">
    <xvw:viewer beanClass="netgest.bo.xwc.xeo.beans.XEOEditBean" beanId="viewBean">
        <xeo:formEdit>
            <xvw:tabs>
                <xvw:tab label='General'></xvw:tab>
                <xvw:tab label='Additional Information'></xvw:tab>
            </xvw:tabs>
        </xeo:formEdit>
    </xvw:viewer>
</xvw:root></verbatim>

Use the built-in preview (remember to launch the project before) in XEO Studio to check the result. It will be like the one depicted in figure LibViewers.4.

<img width="712" alt="LibBookFinalTabs.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerLibraryViewers/LibBookFinalTabs.png" title="LibBookFinalTabs.png" height="536" />

__Figure LibViewers.4 - Preview of the LIB_Book edit viewer in XEO Studio__

Next you'll make creative use of the _xvw:rows_ component in order to put the book fields in the left side of the viewer and an image of the book cover in the right side. You can imagine the _xvw:rows_ component like a table, with several rows and columns. To achieve the desired effect you'll need to create a _xvw:rows_ component with one row and two (side-by-side) cells. The first cell will contain the all the attributes to fill and the second cell will have the book cover image. The trick to maintaining the structure is to reuse another _xvw:rows_ component in the first cell.

So the structure will be like the following for the "General" tab:
<verbatim><xvw:tab label='General'>
     <xvw:rows>
         <xvw:row>
             <xvw:cell><!-- Book fields will be here --></xvw:cell>
             <xvw:cell><!-- Book cover  will be here --></xvw:cell>
         </xvw:row>
      </xvw:rows>
</xvw:tab></verbatim>

Previewing in XEO Studio will not produce any result as the _xvw:rows_, _xvw:row_ and _xvw:cell_ components to not have any visible visual representation. To put the book fields in the *first cell*, use the following code:
<verbatim><xvw:cell>
           <xvw:rows>
                    <xvw:row><xvw:cell><xvw:attribute objectAttribute='title' /></xvw:cell></xvw:row>
                    <xvw:row><xvw:cell><xvw:attribute objectAttribute='isbn' /></xvw:cell></xvw:row>
                    <xvw:row><xvw:cell><xvw:attribute objectAttribute='state' /></xvw:cell></xvw:row>
                    <xvw:row><xvw:cell><xvw:attribute objectAttribute='publisher' /></xvw:cell></xvw:row>
                    <xvw:row><xvw:cell><xvw:attribute objectAttribute='frontCover' /></xvw:cell></xvw:row>
                    <xvw:row><xvw:cell><xvw:attribute objectAttribute='edition' /></xvw:cell></xvw:row>
          </xvw:rows>
</xvw:cell></verbatim>

Previewing the result in XEO Studio will be like depicted in figure LibViewers.5

<img width="798" alt="LibBookFinalFormFields.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerLibraryViewers/LibBookFinalFormFields.png" title="LibBookFinalFormFields.png" height="456" />

__Figure LibViewers.5- Preview of the edit viewer for LIB_Book with form fields__

To display the image stored in the frontCover attribute of LIB_Book you'll require the _xvw:attributeImage_ component which is designed to render an image file stored inside an attribute of type binary data. The attributeImage component requires an alternate image (in case the attribute does not contain an image). Google any image you like in google (or use the image "emptyImage" in annex) and save it in a new "Extras/Images" folder inside the default webapplication with the name "emptyImage.jpg".

Now put the following code inside the second xvw:cell component:
<verbatim><xvw:attributeImage width='100' height='180'
                    emptyImage='Extras/Images/emptyImage.jpg' objectAttribute="frontCover" /></verbatim>

The _xvw:attributeImage_ component requires the _objectAttribute_ property to know where to fetch the image to display and an _emptyImage_ attribute with the path to an image to display when no file is found in the _objectAttribute_.The _width_ and _height_ properties allow you to control the image's dimensions. If you preview the viewer in XEO Studio you'll see your image displayed. You can use the preview to interact with the viewer, choose an actual image for the front cover attribute and watch it display that image in place of the default emptyImage. This scenario is depicted in figure LibViewers.6

<img width="673" alt="LibBookFinalWithCover.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerLibraryViewers/LibBookFinalWithCover.png" title="LibBookFinalWithCover.png" height="508" />

__Figure LibViewers.6 - Image composition displaying the LIB_Book edit viewer with the xvw:attributeImage rendering the default image and a sample image for a given book.__

Having added a preview to the images you can now add the two collection attributes (authors and categories) to the first tab of the edit viewer. If you recall from figure LibViewers.2 in the "General" tab, you could see two inner tabs (with labels "Authors" and "Categories" respectively). To create inner tabs you use the same _xvw:tabs_ and _xvw:tab_ components, put them after the xvw:rows component, like the following:
<verbatim></xvw:rows> <!-- End of the rows component -->
    <xvw:tabs>
        <xvw:tab label="Authors"></xvw:tab>
         <xvw:tab label="Categories"></xvw:tab>                    
    </xvw:tabs>
</xvw:tab><!-- End of the "General tab" -->
<xvw:tab label='Additional Information'></xvw:tab></verbatim>

To display a collection attribute, you'll need the _xeo:bridge_ component (historically a collection attribute is also known as a bridge). The _xeo:bridge_ component, if used in a viewer tied to the WebXEO.XEOEditBean only requires you to set the _bridgeName_ attribute and the set of columns you want to be displayed from the instances in the collection. In the _authors_ collection attribute you'll only need to display the _name_ attribute (as it's the only attribute the LIB_Author Model has). The same is valid for the _categories_ collection attribute.

To use the _xeo:bridge_ collection for authors and categories use the following code:
<pre><verbatim><xvw:tab label="Authors">
    <xeo:bridge bridgeName="authors">
     <xvw:columns>
        <xvw:columnAttribute dataField="name"></xvw:columnAttribute>
     </xvw:columns>
  </xeo:bridge>
</xvw:tab>
<xvw:tab label="Categories">
    <xeo:bridge bridgeName="categories">
        <xvw:columns>
           <xvw:columnAttribute dataField="name"></xvw:columnAttribute>
       </xvw:columns>
   </xeo:bridge>
</xvw:tab>   </verbatim>
</pre>

The result after this update is depicted in figure LibViewers.7, bellow.

<img width="877" alt="LibBookWithCollections.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerLibraryViewers/LibBookWithCollections.png" title="LibBookWithCollections.png" height="625" />

__Figure LibViewers.7 - LIB_Book edit with first tab complete__

To finalize the viewer, you now only need to compose the "Additional Information" tab with the remaining attributes. From figure LibViewer.3 you can see that the "Additional Information" tab has the <em>backCover </em>attribute, the <em>summary </em>attribute as well as two labels for the <em>frontCover </em>and _backCover_. Those two labels, actually will be the labels for the _xvw:attributeImage_ component that you are going to use here, to display the front and back cover of the book. To build this tab, you'll again use the _xvw:rows_ component, this time with three rows, one for the back cover, one for the summary and one for the two images. Use the following code to achieve the result:
<verbatim><xvw:tab label='Additional Information'>
  <xvw:rows>
     <xvw:row>
        <xvw:cell><xvw:attribute objectAttribute="backCover" /></xvw:cell>
      </xvw:row>
      <xvw:row>
         <xvw:cell><xvw:attribute objectAttribute="summary" /></xvw:cell>
      </xvw:row>
      <xvw:row>
         <xvw:cell>
            <xvw:attributeImage width='200' height='360'
               emptyImage='' objectAttribute="frontCover" />
          </xvw:cell>
          <xvw:cell>
            <xvw:attributeImage width='200' height='360'
               emptyImage='' objectAttribute="backCover" />
           </xvw:cell>
     </xvw:row>
  </xvw:rows>
</xvw:tab></verbatim>

A small note about the html editor used for the _summary_ attribute. When one declares a long text attribute in an Object Model you can also select the type of editor used to edit that attribute's content. By default, a longtext attribute uses the HTML editor, but you can choose a simple textarea to edit the attribute's content. Open the LIB_Book Object Model, find the _summary_ attribute change the "Editor" property to "TEXT". Save the Object Model and return to the LIB_Book edit viewer to preview the changes, select the "Additional Information" tab and check that you no longer see the html editor, but instead a regular textarea, as depicted in figure LibViewers.8

<img width="800" alt="LibBook2ndTabNoHtmlEditor.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerLibraryViewers/LibBook2ndTabNoHtmlEditor.png" title="LibBook2ndTabNoHtmlEditor.png" height="237" />

__Figure LibViewers.8 - Summary attribute without the HTML editor.__

Since we used scaffolding to generate all of the viewers, the lookup viewer for the LIB_Publisher Object Model exists and you can now use it within the edit viewer of a book to select a publisher.

Next [[WebXEO.XeoPrimerWebComponentsLibraryPart2][you learn a bit about the Java API that's available when customizing viewers and components]].
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who
png	LIBBookScaffolding.png	manage	15.1 K	2011-01-18 - 14:07	PedroRio
png	LibBook2ndTab.png	manage	21.2 K	2011-01-18 - 14:25	PedroRio
png	LibBook2ndTabNoHtmlEditor.png	manage	20.6 K	2011-01-19 - 10:31	PedroRio
png	LibBookFinal.png	manage	41.4 K	2011-01-18 - 14:23	PedroRio
png	LibBookFinalFormFields.png	manage	12.7 K	2011-01-19 - 08:24	PedroRio
png	LibBookFinalTabs.png	manage	8.1 K	2011-01-18 - 14:54	PedroRio
png	LibBookFinalWithCover.png	manage	78.2 K	2011-01-19 - 09:03	PedroRio
png	LibBookWithCollections.png	manage	35.0 K	2011-01-19 - 09:53	PedroRio
jpg	emptyImage.jpg	manage	12.8 K	2011-01-19 - 08:41	PedroRio
Topic revision: r12 - 2011-04-04 - NicolauGrosskopf
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar