An example of xpages is used to develop a general dojo tree-style custom control.

Author: Zhan Yonghua,SoftwareEngineer,IBMChinaWplc
Yang zhilei, Senior Software Engineer, IBM China software development center wplc
Zhang Shijia, software engineer, IBM China software development center wplc

This topic describes how to use LotusDominoXpages in designer 8.5 develops a general tree view style custom control to display the hierarchy of Domino views. Through this article, readers can apply the next-generation xpagesTechnologyDevelop flexible and reusable custom controls in Domino-based Web applications, and learn how xpages easily applies the dojo toolkit and JavaScript. Class Library.

Background

This section briefly introduces the technologies used in this article. For more details, visit the websites of IBM or related organizations.

LotusSoftware trial download Download the latest IBM Lotus Notes and Domino trial software, and try to use xpage technology to develop the first Domino Web 2.0 application.Program. Download the trial version: Lotus Domino 8.5 Download trial: IBM Lotus Notes 8.5 and Domino designer 8.5

Xpages: powerful web design elements of Domino 8.5

Xpages is a powerful design element added to IBM Lotus Domino 8.5. It can be used to present the Web Client user interface for our project. Xpages utilizes a new JSF (JavaServerFace) rendering engine. Compared with traditional Domino web development, xpages is undoubtedly a powerful web design element.

Domino 8.5 provides users with a visual development environment integrated with Eclipse IDE. Using xpages to develop Domino-based Web applications, you can get the "What you see is what you get" user experience. For each page, control, and object in xpages, we can directly modify their attributes in a visualized manner and preview them instantly. Corresponding, events supported by objects, xpages also provides customized Wizard to help users edit andManagementEvent Response script.

Xpages has more advantages than DominoDatabase. We can create a "Data Source" for each page or Embedded Panel. This data source can be a document or view of the domino database. Then, you can dynamically bind the data in the data source, such as the file Domain value, to the object on the Web page through a simple operation. Of course, by writing scripts, we can also process the data computing before binding it to the page element.

Xpages provides flexibility for users who are used to developing agents to operate Domino data.ProgrammingAnd scalability. You can develop your own Java function libraries through integrated Eclipse IDE, and then use the server-side JavaScript supported by xpages to call these Java functions to generate the desired data for the client.

In this article, we will introduce how to develop a general xpages custom control using the dojo 1.1.1 toolkit included in xpages and Domino, and use the tree widget of dojo to display the hierarchical relationship of the traditional Domino view. In the process of introducing the method, we believe that users can appreciate the powerful functions and flexibility of the aforementioned xpages.

Domino View

The Domino view is a list of document sets. Its rich hierarchy and expressiveness make it a powerful tool for viewing Domino databases. Like the document, the domino view supports both the access method of the Notes client and the Web browsing method. (Open"View> allexpences", Select"Preview in a web browser".) The default Web View cannot meet the requirements of Web 2.0 users. What's more inconvenient is that its data source and page format are completely determined by the existing views in the database, and users cannot customize them flexibly. Therefore, many Domino Web application developers choose to develop their own web views. In traditional Domino web development, this is not an easy task.

Dojo and dijit. Tree

Domino provides the dojo toolkit, which can be found in the server's (C: \ IBM \ Lotus) \ domino \ data \ domino \ JS \ directory. By using the dojo toolkit in xpages, we can easily add Web 2.0 elements, such as widgets and animations, to xpage.

Dojo is a powerful object-oriented,Open Source. Dojo provides a large number of client components based on DHTML, CSS, JavaScript, and other technologies for Web application development. The initial goal of dojo project development is to solve the long-standing historical problems encountered during DHTML application development. For example, cross-browser issues. Therefore, using dojo makes it easier for your web pages to have dynamic capabilities, or to play a role in any robust environment that supports JavaScript. Language. While dojoCodeQuality, running performance, and documentation support are among the top priorities in similar development projects. The dijit. Tree object that will be applied in this article is the widget used in Dojo to display the tree hierarchy. The data source is in JSON format.

JSON

JSON (Javascript. Object Notation) is a lightweight data exchange format. Easy to read and write. It is also easy to parse and generate machines. It is based on a subset of JavaScript.

A json object is an unordered set of 'name/value' pairs. An object starts with "{" and ends. Each "name" is followed by a ":", and "," is used to separate the "name/value" pairs. A json array is an ordered set of values. An array ends with "[" and. Values are separated by commas. JSON values can be string, number, true, false, null, object, or array enclosed by double quotation marks ). These structures can be nested.

System Framework and Method

Before starting all the steps, we need to give a general introduction to the xpages elements involved in this chapter and their relationships. Such as the development and use of server/client JavaScript, Java, and CSS.

1. The domino database design elements on the server side and the elements during running on the client web page are listed. The DIV object on the xpage page will be parsed into the client's dojo object. As shown in the figure, we can also clearly see the definition of its data (1), Action (2), and appearance (3.

Figure 1. System Framework

Dojo object

On the xpage page, we define a div ing corresponding dojo object. There are two main ways to bind a div and a dojo object.

First, the 'dojobtype' attribute is directly used in the DIV to define the dojo object type. The following example defines a dijit. Tree object, which is also known as the dojo tree widget.

Listing 1. Defining a dojo object

<DivDojotype = "dijit. Tree"Id = "mytree" model = "continentmodel" showroot = "false"> </div>

Second, specify the div id on the xpges page, and then use the client JavaScript. dynamic binding is implemented through the Object ID during page loading. charting. the chart2d object is bound to a div object.

Listing 2. dynamically binding a dojo object

<! -- Xpage page --> <Div id = "piechart" style = "width: 250px; Height: 250px;"> </div> <! -- Client JavaScript --> var chart1 = new dojox. charting. chart2d ("piechart ")

Careful readers may find that in the above two examples, we directly use the <div> tag of HTML instead of the <XP: div> tag in xpages. This is not a casual choice. For the first method, we use the 'dojobtype' attribute, Which is the property definition accepted by the <div> tag, but is not the property definition accepted by the <XP: div> tag, an error will be prompted on the xpage. For the second method, if we use the <XP: div> label, the xpages engine will parse its ID attribute value into a view similar: _ id1: _ Id2: piechart format. In this way, in the dynamic binding stage, Dojo fails to bind because it cannot find the object whose ID is piechart. If you are interested, you can try the results of these two cases to better understand the HTML and xpage labels in xpages.

So,When adding a dojo object to the xpage page, you must use the HTML Tag.

Data

The data in this example comes from the domino view. In addition, the data can also come from Domino documents or other relational databases. Figure 1 (1) shows how to use the domino View data: Read the domino View data using the Java class and construct the data into the format required by the JSON schema of the dojo object; use server-side JavaScript. call the Java method to obtain the data and store it in the client JavaScript on the xpage page. variable.

Action

Figure 1 (2) shows the source of the client JavaScript For the dojo object action response: client JavaScript for this object and user-defined in the dojo package. In practical applications, users usually write client-side JavaScript to support client-side user events for the dojo object, suchOnclick,OnchangeAnd so on.

Appearance

Figure 1 (3) shows the source that determines the appearance format of the dojo object: the definition of the object appearance and the custom CSS in the dojo package. To change the default display format of the dojo definition, You need to redefine the CSS class file of the object by using the "overload" method.

Use the dojo tree to display the domino View

Part 1 of this article describes in detail how we extract data from the domino database and bind the data to the Tree View display. Let's follow the steps in Figure 2 "instance flowchart" to build a custom control for a dojo tree widget.

Figure 2. flowchart (View the larger image)

Obtain Domino view JSON data

The Domino view has its own JSON data. Using the URL Command Parameters, we can view the JSON data of the domino view. For a domino view that can be viewed from the web, you only need to add the parameter"? Readviewentries & outputformat = JSONYou can see its JSON format.

However, the JSON data of the domino view is inconsistent with the JSON schema of the dojo tree, so we cannot directly use the JSON data of the domino view as the data source of the dojo tree object. Domino view JSON Format 3 (a). To construct a dojo tree, JSON Format 3 (B) is required.

Figure 3. Domino view JSON and dojo tree JSON

We can use Java and server-side JavaScript to convert these two different JSON formats.

First, create a Java class to obtain the domino View data. Based on the eclipse platform, Domino designer 8.5 can easily create Java classes. We useWindow> open perspective> JAVA"Select the Java window.

Select your project tree. nsf on the right side and create related Java class files under the project. In this example, we create two classesTreenodeAndOrganjsonFor the code, see the appendix after this article. Where,OrganjsonClassGetorgantreeThe function implemented by the method is to convert the view hierarchy of Domino to the tree structure, and the return type isTreenodeThrough the root node of the tree, we can traverse all the nodes in the tree. The gettreejson method is implemented by the root node of the tree, and finally generate a JSON string that can be recognized by the dojo tree.

Then we create a server-side Javascript in designer to call the method in the created Java class. We useWindow> open perspective> Domino designerReturn to the workspace of the designer. In "code-> script. Library", select "create server Javascript. Library" to create the tree. JSS file. In this fileGetjsonstringFunction. In this method, we need to input the domino view name and the name of a column in the view. The column name is used for display in the tree structure, in this example, you can select the name column or the email column.

Listing 3. Javascript. gettreejson Function

Function getjsonstring (view, column) {var viewname: String = view; var columnname: String = column; var organjson: COM. IBM. test. tree. organjson = new COM. IBM. test. tree. organjson (); var organtree: COM. IBM. test. tree. treenode = organjson. getorgantree (Session, "tree. NSF ", viewname, columnname); var rgantreestr = organjson. gettreejson (organtree); Return organtreestr ;}

Bind Domino View data

Next we need to add the dojo data source on the xpage page, which is implemented through a computing domain. The Code is as follows:

Listing 4. Javascript. Obtain server data using the computing domain

<XP: Text escape = "false" id = "computedfield1"> <XP: This. value> <! [CDATA [# {JavaScript.: var viewname = compositedata. viewname; var columnname = compositedata. columnname; var JSON = getjsonstring (viewname, columnname); var result = "<script. language = \ "javascript \" type = \ "text/JavaScript \"> "result + =" Var jsonstore = new dojo. data. itemfilereadstore ({data: "+ JSON +"}); "result + =" </SCRIPT> "return result ;}]]> </XP: This. value> </XP: Text>

First, we get the attributes of the custom control passed in.ViewnameAndColumnname(For details about custom controls and attributes, refer to section 4th). Then, call the method in Javascript. On the server we created earlier.JSON = getjsonstring (viewname, columnname );To generate a data source in JSON format.

With the JSON data source, we only need to use the related APIs provided by the dojo tree on the control page to display our tree structure. Add the following standard HTML code to the source. WhereStore = "jsonstore"Is the jsonstore defined in the previous computing domain, that is, the data source used in this example.Query = "{Name: '0 '}"It is the root node we read from the data source jsonstore and uses it as the root element of the tree structure.<SCRIPT>Is the Action added to the leaf node. When you click the leaf node, an alert dialog box is displayed, showing the label content of the selected node.

Listing 5. the dojo object in xpage

<Div dojotype = "dijit. tree. foreststoremodel "jsid =" continentmodel "store =" jsonstore "query =" {Name: '0'} "> </div> <Div dojotype =" dijit. tree "id =" mytree "model =" continentmodel "howroot =" false "penonclick =" true "> <script. type = "dojo/method" event = "onclick" ARGs = "item"> alert ("execute of node" + jsonstore. getlabel (item) + ", population =" + jsonstore. getvalue (item, "Population"); </SCRIPT> </div>

Create custom controls

Create custom controls

In xpages, a custom control is a component that allows users to define, edit, and reuse on different xpages. It is similar to the "sub-template" in the domino template design, or the Panel in the Web page design. The difference is that it provides more powerful functions and customization. For example, you can drag and drop the "core control" of xpages and customize the control attributes; manage and allow users to reuse controls in drag-and-drop and custom ways. If some Web applications developed by users are used repeatedly, such as header, menu bar, Navigator, or, just as we are creating a general dojo tree that shows the domino view hierarchy, creating a reusable "custom control" is the best choice.

Right-click"Widget"Select"Create custom control"Cctree, 4. In the workspace, we canSource code. In the workspace, you can see the properties and events of the control. In the lower-right corner of the custom control management panel, cctree is listed in. When you want to create other xpage pages or custom controls, we can drag it into the workspace to reuse it. That is to say, Custom Controls Support nesting.

The custom control also allows you to customize attributes. When you use it, you can customize it by passing in different attribute values. The viewname and columnname in the figure are exactly the attributes defined for cctree. Viewname indicates the name of the domino view to be displayed, and columnname indicates the name of the column to be displayed in the tree structure.

Figure 4. cctree Custom Controls

To use the dojo tree element in xpages, You need to introduce the used dojo package into the control,Property> resource> Add script Library"Button to addDojo. parser,Dojo,Data,ItemfilereadstoreAndDijit. TreePackage. You can also choose to directly edit the source code.

Listing 6. Adding resources to xpage

<XP: This. resources> <XP: dojomodule name = "dojo. data. itemfilereadstore "> </XP: dojomodule> <XP: dojomodule name =" dojo. parser "> </XP: dojomodule> <XP: dojomodule name =" dijit. tree "> </XP: dojomodule> </XP: This. resources>

At the same time, in order to use the previously defined Javascript. Library, we also need to introduce it into the control, also through"Property> resource> Add script Library. Of course, you can also choose<XP: This. Resources>Add in<XP: script. src = "/tree. JSS" clientside = "false"> </XP: SCRIPT>Statement.

For the file content of the cctree custom control, see the attachment.

Reuse the cctree control in xpages

The custom control cctree we created can now be used. Let's see how convenient and flexible it is!

All we need to do is:

1. Create an xpage.
2. Drag the cctree control from the custom control panel into the work area (you need to switch to the design page to achieve drag and drop ).
3. Input parameters. Switch to the "source code" Page, find the control location, and add the domino view name and the column name to be displayed. The Code is as follows. In the database tree. nsf in this example, a view named contacts shows the contact list, where the name column is the contact name.
   

   <XC: cctree viewname = "contacts" columnname = "name"> </XC: cctree>

Then, preview the xpage and you will see the 5 (B) dojo tree chart, showing the hierarchy of the contacts view. The contact name is displayed on the leaf node. In this example, it is very easy to have the contact's email address displayed on the leaf node! In the above Code, set the columnname value to email. If you want to display other views, it is very easy to modify the viewname and columnname values in the above Code.

Example

In order to give readers a more intuitive understanding of the dojo tree custom control implemented in this article, we provide an example of 1. Figure 5 (A) is a web view supported by Domino by default. Figure 5 (B) is a view level of the dojo tree style generated in xpages using the custom control provided in this Article. This web page is more in line with the usage habits of Web 2.0 users. More importantly, it is provided to users in the form of xpages custom control, which is very easy to reuse and customize, and can be easily reused on any xpage, you can use a few parameters to display any domino view.

Figure 5. Example: Use the dojo tree to display the contact list

How to Use the source files in this article

Source files used in this article. Including:

1. Java function library and java files: organjson. Java, treenode. Java
2. Server-side Javascript. function library: tree. JSS (code> script. Library> tree)
3. Custom Control: cctree (custom control> cctree)

How to apply these source files:

1. Open Domino designer 8.5 and create a new database tree. nsf (if you want to preview in designer, copy tree. nsf to the data directory of notes ).
2. Switch to the Java perspective and copy the Java-class files organjson. Java and treenode. Java to the tree. nsf project directory.
3. Switch back to the desinger workspace, and customize the cctree and Javascript. function library tree. JSS controls to copy them to your database.
4. Add the cctree control to the xpage page of The cctree control to generate an "xpage page" according to section 4.2 and configure its parameters, displays the existing Domino view in your database.
5. Select"Design> preview in Web Browser".

Deployment to Domino server:

1. Copy tree. nsf to the data directory of the Domino server.
2. Access http: // (dominoserver host)/tree. nsf/tree. xsp from the browser.

   Conclusion

   This article uses an example to describe how to use xpages to develop a general dojo tree-style custom control to display the hierarchy of Domino views. Through this article, readers use xpages technology to develop flexible and reusable custom controls in Domino-based Web applications, and use and integrate the Javascript. Class Library of dojo.