Author: mmcallis Date: 2008-07-13 21:58:29 -0400 (Sun, 13 Jul 2008) New Revision: 11431 Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml Log: 6.1.3. The JBoss Portal Object DTD moving content out of variablelist: make docbook valid and enable code highlighting. Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml 2008-07-14 01:33:56 UTC (rev 11430) +++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/xmldescriptors.xml 2008-07-14 01:58:29 UTC (rev 11431) @@ -400,29 +400,22 @@ <para> The following items refer to elements found in the JBoss Portal Object DTD, <filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/jboss-portal.sar/dtd/portal-object_<replaceable>version_number</replaceable>.dtd</filename>: </para> - <para> - <variablelist> - <varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT deployments (deployment*)>]]> -</programlisting></term> -<listitem> +</programlisting> <para> The <computeroutput>&lt;deployments&gt;</computeroutput> element is a container for <computeroutput>&lt;deployment&gt;</computeroutput> elements. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT deployment (parent-ref?,if-exists?,(context|portal|page|window))>]]> -</programlisting></term> -<listitem> +</programlisting> <para> The <computeroutput>&lt;deployment&gt;</computeroutput> element is a generic container for portal object elements. The <computeroutput>&lt;parent-ref&gt;</computeroutput> child element gives the name of the parent object that the current object will use as parent. The optional <computeroutput>&lt;if-exists&gt;</computeroutput> element defines the action to take if an instance with the same name already exists. The default behavior of the <computeroutput>&lt;if-exists&gt;</computeroutput> element is to keep the existing object, and not to create a new object. </para> <para> The following is an example of the <computeroutput>&lt;deployment&gt;</computeroutput> and <computeroutput>&lt;parent-ref&gt;</computeroutput> elements: </para> - <para> -<programlisting><![CDATA[ +<programlisting role="XML"><![CDATA[ <deployment> <parent-ref>default</parent-ref> <page> @@ -430,7 +423,6 @@ </page> </deployment>]]> </programlisting> - </para> <para> All portal objects have a common configuration which can include: </para> @@ -453,224 +445,166 @@ </listitem> </itemizedlist> </para> - <para> <programlisting><![CDATA[ <!ELEMENT parent-ref (#PCDATA)>]]> </programlisting> - </para> <para> The <computeroutput>&lt;parent-ref&gt;</computeroutput> element contains a reference to the parent object. The naming convention for naming objects is to concatenate the names of the path to the object, and separate the names using a period. If the path is empty, the empty string must be used. The <computeroutput>&lt;parent-ref&gt;</computeroutput> element tells the portal where the portlet appears. The syntax for the <computeroutput>&lt;parent-ref&gt;</computeroutput> element is <computeroutput><replaceable>portal-instance</replaceable>.<replaceable>portal-page</replaceable></computeroutput>. </para> <para> The following is an example of the root having an empty path: </para> - <para> -<programlisting> -&lt;parent-ref/&gt; +<programlisting role="XML"> +&lt;parent-ref /&gt; </programlisting> - </para> <para> The following specifies that the portlet appears in the portal instance named <computeroutput>default</computeroutput>: </para> - <para> -<programlisting> +<programlisting role="XML"> &lt;parent-ref&gt;default&lt;/parent-ref&gt; </programlisting> - </para> <para> The following specifies that the portlet appear in the portal instance named <computeroutput>default</computeroutput>, and on the page named <computeroutput>default</computeroutput>: </para> - <para> -<programlisting> +<programlisting role="XML"> &lt;parent-ref&gt;default.default&lt;/parent-ref&gt; </programlisting> - </para> - <para> <programlisting><![CDATA[ <!ELEMENT if-exists (#PCDATA)>]]> </programlisting> - </para> <para> The <computeroutput>&lt;if-exists&gt;</computeroutput> element defines the action to take if an instance with the same name already exists. Accepted values are <computeroutput>overwrite</computeroutput> and <computeroutput>keep</computeroutput>. The <computeroutput>overwrite</computeroutput> option destroys the existing object, and creates a new one based on the content of the deployment. The <computeroutput>keep</computeroutput> option matains the existing object deployment, or creates a new one if it does not exist. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT context (context-name,properties?,listener?,security-constraint?,portal*, (display-name* | (resource-bundle, supported-locale+)))>]]> -</programlisting></term> -<listitem> +</programlisting> <para> The context type of the portal object. A context type represent a node in a tree, which does not have a visual representation, and only exists under the root. A context can only have children that use the <emphasis>portal</emphasis> type. </para> - <para> <programlisting><![CDATA[ <!ELEMENT context-name (#PCDATA)>]]> </programlisting> - </para> <para> The context name. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT portal (portal-name,supported-modes,supported-window-states?,properties?,listener?, security-constraint?,page*, (display-name* | (resource-bundle, supported-locale+)))>]]> -</programlisting></term> -<listitem> +</programlisting> <para> A portal object that uses the <emphasis>portal</emphasis> type. A portal type represents a virtual portal, and can only have children that use the <emphasis>page</emphasis> type. In addition to the common portal object elements, it also allows you to declare modes and window states that are supported. </para> - <para> <programlisting><![CDATA[ <!ELEMENT portal-name (#PCDATA)>]]> </programlisting> - </para> <para> The portal name. </para> - <para> <programlisting><![CDATA[ <!ELEMENT supported-modes (mode*)>]]> </programlisting> - </para> <para> The <computeroutput>&lt;supported-modes&gt;</computeroutput> elements defines the supported modes of the portal. Accepted values are <computeroutput>view</computeroutput>, <computeroutput>edit</computeroutput>, and <computeroutput>help</computeroutput>. </para> <para> The following is an example of the <computeroutput>&lt;supported-mode&gt;</computeroutput> and <computeroutput>&lt;mode&gt;</computeroutput> elements: </para> - <para> -<programlisting><![CDATA[ +<programlisting role="XML"><![CDATA[ <supported-mode> <mode>view</mode> <mode>edit</mode> <mode>help</mode> </supported-mode>]]> </programlisting> - </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT mode (#PCDATA)>]]> -</programlisting></term> -<listitem> +</programlisting> <para> The portlet mode value. If there are no declarations of modes or window states, the default values are <computeroutput>view</computeroutput>, <computeroutput>edit</computeroutput>, <computeroutput>help</computeroutput>, and <computeroutput>normal</computeroutput>, <computeroutput>minimized</computeroutput>, <computeroutput>maximized</computeroutput>, respectively. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT supported-window-states (window-state*)>]]> -</programlisting></term> -<listitem> +</programlisting> <para> Use the <computeroutput>&lt;supported-window-states&gt;</computeroutput> element to define the supported window states of the portal. The following is an example of the <computeroutput>&lt;supported-window-states&gt;</computeroutput> and <computeroutput>&lt;window-state&gt;</computeroutput> elements: </para> - <para> -<programlisting><![CDATA[ +<programlisting role="XML"><![CDATA[ <supported-window-states> <window-state>normal</window-state> <window-state>minimized</window-state> <window-state>maximized</window-state> </supported-window-states>]]> </programlisting> - </para> - <para> <programlisting><![CDATA[ <!ELEMENT window-state (#PCDATA)>]]> </programlisting> - </para> <para> Use the <computeroutput>&lt;window-state&gt;</computeroutput> element to define a window states. Accepted values are <computeroutput>normal</computeroutput>, <computeroutput>minimized</computeroutput>, and <computeroutput>maximized</computeroutput>. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT page (page-name,properties?,listener?,security-constraint?,(page | window)*, (display-name* | (resource-bundle, supported-locale+)))>]]> -</programlisting></term> -<listitem> +</programlisting> <para> A portal object that uses the <emphasis>page</emphasis> type. A page type represents a page, and can only have children that use the <emphasis>page</emphasis> and <emphasis>window</emphasis> types. The children windows are the windows of the page, and the children pages are the subpages of the page. </para> - <para> <programlisting><![CDATA[ <!ELEMENT page-name (#PCDATA)>]]> </programlisting> - </para> <para> The page name. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT window (window-name,(instance-ref|content),region,height,initial-window-state?, initial-mode?,properties?,listener?, (display-name* | (resource-bundle, supported-locale+)))>]]> -</programlisting></term> -<listitem> +</programlisting> <para> A portal object that uses the <emphasis>window</emphasis> type. A window type represents a window. Besides the common properties, a window has content, and belongs to a region on the page. </para> <para> The <computeroutput>&lt;instance-ref&gt;</computeroutput> and <computeroutput>&lt;content&gt;</computeroutput> elements, configured in the <filename>WEB-INF/*-object.xml</filename> files, define the content of a window. The <computeroutput>&lt;content&gt;</computeroutput> element is generic, and describes any kind of content. The <computeroutput>&lt;instance-ref&gt;</computeroutput> element is a shortcut to define the content-type of the portlet, which points to a portlet instance. The value of <computeroutput>&lt;instance-ref&gt;</computeroutput> must match the value of one of the <computeroutput>&lt;instance-id&gt;</computeroutput> elements in the <filename>WEB-INF/portlet-instances.xml</filename> file. </para> - <para> <programlisting><![CDATA[ <!ELEMENT window-name (#PCDATA)>]]> </programlisting> - </para> <para> The window name value. </para> - <para> <programlisting><![CDATA[ <!ELEMENT instance-ref (#PCDATA)>]]> </programlisting> - </para> <para> Define the content of the window as a reference to a portlet instance. This value is the ID of a portlet instance, and must much the value of one of the <computeroutput>&lt;instance-id&gt;</computeroutput> elements in the <filename>WEB-INF/portlet-instances.xml</filename> file. The following is an example of the <computeroutput>&lt;instance-ref&gt;</computeroutput> element: </para> - <para> -<programlisting> +<programlisting role="XML"> &lt;instance-ref&gt;MyPortletInstance&lt;/instance-ref&gt; </programlisting> - </para> - <para> <programlisting><![CDATA[ <!ELEMENT region (#PCDATA)>]]> </programlisting> - </para> <para> The region the window belongs to. The <computeroutput>&lt;region&gt;</computeroutput> element specifies where the window appears on the page. </para> - <para> <programlisting><![CDATA[ <!ELEMENT height (#PCDATA)>]]> </programlisting> - </para> <para> The height of the window in a particular region. </para> - <para> <programlisting><![CDATA[ <!ELEMENT listener (#PCDATA)>]]> </programlisting> - </para> <para> Define a listener for a portal object. This value is the ID of the listener. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT content (content-type,content-uri)>]]> -</programlisting></term> -<listitem> +</programlisting> <para> Define the content of a window in a generic manner. The content is defined by the type of content, and a URI, which acts as an identifier for the content. The following is an example of the <computeroutput>&lt;content&gt;</computeroutput> element, which is configured in the <filename>WEB-INF/*-object.xml</filename> files: </para> - <para> -<programlisting><![CDATA[ +<programlisting role="XML"><![CDATA[ <content> <content-type>portlet</content-type> <content-uri>MyPortletInstance</content-uri> @@ -681,69 +615,49 @@ <content-uri>/default/index.html</content-uri> </content>]]> </programlisting> - </para> - <para> <programlisting><![CDATA[ <!ELEMENT content-type (#PCDATA)>]]> </programlisting> - </para> <para> The content type of the window. The <computeroutput>&lt;content-type&gt;</computeroutput> element specifies the content to display, for example, a <computeroutput>portlet</computeroutput>. </para> - <para> <programlisting><![CDATA[ <!ELEMENT content-uri (#PCDATA)>]]> </programlisting> - </para> <para> The content URI of the window. The <computeroutput>&lt;content-uri&gt;</computeroutput> element specifies which content to display, for example, a portlet instance. To display a file from the CMS, use the <computeroutput>&lt;content-uri&gt;</computeroutput> element to define the full path to that file in the CMS. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT properties (property*)>]]> -</programlisting></term> -<listitem> +</programlisting> <para> A set of generic properties for the portal object. The <computeroutput>&lt;properties&gt;</computeroutput> elements contains definitions specific to a page. This is commonly used to define the specific theme and layout to use. If not defined, the default portal theme and layout are used. </para> - <para> <programlisting><![CDATA[ <!ELEMENT property (name,value)>]]> </programlisting> - </para> <para> A generic string property. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT name (#PCDATA)>]]> -</programlisting></term> -<listitem> +</programlisting> <para> A name value. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT value (#PCDATA)>]]> -</programlisting></term> -<listitem> +</programlisting> <para> A value. </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT security-constraint (policy-permission*)>]]> -</programlisting></term> -<listitem> +</programlisting> <para> The <computeroutput>&lt;security-constraint&gt;</computeroutput> element is a container for <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. The following is an example of the <computeroutput>&lt;security-constraint&gt;</computeroutput> and <computeroutput>&lt;policy-permission&gt;</computeroutput> elements: </para> - <para> -<programlisting><![CDATA[ +<programlisting role="XML"><![CDATA[ <security-constraint> <policy-permission> <role-name>User</role-name> @@ -758,21 +672,15 @@ </policy-permission> </security-constraint>]]> </programlisting> - </para> -</listitem> -</varlistentry> -<varlistentry><term><programlisting><![CDATA[ +<programlisting><![CDATA[ <!ELEMENT policy-permission (action-name*,unchecked?,role-name*)>]]> -</programlisting></term> - <listitem> +</programlisting> <para> The <computeroutput>&lt;policy-permission&gt;</computeroutput> element is secures a specific portlet instance based on a user's role. </para> - <para> <programlisting><![CDATA[ <!ELEMENT action-name (#PCDATA)>]]> </programlisting> - </para> <para> The <computeroutput>&lt;action-name&gt;</computeroutput> element defines the access rights given to the role defined. Accepted values are: </para> @@ -800,31 +708,21 @@ </listitem> </itemizedlist> </para> - <para> <programlisting><![CDATA[ <!ELEMENT unchecked EMPTY>]]> </programlisting> - </para> <para> If present, the <computeroutput>&lt;unchecked&gt;</computeroutput> element defines that anyone can view the instance. </para> - <para> <programlisting><![CDATA[ <!ELEMENT role-name (#PCDATA)>]]> </programlisting> - </para> <para> The <computeroutput>&lt;role-name&gt;</computeroutput> element defines a role that the security constraint applies to. The following example only allows users that are part of the <computeroutput>EXAMPLEROLE</computeroutput> role to access the instance: </para> - <para> <programlisting><![CDATA[ <role-name>EXAMPLEROLE</role-name>]]> </programlisting> - </para> - </listitem> -</varlistentry> -</variablelist> -</para> </sect2> <sect2> <title>The JBoss Portal App DTD</title>