Chapter 7 Plug-In User Interface Schema

This chapter describes the XML schema that you use to define the user interface for a plug-in. The chapter contains the following topics:

• <pluginUI> Element Overview

• <icon> Element

• <customPage> Element

• Sample XML for the <pluginUI> Element

<pluginUI> Element Overview

The <pluginUI> element enables a plug-in author to describe a limited set of functionality to appear on a custom shortcuts page. The set of functionality exposed via the shortcuts is divided into the following categories:

• Component type shortcuts:

  • List all components that extend this component type

  • Create a component that extends this component type

• Component shortcuts:

  • Manage the specified component (link to component details page)

  • List virtual and physical hosts where this component is installed

• Plan shortcuts:

  • Manage the specified plan (link to plan details page)

Attributes for the <pluginUI> Element

The <pluginUI> element has the following attributes:

• menuItem – The text to display in the menu of the browser interface. The name should be 20 characters or less in length, although the actual character limit is defined by the attribute type.

• tooltip – An optional tooltip to display for the menu item in the browser interface. The menuItem includes the icon, if you choose to provide an icon.

• xmlns – A required string that has the following value:

  http://www.sun.com/schema/SPS

• xmlns:xsi – A required string that has the following value:

  http://www.w3.org/2001/XMLSchema-instance

• xsi:schemaLocation – An optional string that has the following recommended value:

  http://www.sun.com/schema/SPS pluginUI.xsd

• schemaVersion – A required attribute of type schemaVersion, which is the version of the plug-in XML schema being used. The only permitted values are 5.0, 5.1 and 5.2.

  The 5.2 version of the schema is backward compatible with the 5.0 and 5.1 versions.

Child Elements of the <pluginUI> Element

The <pluginUI> element contains the following elements:

• <icon> – Provides the path to a graphic (icon) that you want displayed within the interface for this plug-in

• <customPage> – Defines the contents of the custom page linked to by the menu item in the browser interface

<icon> Element

The <icon> element is a child of the <pluginUI> element. The <icon> element declares the location of the plug-in icon. The icon is expected to be in GIF or JPEG file format. The icon should have dimensions of 32 pixels wide by 26 pixels high.

Attributes for the <icon> Element

The <icon> element has one required attribute jarPath. The jarPath attribute specifies the location of the plug-in icon, relative to the root of the plug-in JAR file. Leading slash (/) or dot (.) characters are not permitted.

<customPage> Element

The <customPage> element is a child of the <pluginUI> element and defines the contents of the custom page linked to by the menu item in the browser interface. . The <customPage> element contains one or more <section> elements and has a name attribute.

Attributes for the <customPage> Element

The <customPage> element has one required attribute, name. The name attribute is used in the breadcrumb and title sections of the custom page.

<section> Element

The <section> element is a child of the <customPage> element and defines a section for the custom page. The <section> element contains one or more <entry> or <section> elements and has two attributes:

• title – Section title

• description – An optional section description, secondary text

---

Note –

To create a nested custom page structure, put a <section> element within another <section> element. Any nested <section> elements must appear after all <entry> elements within the <section>.

---

<entry> Element

The <entry> element is a child of the <section> element and defines an entry point for user actions. An <entry> element contains zero or more <action> elements and has the following attributes:

• title – Entry title

• description – An optional entry description

<action> Element

The <action> element is a child of the <entry> element and defines a user action. Each <action> element must contain exactly one child element.

The <action> element has two attributes:

• text – Text to be rendered for the link of the user action

• tooltip – An optional tooltip to be used for the link of the user action

Each <action> element must contain one of the following child elements:

<compCreate>

The <compCreate> element is a child of the <action> element and defines a link to the component create page for the named component type.

The <compCreate> element has one required attribute:

• typeName – The name of the component type. The component type must be contained in the plug-in or in a plug-in on which this plug-in directly depends. The component type cannot be defined as hidden. The pluginName must be prefixed to the component type name, for example, fullPluginName#componentTypeName.

<compDetails>

The <compDetails> element is a child of the <action> element and defines a link to the component details page for the latest version of the named component.

The <compDetails> element has two required attributes:

• path – The absolute path of the component.

• name – The name of the component. The component must be contained in the plug-in or in a plug-in on which this plug-in directly depends.

<compList>

The <compList> element is a child of the <action> element and defines a link to the component list page filtered by the named component type. If the optional path or flatView attributes are omitted, their values will be picked up from the user's session when the users clicks on the link. If not omitted, the user's session values will be changed to reflect them after clicking on the link.

The <compList> element has three attributes:

• typeName – The required name of the component type. The component type must be contained in the plug-in or in a plug-in on which this plug-in directly depends. The component type cannot be defined as hidden. The pluginName must be prefixed to the component type name, for example, fullPluginName#componentTypeName.

• path – An optional full path by which to filter the components list page. The path must start with a slash (/), and should not end with a slash (/). The folder that the path represents must be a folder either owned by this plug-in or owned by a plug-in on which this plug-in directly depends. Alternatively, the folder can contain a folder owned by this plug-in or by a plug-in on which this plug-in directly depends.

• flatView – An optional statement as to whether the list page should enable the flat view filter.

<compWhereInstalled>

The <compWhereInstalled> element is a child of the <action> element and defines a link to the Component Where Installed page for the latest version of the named component.

The <compWhereInstalled> element has two required attributes:

• path – The absolute path of the component.

• name – The name of the component. The component must be contained in the plug-in or in a plug-in on which this plug-in directly depends.

<hostList>

The <hostList> element is a child of the <action> element and defines a link to the host list page filtered by the named host type.

The <hostList> element has one required attribute:

• typeName – The name of the host type. The host type must be contained in the plug-in or in a plug-in on which this plug-in directly depends. The host type cannot be defined as hidden. The pluginName must be prefixed to the host type name, for example, fullPluginName#hostTypeName.

<planDetails>

The <planDetails> element is a child of the <action> element and defines a link to the plan details page for the latest version of the named plan.

The <planDetails> element has two required attributes:

• path – The absolute path of the plan.

• name – The name of the plan. The plan must be contained in the plug-in or in a plug-in on which this plug-in directly depends.

<compProcedureRun>

The <compProcedureRun> element is a child of the <action> element and enables you to run a component procedure directly.

The <compProcedureRun> element has four required attributes:

• name – The name of the component that contains the procedure to run. The component must be contained in this plug-in or in a plug-in on which this plug-in directly depends.

• path – The absolute path to the component.

• procedureName – The name of the component procedure.

• procedureType – The type of the component procedure. Valid values include INSTALL, UNINSTALL or CONTROL.

<external>

The <external> element is a child of the <action> element and defines a link to an arbitrary URL that is outside of the N1 SPS product. For example, you might use this element to provide a link to a corporate web page that contains additional information about a specific plug-in or feature.

The <external> element has one attribute, url, which supplies a well-formed URL. The URL must conform to the Internet standard for Uniform Resource Identifiers (URIs) as specified in RFC3986 Uniform Resource Identifier (URI): Generic Syntax.

To ensure that the XML for the plug-in user interface descriptor is well-formed, the url attribute may include escaped special characters. Use the following escape sequences for the specified characters:

Character	Escape Sequence
>	>
<	&lt;
"	&quot;
&	&amp;

Sample XML for the <pluginUI> Element

The following sample XML takes fragments from various custom pages to illustrate each element in the <pluginUI> schema.

---

Example 7–1 Sample <pluginUI> Descriptor File

<?xml version="1.0" encoding="UTF-8"?>
<pluginUI menuItem="pluginName" 
          toolTip="view wl server pages"
          xmlns="http://www.sun.com/schema/SPS"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.sun.com/schema/SPS
                              pluginUI.xsd"
          schemaVersion="5.2">
  <icon jarPath="custom/gui/img/WLicon-small.gif"/>
  <customPage name="WebLogic">
    <section title="WebLogic application tasks" 
             description="capture and edit your WebLogic applications...">
      <entry title="enterprise applications (EARs)" 
             description="capture, edit and deploy your enterprise applications">
        <action text="view all" toolTip="view all EARs">
          <compList typeName="com.bigCo.logic.pluginName#WebLogic enterprise application" 
               path="/com/bigCo/logic" flatView="true"/>
        </action>
        <action text="create new" toolTip="create new enterprise application">
         <compCreate typeName="com.bigCo.logic.pluginName#WebLogic enterprise application"/>
        </action>
      </entry>
      <entry title="web applications (WARs)" 
             description="capture, edit and deploy web applications">
        <action text="view all" toolTip="view all WARs">
          <compList typeName="com.bigCo.logic.pluginName#WebLogic web application"/>
        </action>
        <action text="create new" toolTip="create new webapp">
          <compCreate typeName="com.bigCo.logic.pluginName#WebLogic web application"/>
        </action>
      </entry>
      <entry title="java archives containing EJBs (JARs)" 
             description="capture, edit and deploy your JARS containing EJBs">
        <action text="view all" toolTip="view all JARs">
          <compList typeName="com.bigCo.logic.pluginName#WebLogic EJB"/>
        </action>
        <action text="create new" toolTip="create new java archive containing EJBs">
          <compCreate typeName="com.bigCo.logic.pluginName#WebLogic EJB"/>
        </action>
      </entry>
	<section>
	  <entry title="entry in a nested section"
		   description="this is a an entry in a nested section">
	    <action text="view all" toolTip="view all aType comps">
		<compList
              typeName="com.bigCo.logic.pluginName#aType"
	        path="/com/bigCo/logic" />
	    </action>
	  </entry>
	</section>
    </section>
    <section title="WebLogic infrastructure" 
             description="create and edit your WebLogic infrastructure...">
      <entry title="admin servers" 
             description="WebLogic domains / administration servers">
        <action text="manage admin servers" toolTip="manage WebLogic admin servers">
          <compDetails path="/com/bea/weblogic" name="WL Admin Server 7.0"/>
        </action>
        <action text="view admin servers" toolTip="list of WebLogic admin servers">
          <compWhereInstalled path="/com/bea/weblogic" name="WL Admin Server 7.0"/>
        </action>
      </entry>
      <entry title="clusters" 
             description="WebLogic clusters">
        <action text="manage clusters" toolTip="manage WebLogic clusters">
          <compDetails path="/com/bea/weblogic" name="WL Cluster"/>
        </action>
        <action text="view clusters" toolTip="list of WebLogic clusters">
          <compWhereInstalled path="/com/bea/weblogic" name="WL Cluster"/>
        </action>
      </entry>
      <entry title="managed servers" 
             description="WebLogic server instances">
        <action text="manage server instances" toolTip="WebLogic managed servers">
          <compDetails path="/com/bea/weblogic" name="WL Managed Server"/>
        </action>
        <action text="view managed servers" toolTip="list of WebLogic managed servers">
          <compWhereInstalled path="/com/bea/weblogic" name="WL Managed Server"/>
        </action>
        <action text="update managed servers" toolTip="run a plan on managed servers">
          <planDetails path="/com/bea/weblogic/updates" name="updatePlan"/>
        </action>
        <action text="list servers" toolTip="list the apache servers">
          <hostList searchName="com.bigCo.logic.pluginName.WebLogic#apacheHosts"/>
        </action>
         <action text="custom reports" toolTip="view the custom reports">
          <external url="http://reportserver/reports/dec"/>
        </action>
        <action text="start a Managed Server" 
                toolTip="run the start control of a ManagedServer component">
          <compProcedureRun path="/com/sun/weblogic" name="WL Managed Server" 
               procedureName="start" procedureType="CONTROL"/>
        </action>
    </entry>
    </section>
  </customPage>
</pluginUI> 

---