XeoPrimerWebComponentsIntro < WebXEO

WebXEO Web>XeoPrimer>XeoPrimerWebComponentsIntro (2011-04-04, NicolauGrosskopf) (raw view)
-- Main.PedroRio - 07 Jan 2011
---+ XEO Web Components Introduction

In order to finalize the XEO Library project you'll need the web pages (created with XEO's Web Components layer) to interact with the application. As explained in [[WebXEO.XeoPrimerConcepts#xwc][the introduction chapter]], XEO Viewers are containers for XEO Components which will render the webpage.<em><strong> Each XEO Viewer is associated with a Java class</strong></em> (a Bean, just like those used in JSF based applications); in that bean are the structures required by the components and the viewer itself for a successful render. Different types of Beans exist for the different types of Viewers in the XEO Framework, see figure XWC.1 for details.

<img width="960" alt="XWC_BeanHierarchy.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerWebComponentsIntro/XWC_BeanHierarchy.png" title="XWC_BeanHierarchy.png" height="720" />

__XWC.1 - XEO Bean Hierarchy (including custom Beans)__

As depicted in figure XWC.1, there are five different types of Beans supplied by the framework (XEOBaseBean, XEOBaseList, WebXEO.XEOEditBean, XEOMainBean and XEOBaseLookupList). Each of them is designed for a specific purpose, namely:
   * The XEOBaseList bean is suited to list instances which are selected through a XEOQL (BOQL) expression, usually in a list viewer.
   * The WebXEO.XEOEditBean allows to edit a specific instance object and is used in edit viewer.
   * The XEOBaseLookupList is used to create a listing of instances to allow selection of one instance.
   * The XEOMainBean is the bean for a Main viewer to allow opening tabs/windows with viewers.
   * The XEOBaseBean is (as the name suggests) the base bean for all other beans and provides the tools to create any custom viewer that does not fit any of the previous categories.

All of the previous beans, can (and should) be extended to provide the values to XEO Components when customizing a particular viewer.

XEO Components have properties and actions, both can binded to methods in a Java bean. Component properties are binded to Java getter methods (which return a value) and Component actions are binded to Java methods that are void (to execute an action, instead of returning a value). The following is a sample of a XEO Menu component declaration and the respective Java code in the bean (menu components are used in toolbars to create buttons, for example).

XML declaration*
<verbatim><xvw:menu text='#{viewBean.labelMenu}'
          serverAction="#{viewBean.execute}" />
            
</verbatim>

*Note, viewBean is the identifier of the Bean in the viewer, as depicted in the following line (declaration of the viewer):
<verbatim><xvw:viewer beanClass="netgest.bo.xwc.xeo.beans.XEOEditBean" beanId="viewBean"></verbatim>

Java Source Code
<verbatim>public String getLabelMenu(){ return "My Menu"; };</verbatim> <pre><verbatim>public void execute() { /* execute some code here */ };</verbatim>
</pre>

As you can see, Java EL ( [[http://developers.sun.com/docs/jscreator/help/2update1/jsp-jsfel/jsf_expression_language_intro.html][Expression language]]) is used to bind component properties and actions to Bean methods (just like in a JSF component). When a component property expects a value, you bind it with #{viewBean.<em>beanProperty</em>} and in the bean you're expected to have a "<em>getBeanProperty</em>()" method, while an action is binded to a void method in the Java bean.
---+++++ Opening a viewer from a Main Viewer

Main viewers are responsible for the workspace of a XEO Application. They define a tree structure of menus that can be opened in the application's workspace, those viewers can be list, edit or custom viewers. You'll start with an example, by creating a tiny custom viewer that will open in a Main viewer (which will be reused later in the Library project).

Fire up XEO Studio and select the XEOLibrary Project, go the "File" menu, and select "New" -&gt; "XEO Web Viewer", choose "Blank" from the list, press next and then type "MyViewer" as the name of the viewer (as depicted in figure XWC.2).

<img width="800" alt="CreateViewer.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerWebComponentsIntro/CreateViewer.png" title="CreateViewer.png" height="488" />

__Figure XWC.2 - Creating a blank viewer.__

XEO Studio uses a template to create the viewer, and in the blank case the code is the following (the viewer will be located in the:
<verbatim><xvw:root 
    xmlns:xvw="http://www.netgest.net/xeo/xvw"
    xmlns:xeo="http://www.netgest.net/xeo/xeo"
>
    <xvw:viewer beanClass="" beanId="viewBean">
        <xvw:form>
        </xvw:form>
    </xvw:viewer>
    
</xvw:root></verbatim>

<a name="prefixes"></a>

Every XEO Viewer will have a root element (xvw:root) where the namespaces to be used in the viewer are declared. By default the <em>xeo </em>and _xvw_ prefixes are declared so that all components provided by the XEO framework can be used. If you create custom components you'll probably create them in a different namespace and when you need to use them in a viewer, their namespace has be declared in the root element. The _xeo_ prefix is used for components which are tied (in some way) with XEO Model instances, while the _xvw_ prefix is used for components which do not require any Object Model instance to work properly. In this small example you'll only need _xvw_ components.

Each XEO Viewer declaration also requires two things. A viewer component and a form component. The viewer component (xvw:viewer) indicates the fully qualified name of the Java bean class (throug the _beanClass_ attribute), as well as its identifier (although, at the moment, the XEO framework only supports one bean identifier and it's _viewBean_, through the <em>beanId </em>attribute). The form component does not require any attributes, but it's required to allow component values to be passed to the bean.

In order to continue, you'll require a Java bean. Go to the "File" menu, select "New" and choose "Class". Fill the package with _org.example.viewers.beans_ and class name with _MyBean_, make it a subclass of _netgest.bo.xwc.xeo.beans.XEOBaseBean_, like depicted in figure XWC.3.

<img width="525" alt="CustomBean.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerWebComponentsIntro/CustomBean.png" title="CustomBean.png" height="626" />

__Figure XWC.3 - Creating a custom Java Bean for a viewer__

Return to the MyViewer.xvw file and fill the <em>beanClass </em>attribute with _org.example.viewers.beans.MyBean_ to 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="org.example.viewers.beans.MyBean" beanId="viewBean">
        <xvw:form></xvw:form>        
    </xvw:viewer>
    
</xvw:root></verbatim>

Ok, so now you're ready to add some components (which will binded to the bean to retrieve the values). Add two tab components. The first tab will have a text field (with a label) and a date field (also with a label) and the second tab will have nothing (just its label). The code to achieve is the following:
<verbatim><xvw:root xmlns:xvw="http://www.netgest.net/xeo/xvw" xmlns:xeo="http://www.netgest.net/xeo/xeo">
    <xvw:viewer beanClass="org.example.viewer.beans.MyBean"
        beanId="viewBean">
        <xvw:form>
            <xvw:tabs>
                <xvw:tab label='Tab1'>
                    <xvw:rows>
                        <xvw:row>
                            <xvw:cell>
                                <xvw:attribute label='Text' 
                                inputType="attributeText"></xvw:attribute>
                            </xvw:cell>
                            <xvw:cell>
                                <xvw:attribute label='Date' 
                                inputType="attributeDate"></xvw:attribute>
                            </xvw:cell>
                        </xvw:row>
                    </xvw:rows>
                </xvw:tab>
                <xvw:tab label='Tab2' />
            </xvw:tabs>
        </xvw:form>
    </xvw:viewer>
</xvw:root></verbatim>

As explained before, the form encapsulates all components. The first component is a "Tabs" component which is a container for "Tab" components (in this example there are two, each with a label ("Tab1" and "Tab2"). Inside the first tab, you'll use the Rows/Row/Cell component set (this allows to use a tabular layout which in the case of form fields gives it a nicer look). Inside each of the Cell components you have "attribute" components ( a generic form field which can be declared to be a text, number, date, datetime, longtext, file or html editor).

You can use XEO Studio's built-in Viewer Preview, just like depicted in figure XWC.4, to preview the layout of a viewer while designing the viewer (you'll have to [[WebXEO.XeoPrimerStudioIntroduction#launch][launch the project before that]], use this feature), just open the MyViewer viewer and press the "Preview" tab.

<img width="800" alt="MyViewer.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerWebComponentsIntro/MyViewer.png" title="MyViewer.png" height="658" />

__Figure XWC.4 - XEOStudio's Viewer Preview__

To make it more interesting add an _outputHTML_ component which will allow you to print html content inside the viewer and that content will be binded to a bean property to make more dynamic. Add the following to the viewer (bellow the _rows_ components):
<verbatim><xvw:outputHtml valueExpression = #{viewBean.html}></verbatim>

Next, add the following code to your bean.
<verbatim>private String html;
    
    public String getHtml(){
        
        String result = "<b>";
        result += Math.random();    
        result += "</b>";
        html = result;
        return html;
    }</verbatim>

This previous code will render a random number in bold each time the viewer is opened (or each time you change tabs), as you can see in the figure XWC.5 (highlighted in red).

<img width="800" alt="RandomValue.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerWebComponentsIntro/RandomValue.png" title="RandomValue.png" height="264" />

__Figure XWC.5 - Random value printed by the outputHtml component__

<strong><em>______</em></strong>

To open a viewer from a Main Viewer you'll first create it by using XEO Studio's wizards. Go to the "File" menu, choose "New" and "XEO Web Viewer". From the list of templates choose "Main Viewer" and press next. Name the viewer "Main_Library", *uncheck* the "create new profile" box (more on that later) and press finish. A Main_Library.xvw file will be created in the root of the viewers folder (webapps/default/viewers). To make things easier, the Main_Library viewer should be the default Main viewer. In order to change that open the XEOLibrary.xeoprofiles file in the uidef/default directory and change the following line:
<verbatim><profile viewer="Main.xvw" id="Library" description="Library Profile"/></verbatim>

to
<verbatim><profile viewer="Main_Library.xvw" id="Library" description="Library Profile"/></verbatim>

This will make that the default Main viewer is now the newly created Main_Library.xvw viewer (when a user logins with the "Library Profile"). To see the result, launch the application and login with SYSUSER/ABC and the Library Profile, it should be like the one depicted in figure XWC.6.

<img width="800" alt="Main_Library.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerWebComponentsIntro/Main_Library.png" title="Main_Library.png" height="299" />

__Figure XWC.6 - Main Library Viewer__

If you open the Main_Library.xvw viewer, you'll see a set of elements (which will be explained later), but the important ones are the _xvw:treePanel_ component and the set of _xvw:menu_ components. The _xvw:treePanel_ component is responsible for creating the tree structure while the _xvw:menu_ components are the entries in the tree. Nested _xvw:menu_ elements are used to create groups (folders) and each _xvw:menu_ entry can be restricted to a given profile (that's why the template for the Main_Library.xvw file has lots of xvw:menu entries but when you login, you only see four of the them (the Welcome and XEO Developers folder, and the "Welcome Page" and "XEO Model Builder" entries). In figure XWC.7, highlighted in blue, are the two menu entries that you see when you login (the two folders); highlighted in red is the menu entry which is associated with the "admin" profile. If you login with SYSUSER/ABC, choose the XEO Administration profile and then point your browser to the "Main_Library.xvw" file you'll be able to see the rest of the entries.

<img width="716" alt="MainViewerXML.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerWebComponentsIntro/MainViewerXML.png" title="MainViewerXML.png" height="252" />

__Figure XWC.7 - Main_Library.xvw XML definition (elements are collapsed for readability)__

For the Main_Library viewer you'll want to arrange things in a different way, replace the contents of the _xvw:treePanel_ component with the following:
<pre><verbatim><xvw:treePanel renderComponent='false' id='tree'>                
                <xvw:menu text='MyViewer'
                         value="{viewerName:'MyViewer.xvw'}" 
                        target='Tab' 
                        serverAction="#{viewBean.openViewer}">
                </xvw:menu>
</xvw:treePanel></verbatim>
</pre>

Just to explain things a bit, this _xvw:menu_ configuration creates a "leaf" node (i.e. not a folder) which will open the MyViewer.xvw viewer in a new tab. There are different <em>serverActions </em>available for this component but we'll get in to that later. If you now login to the application (with the Library Profile) you will see a single menu (named "<em>MyViewer</em>"), which if you click, will open a tab with the MyViewer viewer, as depicted in the figure XWC.8.

<img width="796" alt="Main_Library_Arranged.png" src="http://wiki.itds.pt/pub/WebXEO/XeoPrimerWebComponentsIntro/Main_Library_Arranged.png" title="Main_Library_Arranged.png" height="177" />

__Figure XWC.8 - MyViewer opened in Main_Library.xvw__

This menu entry will not be reused for the Library application, it was just used to show how to open a viewer in a Main viewer. This completes the introduction to XEO Web Components and Viewers. [[WebXEO.XeoPrimerWebComponentsLibrary][The next step will be developing the Library application's viewers]].
<div style="position: absolute; left: -10000px; top: 2946px; width: 1px; height: 1px; overflow: hidden;" id="_mcePaste"> <verbatim><xvw:root 
    xmlns:xvw="http://www.netgest.net/xeo/xvw"
    xmlns:xeo="http://www.netgest.net/xeo/xeo"
>
    <xvw:viewer beanClass="" beanId="viewBean">
        <xvw:form>
        </xvw:form>
    </xvw:viewer>
    
</xvw:root></verbatim> </div>
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who
png	CreateViewer.png	manage	38.7 K	2011-01-11 - 15:31	PedroRio
png	CustomBean.png	manage	19.9 K	2011-01-11 - 16:19	PedroRio
png	MainViewerXML.png	manage	7.5 K	2011-01-13 - 09:40	PedroRio
png	Main_Library.png	manage	5.3 K	2011-01-13 - 09:09	PedroRio
png	Main_Library_Arranged.png	manage	5.9 K	2011-01-13 - 09:58	PedroRio
png	MyViewer.png	manage	8.7 K	2011-01-12 - 10:05	PedroRio
png	RandomValue.png	manage	4.4 K	2011-01-12 - 18:03	PedroRio
png	XWC_BeanHierarchy.png	manage	16.9 K	2011-03-11 - 09:12	PedroRio
Topic revision: r17 - 2011-04-04 - NicolauGrosskopf
No permission to view TWiki.WebTopBar
No permission to view TWiki.WebBottomBar