B.1 Bind Task Examples

This section discusses how the underlying SVG/XML level works. When you understand how these tasks are accomplished at the XML level, you’ll be in a much better position to understand what’s working or not working, and why that is so. And, you’ll be able to create custom visualizations and interactions much more easily.

B.1.1 Adding Tooltips or Pop-Ups to Portlets in the Dashboard

In the dashboard, the Layout portlet is used to display the same information (or drawings) that you have in the console’s Layout view. You can modify the Layout view drawing code to leverage tooltip and pop-up functionality in the dashboard.

The following sections cover adding tooltips or pop-ups to portlets. This functionality applies to the dashboard.

Tooltips for the Layout Portlet

A tooltip can be displayed when the mouse is hovered over a specific element in the Layout portlet in the dashboard. For more information about the Layout portlet and the dashboard, see the Operations Center 5.6 Dashboard Guide.

Although the tooltip is created in the Layout View, it cannot be displayed in a Layout View drawing in the Operations Center console.

The tooltip must be manually inserted into an SVG drawing. The mechanism to create the tooltip requires a specific structure as follows:

<g tooltiptype="outer" preserveId="true" display="none">
<g id="uniqueid" tooltiptype="inner" preserveId="true" display="inline" timeout="7000">
    <…tooltip content goes here…>
   </g>
 </g>

This structure consists of an inner and an outer SVG Group object. The purpose of the outer Group object is to hide the inner Group object when the tooltip should not be displayed. A different mechanism directly refers to the inner Group object when it is time to display the tooltip.

The outer group must have a tooltiptype of "outer" and the inner group must have a tooltiptype of "inner". Both groups must have the preserveId set to True. The display attribute is required for both groups. The outer group could toggle the display attribute from "none" to "inline" at design time in the Operations Center console in order to preview how the tooltip can render. The inner group must have display set to "inline". The inner group can supply an optional attribute called timeout, which sets the display time of the tooltip in milliseconds. The default timeout value is 5000 milliseconds. The inner group MUST have an id that is unique within the current document. The tooltip is referenced by this id.

The tooltip content can be very flexible, but because the Layout portlet renders the Layout contents as a snapshot, each tooltip must be constructed at rendering time by the dashboard to ensure the tooltip is fully rendered. The tooltip contents can also display “bound” element data. The element that is “bound” is determined by the currently inherited “dname” value where the tooltip structure is defined.

The tooltip for a drawing item is determined by walking up the parent XML hierarchy. At each parent level, if a group object with “tooltip” set to “outer” is encountered as a child of that parent, this tooltip is used. The tooltip cannot be an immediate child of the <svg> root drawing element.

Figure B-1 shows a simple tooltip showing an element’s “name” when the mouse is hovered over the rectangle:

Figure B-1 Tooltip Displayed in a Layout Portlet in the Dashboard

The tooltip in the example is defined as follows:

<svg dname="org=SimpleRectangle/org=tooltip/org=testing/root=Organizations" MOS_EnableMouseEvents="true">
  <g>
    <rect stroke="#000000" stroke-linecap="butt" width="245" fill="rgb(128,128,128)" stroke-dasharray="none" filter="none" stroke-width="3" height="141" undofill="#c0c0c0" x="0" stroke-linejoin="miter" opacity="1" y="0">
      <bind:fill property="condition" default="" set="" when=""/>
      </rect>
    <g tooltiptype="outer" preserveId="true" display="inline" transform="matrix( 1, 0, 0, 1, 95, 75)">
      <g tooltiptype="inner" id="rect_caption" preserveId="true">
        <g>
          <rect x="-15.847" y="57.862" fill="white" text-anchor="middle" width="86.1938" height="16.289" bind:container="true" stroke="gray" overflow="visible"/>
          <bind:layout name="wrap" pad="2" id="103"/>
          <text x="27" font-size="11px" y="70" fill="black" text-anchor="middle" gautolayout="103" stroke="none" overflow="visible" xml:space="preserve">SimpleRectangle<bind:value property="name"/></text>
          </g>
        </g>
      </g>
   </g>
  </svg>

In this example, the rectangle and the tooltip outer group element are wrapped inside of another group element. This is done because of how the tooltip is determined by walking up the parent XML hierarchy.

Some of the root <svg> attributes have been omitted for this example. However, there is a required attribute on the root <svg> element. This is the MOS_EnableMouseEvents, which must be set to True in order to activate the mouse handling mechanism in the Layout portlet in the dashboard.

Tooltips can also use node styles as the tooltip content. This tooltip is defined by the following nested outer/inner tooltip structure:

<g tooltiptype="outer" preserveId="true" display="inline" transform="matrix( 1, 0, 0, 1, 124, -40)">
    <g id="rect_caption" tooltiptype="inner" preserveId="true" transform="matrix( 1, 0, 0, 1, 0, 0)" display="inline">
       <g>
           <g bind:graphic="Nodes__Detailed"/>
       </g>
    </g>
</g>

Using node styles for constructing tooltips is the recommended method for implementing complex tooltips. For example, the tooltip shown in Figure B-1 is a node style.

Pop-ups in the Layout Portlet

In the dashboard, the Popup definition allows you to open a new dialog box or Web page from the Layout portlet. Although the pop‑up definition is defined inside the Layout View’s source code, the pop‑up is not available as a feature for use from the Layout View of the Operations Center console—the resulting pop-up is only active in the dashboard depending on how it is defined.

For more information about the Layout portlet and the dashboard, see the Operations Center 5.6 Dashboard Guide.

As mentioned above, pop-ups are defined differently depending on whether it is to apply to the dashboard. The following sections describe the Popup definition and show how to implement for the dashboard:

Understanding Pop-Up Definition

The pop-up definition is used to open a new dialog box or Web page. It contains a parameter identifying the DName of the selected item used to pre-populate data in the new window or Web page.

A pop‑up URL template is a group object with the following required parameters:

  • portalPopupURLTemplate:  

    • Defines the actual URL template itself.

    • Refers to an existing URL within the current portlet definitions.

    • The DName must be parameterized in the template with the following replacement tag:

      [INSERT_DNAME_HERE]
      

      This instructs the pop‑up mechanism to insert the currently active DName (derived from the click) into the URL when launched.

      NOTE:Never replace [INSERT_DNAME_HERE] with an actual DName value, this is the mechanism for Operations Center to dynamically insert the DName of the active element.

    • The parameter cannot contain ampersand (&) characters. Replace them with &amp;. The & character is a reserved character in SVG and cannot appear in an attribute value.

  • popupTargetFrameIds: Identifies the target dialog box in which to open the pop‑up URL.

Optionally, the following parameters can be defined:

  • popupURLParams: Defines the parameters used to display the pop‑up dialog box. For example, popupURLParams="toolbar=no,location=no,menubar=no,resizable,scrollbars".

  • popupTargetWindow: Defines the name of the browser window. For example, popupTargetWindow="_blank".

If a direct parent of any child element contains a group object with a portalPopupURLTemplate attribute, this pop‑up URL Template is used. The group object with a portalPopupURLTemplate attribute must be a direct parent of any child that should inherit that pop-up.

Creating a Pop-Up for the Dashboard

Figure B-2 is an example of a pop‑up implemented for the dashboard’s Layout portlet. A tooltip provides hyperlinks for additional options.

Figure B-2 Pop-up in Layout Portlet in the Dashboard

These links contain the DName for the selected element so they can use the popup definition to launch and populate other portlets. Clicking a link opens the selected element in a different portlet. For details on portlet structures, see the Operations Center 5.6 Dashboard Guide.

For example, clicking PopupAndDriveALL in the illustration above opens a new the dashboard page where all portlets on the page are focused to the selected element, as shown in Figure B-3:

Figure B-3 Clicking an option in the portal pop-up opens this dashboard page in a new browser window.

When creating a pop-up link in the dashboard, the portalPopupURLTemplate can be used to drive the current element on the page by passing in the portlet’s namespace or Portal Identifier with the element DName.

The following code shows syntax using the popup parameters to drive all portlets on the dashboard page. Keep in mind it is only a portion of the entire set of Bind language used to create the Layout view. View the Layout View’s source code using the View Source option in the Operations Center console.

<g>
   <g portalPopupURLTemplate="/web/communitya/page1?global_identity=[INSERT_DNAME_HERE]" popupTargetWindow="our_popup" popupURLParams="toolbar=no,location=no,menubar=no,resizable,scrollbars">
      <text x="154" font-size="10pt" y="70" text-decoration="underline" transform="matrix( 1, 0, 0, 1, -146, -16)" fill="blue" filter="none" font-style="italic" opacity="1" stroke="none">PopupAndDriveALL</text>
   </g>
</g>

IMPORTANT:The [INSERT_DNAME_HERE] section of the code should never be manually modified. This is for internal use and instructs Operations Center to dynamically use the DName of the current element.

Links can also be configured to drive only those portlets as specified. Specify the exact portlets to update in the page by including the namespace or identifier for each portlet we wish to drive by appending the portalPopupURLTemplate value with a portlet_ids parameter such as &amp;portlet_ids="id1,id2".

For example:

<g>
    <g portalPopupURLTemplate="/web/communitya/page1?global_identity=[INSERT_DNAME_HERE]&amp;portlet_ids=layoutA" popupTargetWindow="our_popup" popupURLParams="toolbar=no,location=no,menubar=no,resizable,scrollbars">
     <text x="154" font-size="10pt" y="70" transform="matrix( 1, 0, 0, 1, -146, -16)" text-decoration="underline" fill="blue" filter="none" font-style="italic" opacity="1" stroke="none">PopupAndDriveSome</text>
   </g>
</g>

Using the dashboard portlet identifier feature, you can create user-friendly names for the portlets which is much easier (and shorter) to reference than the namespace. The example above takes advantage of this feature.

NOTE:Some of the root <svg> attributes have been omitted for these examples. It is important to note that a MOS_EnableMouseEvents must be added as an attribute on the root <svg> element and set to True in order to activate the mouse handling mechanism in the Layout portlet for the dashboard.

To determine the portalPopupURLTemplate value and the optional portlet identifiers in the dashboard:

  1. In Internet Explorer, access the dashboard and go to the page.

    NOTE:Only use Internet Explorer to perform this procedure.

  2. To determine the portalPopupURLTemplate value:

    1. From the Web browser address/location bar, copy the URL which might look something like the following (or in some cases, much simpler):

      http://serverName:8080/web/guest/popuptemplate

    2. Remove the server prefix and the extra portlet parameters from the URL (basically retaining the community and page portion of the URL) and insert them into the following template:

      relative_server_path?global_identity=[INSERT_DNAME_HERE]

      to obtain the following for the example from step 2:

      /web/guest/popuptemplate?global_identity=[INSERT_DNAME_HERE]

  3. (Optional) To determine the Namespace or Portal Identifier to drive a specific portlet(s):

    1. Open the Preferences for the portlet to drive and navigate to the Advanced tab. The Common tab opens under Advanced.

    2. Copy the portlet namespace or identifier.

      The namespace is shown at the top of the Common tab:

      (Optional) Scroll down to locate or specify the Portlet Identifier. The Portlet Identifier can be easier to use and remember than the portlet namespace as it creates a “friendly URL”:

    3. In the Layout View’s Source, when defining the portalPopupURLTemplate as shown earlier in this section, specify the namespace or identifier using the portlet_ids parameter to be passed to the page. For example:

      &amp;portlet_ids=portlet1,portlet2
      

      Use a comma delimited list for multiple portlet namespace or identifiers.

      For example, by appending our previous example and using friendly URLs (Portlet Identifiers), we have:

      /web/guest/popuptemplate?global_identity=INSERT_DNAME_HERE&amp;portlet_ids=proptable42,properties42
      
  4. In the Layout View’s Source, set the portalPopupURLTemplate to the value as obtained as a result of Step 2 or Step 3.

B.1.2 Tying an Element to a Drawing Shape

You can tie an element to a drawing shape by setting the DName attribute of the shape:

<g DName='root=Organizations'>
  <rect width='100' height='100'>
    <bind:condition/>
  </rect>
</g>

SVG ignores this attribute, but the layout system can use it to know which element to bind to the shape.

When set, the DName attribute affects every shape beneath it in the SVG or XML tree. But you can set other DNames beneath it in the tree.

A DName attribute overrides whatever is set above it.

B.1.3 Changing Shapes or Showing Objects Based on Element Condition

The following sections cover changing shapes and hiding/showing objects:

Shape Background Color

To change a shape’s background color to reflect an element’s condition, use the <bind:condition> tag inside the shape tag:

<rect width='100' height='100' stroke='black'>
  <bind:condition/>
</rect>

Shape Border Color

To change a shape’s border color to reflect an element’s condition, use the <bind:stroke> tag inside the shape tag:

<rect width='100' height='100' stroke='blue' fill='white' stroke-width='5'>
  <bind:stroke property='condition'/>
</rect>

Hiding and Showing Objects

To set the visibility of a shape or object based on element condition, use the <bind:visibility> tag:

<rect width='100' height='100' visibility='hidden'>
  <bind:visibility when='critical,major' set='visible' else='hidden'/>
</rect>

B.1.4 Changing Shapes Based on Element Property

The following sections cover changing shape characteristics based on element property values:

Shape Size

To set the size of a shape based on property value, use the <bind:width> tag, then specify a property attribute:

<rect width='50' height='20'>
  <bind:width property='users'/>
</rect>

The shape width changes based on the value of the property.

Scaling by a Factor when Setting a Numeric Property

To scale an attribute by a factor using an element property value, specify a value to multiply against the property value:

<rect width='50' height='20'>
  <bind:width>element['users'] * 5</bind:width>
</rect>

Shape Style Based on Element Property Value

To change the style of a shape based on an element property, conditional statements can be used. In the following example, the border of the shape is grey:

<rect stroke-width='1' stroke='grey' width='100' height='100'>
  <bind:stroke-width>
<![CDATA[
if (element['users'] < 50) 1 else 5
]]>
  </bind:stroke-width>
  <bind:stroke>
<![CDATA[
if (element['users'] < 50) 'green' else 'red'
]]>
  </bind:stroke>
</rect>

If the users property on the element is greater than 50, the shape border increases to a width of 5 pixels and changes from green to red.

The following partial code example shows a simplified ranging syntax:

<rect width='100' height='100'>
  <bind:stroke-width property='users' range='< 50 :green;< 80 :orange' else='red'/>
</rect>

Shape Transparency Based on Element Property Value

To change an objects transparency based on an element property, use the <bind:opacity> tag. In the following example, the property value is divided by 100 to set a percentage value of opacity.

<rect fill='green' stroke='black' opacity='1'>
  <bind:opacity>element['users'] / 100.0</bind:opacity>
</rect>

B.1.5 Displaying Element Name or Element Property

The following sections cover how to display and element name or property value:

Element Name

To show the name of an element, use the <bind:value> tag, setting the bind property to 'name':

<text font-size='18' text-anchor='middle'>
  <bind:value property='name'/>
</text>

Element Property Value

To show the value of a specific element property, use the <bind:value> tag, setting property to the element property name:

<text>
  <bind:value property='responseTime'/>
</text>

Default Property Value

If a property doesn’t exist, you can set the default value by specifying a default attribute on the <bind:value> tag:

<text text-anchor='middle'>
  <bind:value property='responseTime' default='not available'/>
</text>

Controlling Width of Text

Control the width of wrapped text by adding a wrap tag to a <bind:value> on a text-based content bind. The value of the wrap tag controls the width of the wrapped text. The wrapper attempts to break on spaces, but it breaks a word if it is longer than the specified wrap width.

This example sets the wrap width to 75:

<text overflow="visible" x="27" y="65" font-size="10" text-anchor="middle">ClassicWrap<bind:value property="name" wrap="75" texthash="1.52892531E9" undo="Classic Small"/>
</text>

Notice that the wrap attribute must be contained inside of the <bind:value> tag.

B.1.6 Displaying Element Children

The following sections cover how to display the number of children or the children along a path of a shape:

Number of Children

To show the number of children for the element, set the property attribute to childCount in the <bind:value> tag:

<text>
  <bind:value property='childCount'/>
</text>

Number of ORG Children

To show the number of children for the element, set the property attribute to orgChildCount in the <bind:value> tag:

<text>
  <bind:value property='orgChildCount'/>
</text>

Children along a Path

Children can be displayed for any element. By using or modifying the following code, the children can be displayed along the circumference of a circle or the edge of any shape (for example, rectangles, lines, paths, or curves).

In this example, we show setting them to display along the edge of a circle:

<circle id='circlepath' fill='none' stroke='grey' r='500'/>
<bind:children graphic='Nodes__Classic'>
  <bind:layout path='#circlePath'/>
</bind:children>

B.1.7 Formatting Numbers, Dates, and Time

The following section cover how to format numbers, dates and times:

Numbers

Format numbers using Java’s Formatter class. For example:

<text>
  <bind:value property='childCount' format='Number of children: %1$d'/>
</text>

The above formats an integer property. To format a floating point property, use %1$f instead of %1$d.

Java’s Formatter class documentation can be referenced at http://java.sun.com/j2se/1.5.0/docs/api/java/util/Formatter.html.

Time

<text>
  <bind:value property='lastUpdate' format='time'/>
</text>

Date

<text>
  <bind:value property='lastUpdate' format='time'/>
</text>

Date-Time

<text>
  <bind:value property='lastUpdate' format='datetime'/>
</text>

Custom Date-Time

In addition to the shortcuts supplied above (which do locale-specific date and time formatting automatically), you can specify the exact format of a date-time string by supply a format compatible with Java’s SimpleDateFormat class:

<text>
  <bind:value property='lastUpdate' format='EEE, d MMM yyyy HH:mm:ss Z'/>
</text>