Using the IGS in Web Dynpro Java

Web Dynpro - Using the Internet Graphics Server in Web Dynpro Java

SAP DEVELOPER NETWORK | sdn.sap.com BUSINESS PROCESS EXPERT COMMUNITY | bpx.sap.com © 2007 SAP AG 1


Applies to SDN Training Material

Summary This document is not intended to act as a comprehensive guide to all the possible features of how the SAP Internet Graphics Server (IGS) can be used from Web Dynpro. Rather, it is designed to communicate the principles of how Web Dynpro programs can use the IGS to generate graphical content, and to give you enough information to incorporate such graphics into your own Web Dynpro applications. Author(s): Chris Whealy Company: SAP AG Created on: 24 October 2006

Author Bio Chris Whealy has more than 20 years experience on Computer Science. He has worked with SAP software since 1993 and specifically with web based interfaces since 1996. In late 2002, Chris turned his attention to Web Dynpro and by October 2003, was able to put his knowledge into practice when he started work as the lead technical consultant for a large Web Dynpro based project. Chris is the author of the SAP Press book "Inside Web Dynpro for Java" published in November 2004 and both the SAP training courses on Web Dynpro for Java (JA310 and JA312)



Introduction ...................................................................................................................................... 3

Assumptions................................................................................................................................. 3 Graphics and screen shots .......................................................................................................... 3 Further information....................................................................................................................... 3

The business scenario..................................................................................................................... 4 Let’s get started! .............................................................................................................................. 5

Create a new Web Dynpro project............................................................................................... 5 Create a new Web Dynpro Component ....................................................................................... 5 Create a new Application ............................................................................................................. 6 Build the context in the Component Controller ............................................................................ 6 Map the view controller’s context to the component controller .................................................... 7 Editing the view layout ................................................................................................................. 7 Writing the code to generate the sales data .............................................................................. 10 Deploy and run........................................................................................................................... 11

How to improve your chart............................................................................................................. 12 Opening the chart designer........................................................................................................ 12 Using the Chart Designer........................................................................................................... 13 The finished result...................................................................................................................... 16

How to avoid creating chart junk ................................................................................................... 17 Why create graphs at all? .......................................................................................................... 17 What is graphical excellence? ................................................................................................... 17 So, what’s the problem?............................................................................................................. 18 Things to avoid when creating charts ........................................................................................ 19 Summary of the principles of graphical excellence.................................................................... 21

Copyright........................................................................................................................................ 22



Introduction

Assumptions

The following assumptions have been made:

• You have already installed an SAP J2EE Engine version 6.40 SP10 or higher. • You have already installed the IGS and configured your J2EE Engine to communicate with it. • You have already installed the NetWeaver Developer Studio. • You already have at least a basic familiarity with writing applications using Web Dynpro for Java.

Certain elementary steps will not be described in this guide; such as general navigation around the NetWeaver Developer Studio.

Graphics and screen shots

Certain screen shots shown in this document may have been cropped in order to reduce the amount of empty image space and the overall document size. Only those areas of the screen that carry relevant information have been included in screen shots. Therefore, it is entirely possible that the image you see on the printed page is different in size from the corresponding screen seen in the NetWeaver Developer Studio.

Further information

Further information is available from the following sources:

• For information on installing and configuring the Internet Graphics Server, please refer to the IGS installation guide. Alternatively, work through the e-Learning training course JA314 “The Internet Graphics Server”.

• For detailed information about using the Web Dynpro toolset to develop business applications, get a copy of the book Inside Web Dynpro for Java by Chris Whealy, published by SAP Press, Bonn, Germany, 2004. http://www.sap-press.com or http://www.sap-press.de

• For information about the principles of graphical excellence, please get a copy of the book The Visual Display of Quantitative Information by Edward R. Tufte, published by Graphics Press, Cheshire, Connecticut, 1989. http://www.edwardtufte.com

For further training courses on Web Dynpro development, please attend the SAP training course JA310 “Introduction to Web Dynpro”



The business scenario

You have been asked to create a simple Web Dynpro application that can compare sales figures from three rival companies from the last financial year. For simplicity, you decide that the easiest way to show this information is as a bar chart, showing three bars per month.

Figure 1: Here’s what the finished graph could look like

The sales figures for each company are shown grouped together by month. This makes it easy to compare how each company has performed against its rivals on a month by month basis.



Let’s get started!

Create a new Web Dynpro project

The first step is to create a new Web Dynpro project:

Figure 2: Create a new Web Dynpro project

After opening the NetWeaver Developer Studio, create a new Web Dynpro Project. Since we are building a small application that serves only as a training exercise, we will use a Web Dynpro Project, rather than a Web Dynpro Development Component. When you come to build a Web Dynpro Application in a team environment, you should always use a Development Component of type “Web Dynpro” instead of a Web Dynpro Project.

Create a new Web Dynpro Component Within the new Web Dynpro project, create a new component.

Figure 3: Create a new Web Dynpro Component



Create a new Application

Since a Web Dynpro Application is the entry point into a Web Dynpro Component. We must create a new Application otherwise we would never be able to invoke the functionality found in our component.

Figure 4: Create a new application

Since there is only one component in this Web Dynpro Project, no selections are necessary on the subsequent screens in this wizard; therefore, you can press finish immediately.

Build the context in the Component Controller

The context is where all Web Dynpro controllers store their data at runtime. The structure of the context must be declared before any data can be stored there, and since we know a priori what our data structure will be, we can declare our context structure at design time. (If the structure of your data is not known until runtime, then this is no problem – you can create context data structures at runtime). In the component controller, create the following node and attribute structure:

• Create a new value node called GraphData. • Ensure that this node’s cardinality remains set to the default value of 0..n. • Now add four value attributes to the GraphData node as follows:

o Add a string attribute called Category. o Add three decimal attributes called Company1Sales, Company2Sales and

Company3Sales.

Your context structure should now look like this

Figure 5: Context structure of the component controller



Map the view controller’s context to the component controller

By double clicking on the component name SalesFiguresComp itself; the data modeller tool will open. Use this to create a data link between the view controller and the component controller. When the context mapping wizard opens, select the entire GraphData node, and drag it across to the root node of the view controller. Select all the attributes, press OK and then Finish.

Now that the view controller has full access to all the data contained within the GraphData node in the component controller’s context, we are ready to create the UI elements that will be seen on the screen.

Editing the view layout

Adding a BusinessGraphics UI element

After closing the data modeller tool, open the view designer by double clicking on the view name SalesFiguresView. In the Layout tab, add a new BusinessGraphics UI element.

Select the “Add Child” menu option from the RootUIElementContainer in the Overview window as follows:

Figure 6: Add a new BusinessGraphics UI element

Once added, your view layout hierarchy will be as follows:

Figure 7: The BusinessGraphics UI Element added to hierarchy

The DefaultTextView UI element can be deleted if you wish.

Now select the BusinessGraphics UI element and select its properties. In order for this UI element to function correctly, certain properties must be set correctly. Some of these property settings are mandatory, whilst other properties are optional, simply adjusting the appearance of the graph.

You can see from Figure 8 what the basic settings of the BusinessGraphics UI element will be.



Figure 8: BusinessGraphics properties

The most important property setting is the seriesSource property. This property defines the context node from which the BusinessGraphics UI element will obtain its data. You will notice that before any value has been placed into this property, it has a red “X” icon next to it. This indicates that a value for this property is mandatory.

The chartType property will default to “columns”; therefore, it is not necessary to modify this value.

In order to make the graph more legible, the height and width properties are increased from their default value of 300 pixels to 480 and 600 respectively.

Once the properties of the BusinessGraphics object are defined, you are now ready to define the various child UI elements.

Defining a Category UI element

A BusinessGraphics object is known as a composite UI element; this means that child UI elements must also be defined in order for it to function correctly. In our case we are going to add two types of child UI element – one Category UI element, and three SimpleSeries UI elements.

The Category UI element is optional insomuch as the BusinessGraphics UI element will be able to function without it; however, it should always be included for completeness. As shown in Figure 9, a Category can be added by selecting the BusinessGraphics object, and then selecting “Insert Category” from the right mouse-click pop-up menu.

The Category UI element describes what type of information will be displayed along the horizontal, or “X” axis. In our case, we will be displaying sales figures for each month of the preceding year. Therefore, the category here will be months.



Figure 9: Inserting a category into the BusinessGraphics UI element

Once the category UI element has been added, it must have its description property configured. If you forget this stage, then the categories along the “X” axis will have default labels – which will not be very helpful for the user!

Figure 10: Binding the description property to the context

Since the context attribute Category holds the names of the months, this is a suitable attribute to act as the data source for the description property.

Defining SimpleSeries UI elements

A BusinessGraphics UI element always requires the use of at least one series UI element. In our case, we are comparing the sales figures from three different companies; therefore we require three series UI elements.

Figure 11: Inserting a SimpleSeries UI element

Each series UI element must be of type SimpleSeries and describes one company’s sales values.

In Figure 8, we can see that the seriesSource property of the BusinessGraphics UI element was bound to the context node GraphData. This indicates that all the series UI elements declared under this BusinessGraphics UI element will obtain their data from the context node GraphData.



Figure 12: Configuring the value property of each SimpleSeries UI element

For each of the three SimpleSeries UI elements that you created, bind the value property to the corresponding Company[1,2,3]Sales context attribute.

Writing the code to generate the sales data

Up till now, the only configuration we have performed has been declarative. However, there is one part of this application that cannot be defined in this manner; namely, the coding to generate the sales figures. In this example, we are going to bypass reality and use a random number generator to create the sales figures.1 The coding should be placed into the component controller: public void wdDoInit() { //@@begin wdDoInit() Random rnd = new Random(); // Get a reference to the GraphData node IGraphDataNode gdNode = wdContext.nodeGraphData(); // Create 12 elements for each month's sales figures for (int i=0; i<12; i++) { IGraphDataElement gdEl = gdNode.createGraphDataElement(); // Set the category value to the name of the current month switch(i) { case 0: gdEl.setCategory("January"); break; case 1: gdEl.setCategory("Febrary"); break; case 2: gdEl.setCategory("March"); break; case 3: gdEl.setCategory("April"); break; case 4: gdEl.setCategory("May"); break; case 5: gdEl.setCategory("June"); break; case 6: gdEl.setCategory("July"); break; case 7: gdEl.setCategory("August"); break; case 8: gdEl.setCategory("September"); break; case 9: gdEl.setCategory("October"); break;

1 I assume we are bypassing reality here! ;-)



case 10: gdEl.setCategory("November"); break; case 11: gdEl.setCategory("December"); default: } // Generate random numbers for the sales figures(!) gdEl.setCompany1Sales(new BigDecimal(100*rnd.nextDouble())); gdEl.setCompany2Sales(new BigDecimal(100*rnd.nextDouble())); gdEl.setCompany3Sales(new BigDecimal(100*rnd.nextDouble())); // Add the new element to node collection gdNode.addElement(gdEl); } //@@end }

Textbox 1: Coding to generate sales figures

There are several things to notice about this coding:

1. The coding has been placed inside the wdDoInit() method of the component controller. This means that this section of code will only be executed once per lifecycle of the component.

2. Since we are using a random number generator, you will never see the same graph twice! 3. Even though the coding is writing data to the GraphData node in the context of the component

controller, this node is acting as the mapping origin for a node of the same name in the view controller’s context. Therefore, the UI elements in the view layout have direct access to the data in the component controller’s context because of the following chain of relationships:

a. The UI elements are bound to nodes and attributes in the view controller’s context. b. The nodes and attributes in the view controller’s context are mapped to corresponding nodes

and attributes in the component controller’s context.

Deploy and run

The final stage is now to deploy and run your application.

Figure 13: Deploy and run new application

You finished result will look something Figure 1. But remember, we’re using random numbers, so you’ll get a different shaped graph each time you run the application.



How to improve your chart

The chart that appears in Figure 1 is OK in as much as it shows the business data in the required format. However, there are several improvements that can be made to the presentation. The graph in Figure 1 has the following shortcomings:

1. It has no title. 2. Some of the month names are too long and so have been wrapped. 3. The grey background is just plain dull!

All of these shortcomings need to be addressed in order to make the information more presentable. The only problem is if you examine the properties of the BusinessGraphics, SimpleSeries and Category UI elements in the view designer, you will not find any properties to control these objects in the required manner. This is where we need to look at using the Chart Designer.

Opening the chart designer

In order to open the chart designer tool, right mouse-click on the BusinessGraphics UI element and select “Start Chart Designer”.

Figure 14: Starting the chart designer

Since the Chart Designer displays quite a large amount of information, it is usually helpful to maximize the editor window. This is done by double clicking on the Chart Designer tab at the top of the editor view. Using the Chart Designer we will change the default font family, give the graph a title, change the background colour and rotate the category text in order to prevent it wrapping.



Using the Chart Designer

Figure 15: The Chart Designer

The Chart Designer is an additional editor within the Web Dynpro View Designer that allows you full design-time access to the properties of a business graphics object.

In the top right-hand corner of the screen, you can see an overview area from which all the various property types can be accessed. Underneath the Overview is an area that displays the values of the currently selected property type. The default property type is “Global settings”. Some of the properties shown in “Global settings” can also be changed without needing to open the Chart Designer. Examples being “Chart type”, “Dimension” and “Font family”. The graph image shown on the left of the editor screen is a generic representation of the chart type currently selected. If you change the chart type, then the both generic image and the list of property types will change to reflect the currently selected chart type.

Changing the font family

In the overview area, select the “Global settings” property type and then change the “Font family” property to Tahoma. This defines the default font for all text in the graph. See Figure 16.

Figure 16: Font family



Adding a title

Next, scroll down the list of property types, until you find “Title”. Select this Property type and a new set of properties will appear in the property area underneath. Make sure that the “Visibility” and “Align to plot” check boxes are switched on, and then enter a text value in the “Caption” property. In our case, we will enter the value “Comparison of monthly sales figures”. Some of the property types contain property sub-types. For instance, any time the properties controlling the appearance of text are listed, they are gathered together into the sub-type “Text properties”. Expand the “Text properties” sub-type and change the “Size” property to 12 and the “Style” property to Bold.

Figure 18: Adding a title

Changing the background colour

Now locate the property type “Background” in the overview area. All the properties that control the appearance of a plot or background area are gathered together into the sub-types “Area properties” and “Border properties”. In our case we want to change the colour of the background plot area. Therefore, expand the “Area properties” sub-type, and locate the “Colour” property. There are a variety of ways to enter colour information. You can enter it in the form of an RGB2 triple in either decimal or

2 RGB stands for Red Green Blue

Figure 17: Background Colour



hexadecimal format using either 12 bits or 24 bits. If you enter the hexadecimal values, they will be converted to the decimal RGB triple form automatically. If you do not know the decimal or hexadecimal colour values, then you can choose a colour from the colour picker that will appear when you press the down arrow to the right of the input field. In our case, we are going to use an off-white colour which is easiest to enter in hexadecimal format. In the “Color” property, enter the “Hash” or “Pound” symbol followed immediately by the letters FF FF EE. Now locate the property type “Plot area” in the overview area. In order to make the plot area of the chart stand out from the background, we must ensure that it is white. Therefore, expand the “Area properties” sub-type, and locate the “Color” property. Enter the “Hash” or “Pound” symbol followed immediately by FF FF FF. This is hexadecimal value for pure white.

Changing the text direction

Next locate and expand the property type “Category axis” in the overview area. We are interested in the properties that control the labelling of the X axis, therefore select the “Line” property type. Make sure that the “Wrap texts” check box is switched off, and that the “Direction” property is set to DiagonalUp. These are all the configuration changes needed to put the finishing touches to our graph. All that remains now is to deploy a new archive to the J2EE Engine and run the application.

Figure 19: Text direction



The finished result

Figure 20: The finished result

As you can see, the adjusted graph is much easier to comprehend, and all we did was make a few adjustments to some small details. The raw data of the sales figures has now been transformed into graphical information that is clear, simple, and easy to understand. However, this is not always the case…



How to avoid creating chart junk

Why create graphs at all?

A graph is a very useful tool for transforming raw data into intelligible information – particularly when there are a large number of data samples involved. The purpose of a chart is to allow the viewer to comprehend the information hidden within the data in the simplest and quickest manner. Therefore, charts and graphs should always be designed with viewer comprehension in mind.

What is graphical excellence?

Graphical excellence3 is the result that can be achieved if, when designing a chart or graph, it communicates:

• The greatest number of ideas • With the least amount of ink • In the shortest possible time • In the least amount of space

Probably the best example of a statistical graph ever produced was done by Charles Joseph Minard in 1869 when he depicted the losses suffered by Napoleon’s army during the Russian Campaign of 1812-13. Six dimensions of data are represented here:

• The size of the army • Its location in two dimensions • Its direction of travel • The temperature during the retreat

3 As defined by Edward R. Tufte in his book The Visual Display of Quantitative Information, Graphics Press, Cheshire, Connecticut, 1989.

Figure 21: Losses suffered by Napoleon’s

army in 1812



We are not suggesting that the IGS is capable of generating the type of graph shown in Figure 21, but it has been shown to illustrate that with some careful thought and design, six dimensions of data can be represented with great clarity and simplicity.

So, what’s the problem?

With the increased demand for statistical information, came the increased desire to jazz up the manner in which that information is presented. This led directly to the phenomenon known as “Chart Junk”. A graph or chart falls into the “Chart Junk” category if the information it contains is obscured, hidden or misrepresented by the manner in which the data is presented. If you apply the principles of graphical excellence when designing your charts and graphs, you will always be able to avoid the creation of chart junk. Here are two examples in which the data in the chart remains unchanged, but the presentation of the second chart causes the viewer to have to look more carefully in order to find the information.

Figure 22: Simple, clean and easy to read

Figure 23: Distracting, complex and harder to read

The point here is that there is no difference between the data in Figure 22 and Figure 23. However, this rather extreme example shows how the poor choice of background textures, gradient fills and colours can reduce the viewers ability to perceive the information contained within the data.



Things to avoid when creating charts

Distracting backgrounds and gradient fills

As Figure 22 and Figure 23 show unless background textures and gradient fills are chosen very carefully, they will distract the user from seeing the information contained within the data. A background should provide a canvas that causes the information to present itself to the user, rather than the user having to go hunting for the information through the dense undergrowth of the textured background.

Adjacent non-complementary colours

Figure 24: Non-complementary colours occur on opposites sides of the colour circle

Colours that are located on opposite sides of the colour circle will create an optical illusion if placed next to each other. At the border of these chromatic opposites, your brain will perceive an extra, third colour which can sometimes appear to jitter or jump around. Such colour pairs should not be placed next to each other.

Large areas of block colour

Figure 25: Avoid large areas of block colour

On the whole, you should avoid using chart types that will result in large areas of block colour. The exception to this rule is where you wish to illustrate a striking contrast between the values in a dataset. Normally speaking however, if you only have two or three values to display, then it is not appropriate, for instance, to choose a pie chart as your chart type.



Unnecessary use of the third dimension Finally, the unnecessary use of the third dimension is a crime that almost everyone who has produced a chart is guilty of! Since modern chart software makes it is so easy to add 3D effects to a graph, many people use the effect thinking that it will somehow give the information extra impact or depth. This is not true at all! The truth is that people use 3D effects either for novelty value or through habit.

Figure 26: An appropriate use of a 3D graph

Figure 27: An inappropriate use of a 3D graph

If the data in your dataset varies in only two dimensions, then attempting to represent that dataset in three dimensions (particularly if the third dimension varies), does not add to the clarity or efficiency of the chart. Such a chart will present the information in a weaker manner and possibly lead to ambiguity of perception. The principle that should be obeyed here is the following:



The number of depicted dimensions should not exceed

the number of dimensions in the data.

Summary of the principles of graphical excellence

To summarise the principles of graphical excellence, the most fundamental principle is this:

MAKE EVERY PIXEL COUNT! If you find yourself adding colours, textures, gradient fills or 3D effects simply because you can, or you’re bored, then stop, and rethink your design. Ask yourself whether the addition a gradient fill or a textured background actually adds to the graph’s clarity and simplicity. If it does, then use it; otherwise, leave it out. As a chart designer, your job is to transform raw data into graphical information that can be understood quickly, efficiently and with simplicity. Anything that detracts from this objective is just Chart Junk!



Copyright © Copyright 2007 SAP AG. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice.

Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.

Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation.

IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix, i5/OS, POWER, POWER5, OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation.

Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Oracle is a registered trademark of Oracle Corporation.

UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group.

Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc.

HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology.

Java is a registered trademark of Sun Microsystems, Inc.

JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape.

MaxDB is a trademark of MySQL AB, Sweden.

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.

These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

These materials are provided “as is” without a warranty of any kind, either express or implied, including but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement.

SAP shall not be liable for damages of any kind including without limitation direct, special, indirect, or consequential damages that may result from the use of these materials.

SAP does not warrant the accuracy or completeness of the information, text, graphics, links or other items contained within these materials. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third party web pages nor provide any warranty whatsoever relating to third party web pages.

Any software coding and/or code lines/strings (“Code”) included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAP intentionally or grossly negligent.

Documents

Using the IGS in Web Dynpro Java