Author: mmcallis Date: 2008-02-25 22:41:50 -0500 (Mon, 25 Feb 2008) New Revision: 10117 Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/xmldescriptors.xml Log: 6.1.3. The JBoss Portal Object DTD replacing itemizedlist with variablelist Note: large section commented out so as not to break the nightly build Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/xmldescriptors.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/xmldescriptors.xml 2008-02-26 02:47:19 UTC (rev 10116) +++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/xmldescriptors.xml 2008-02-26 03:41:50 UTC (rev 10117) @@ -302,7 +302,7 @@ <sect2> <title>The JBoss Portlet Instance DTD</title> <para> - The following items refer to elements found in the JBoss Portlet Instance DTD, <filename>$JBOSS_HOME/server/configuration/deploy/jboss-portal.sar/dtd/portlet-instances_<replaceable>version_number</replaceable>.dtd</filename>: + The following items refer to elements found in the JBoss Portlet Instance DTD, <filename>$JBOSS_HOME/server/<replaceable>configuration</replaceable>/deploy/jboss-portal.sar/dtd/portlet-instances_<replaceable>version_number</replaceable>.dtd</filename>: </para> <para> <variablelist> @@ -487,7 +487,7 @@ </screen> </para> <para> - If present, the <computeroutput>&lt;unchecked&gt;</computeroutput> element is used to define that anyone can view the instance. + If present, the <computeroutput>&lt;unchecked&gt;</computeroutput> element is used to define that anyone can view this instance. </para> <para> <screen><![CDATA[ @@ -495,7 +495,7 @@ </screen> </para> <para> - The <computeroutput>&lt;role-name&gt;</computeroutput> element is used to define a role that the security constraint will apply to. The following example only allows users that are part of the <computeroutput>EXAMPLEROLE</computeroutput> role, to access the instance: + The <computeroutput>&lt;role-name&gt;</computeroutput> element is used to define a role that the security constraint will apply to. The following example only allows users that are part of the <computeroutput>EXAMPLEROLE</computeroutput> role to access this instance: </para> <para> <screen><![CDATA[ @@ -508,117 +508,187 @@ </para> </sect2> <sect2> - <title>Portal Object DTD</title> + <title>The JBoss Portal Object DTD</title> <para> -<itemizedlist> + 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><screen><![CDATA[ +<!ELEMENT deployments (deployment*)>]]> +</screen></term> <listitem> -<para> -Element <![CDATA[<!ELEMENT deployments (deployment*)>]]> -</para><para><programlisting><![CDATA[The deployements element is a generic container for deployment elements.]]></programlisting></para> -</listitem><listitem> -<para> -Element <![CDATA[<!ELEMENT deployment (parent-ref,if-exists?,(context | portal | page | window))>]]> -</para><para><programlisting><![CDATA[The deployment is a generic container for portal object elements. The parent-ref -child gives the name of the parent object that the current object will use as parent. -The optional if-exists element define the behavior when a portal object which -an identical name is already child of the parent element. The default behavior of -the if-exist tag is to keep the existing object and not create a new object. The -last element is the portal object itself. - -Example: - + <para> + The <computeroutput>&lt;deployments&gt;</computeroutput> element is a container for the <computeroutput>&lt;deployment&gt;</computeroutput> element. + </para> +</listitem> +</varlistentry> +<varlistentry><term><screen><![CDATA[ +<!ELEMENT deployment (parent-ref,if-exists?,(context | portal | page | window))>]]> +</screen></term> +<listitem> + <para> + The <computeroutput>&lt;deployment&gt;</computeroutput> element is a generic container for portal object elements. The <computeroutput>&lt;parent-ref&gt;</computeroutput> child 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 behavior when a portal object which an identical name is already child of the parent element. The default behavior of the <computeroutput>&lt;if-exists&gt;</computeroutput> element is to keep the existing object and not create a new object. The last element is the portal object itself. + </para> + <para> + The following is an example of the <computeroutput>&lt;deployment&gt;</computeroutput> and <computeroutput>&lt;parent-ref&gt;</computeroutput> elements: + </para> + <para> +<screen><![CDATA[ <deployment> <parent-ref>default</parent-ref> <page> ... </page> -</deployment> - -All portal objects have a common configuration which can be : - -1/ a listener : specifies the id of a listener is the listener registry. A listener -object is able to listen portal events which apply to the portal node hierarchy. - -2/ properties : a set of generic properties owned by the portal object. Some -properties can drive the behavior of the object. - -3/ security-constraint : defines security configuration of the portal object.]]></programlisting></para> -</listitem><listitem> -<para> -Element <![CDATA[<!ELEMENT parent-ref (#PCDATA)>]]> -</para><para><programlisting><![CDATA[Contains a reference to the parent object. The naming convention for naming object -is to concatenate the names of the path to the object and separate the names by a dot. -If the path is empty then the empty string must be used. - -Example: - -<parent-ref/> the root having an empty path - -<parent-ref>default</parent-ref> the object with the name default under the root -having the path (default) - -<parent-ref>default.default</parent-ref> the object with the path (default,default)]]></programlisting></para> -</listitem><listitem> -<para> -Element <![CDATA[<!ELEMENT if-exists (#PCDATA)>]]> -</para><para><programlisting><![CDATA[The authorized values are overwrite and keep. Overwrite means that the existing -object will be destroyed and the current declaration will be used. Keep means that -the existing object will not be destroyed and no creation hence will be done.]]></programlisting></para> -</listitem><listitem> -<para> -Element <![CDATA[<!ELEMENT context (context-name,properties?,listener?,security-constraint?,portal*)>]]> -</para><para><programlisting><![CDATA[A portal object of type context. A context type represent a node in the tree which -does not have a visual representation. It can exist only under the root. A context can -only have children with the portal type.]]></programlisting></para> -</listitem><listitem> -<para> -Element <![CDATA[<!ELEMENT context-name (#PCDATA)>]]> -</para><para><programlisting><![CDATA[The context name value.]]></programlisting></para> -</listitem><listitem> -<para> -Element <![CDATA[<!ELEMENT portal (portal-name,supported-modes,supported-window-states?,properties?,listener?,security-constraint?,page*)>]]> -</para><para><programlisting><![CDATA[ -A portal object of type portal. A portal type represents a virtual portal and can -have children of type page. In addition of the common portal object elements it support -also the declaration of the modes and the window states it supports. If no declaration -of modes or window states is done then the default value will be respectively -(view,edit,help) and (normal,minimized,maximized).]]></programlisting></para> -</listitem><listitem> -<para> -Element <![CDATA[<!ELEMENT portal-name (#PCDATA)>]]> -</para><para><programlisting><![CDATA[The portal name value.]]></programlisting></para> -</listitem><listitem> -<para> -Element <![CDATA[<!ELEMENT supported-modes (mode*)>]]> -</para><para><programlisting><![CDATA[The supported modes of a portal. - -Example: - +</deployment>]]> +</screen> + </para> + <para> + All portal objects have a common configuration which can include: + </para> + <para> + <itemizedlist> + <listitem> + <para> + a listener: specifies the id of a listener is the listener registry. A listener object is able to listen portal events which apply to the portal node hierarchy. + </para> + </listitem> + <listitem> + <para> properties : a set of generic properties owned by the portal object. Some properties can drive the behavior of the object. + </para> + </listitem> + <listitem> + <para> security-constraint : defines security configuration of the portal object. + </para> + </listitem> + </itemizedlist> + </para> + <para> +<screen><![CDATA[ +<!ELEMENT parent-ref (#PCDATA)>]]> +</screen> + </para> + <para> + Contains a reference to the parent object. The naming convention for naming object is to concatenate the names of the path to the object and separate the names by a dot. If the path is empty then the empty string must be used. The <computeroutput>&lt;parent-ref&gt;</computeroutput> element tells the portal where the portlet should appear. + </para> + <para> + The following is an example of the root having an empty path: + </para> + <para> +<screen> +&lt;parent-ref/&gt; +</screen> + </para> + <para> + The following specifies that the portlet will appear on the <computeroutput>default</computeroutput> page: + </para> + <para> +<screen> +&lt;parent-ref&gt;default&lt;/parent-ref&gt; +</screen> + </para> + <para> + The following specifies that the portlet will apear in the portal instance named <computeroutput>default</computeroutput>, and on the page named <computeroutput>default</computeroutput>: + </para> + <para> +<screen> +&lt;parent-ref&gt;default.default&lt;/parent-ref&gt; +</screen> + </para> + <para> +<screen><![CDATA[ +<!ELEMENT if-exists (#PCDATA)>]]> +</screen> + </para> + <para> + The <computeroutput>&lt;if-exists&gt;</computeroutput> element is used to define 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 will destroy the existing object and create a new one based on the content of the deployment. The <computeroutput>keep</computeroutput> option will maintain the existing object deployment, or create a new one if it does not exist. + </para> +</listitem> +</varlistentry> +<varlistentry><term><screen><![CDATA[ +<!ELEMENT context (context-name,properties?,listener?,security-constraint?,portal*)>]]> +</screen></term> +<listitem> + <para> + A portal object of type context. A context type represent a node in the tree which does not have a visual representation. It can exist only under the root. A context can only have children with the portal type. + </para> + <para> +<screen><![CDATA[ +<![CDATA[<!ELEMENT context-name (#PCDATA)>]]> +</screen> + </para> + <para> + The context name value. + </para> + <para> +<screen><![CDATA[ +<![CDATA[<!ELEMENT portal (portal-name,supported-modes,supported-window-states?,properties?, +listener?,security-constraint?,page*)>]]> +</screen> + </para> + <para> + A portal object of type portal. A portal type represents a virtual portal and can have children of type page. In addition of the common portal object elements it support also the declaration of the modes and the window states it supports. If no declaration of modes or window states is done then the default value will be respectively (view,edit,help) and (normal,minimized,maximized). + </para> + <para> +<screen><![CDATA[ +<!ELEMENT portal-name (#PCDATA)>]]> +</screen> + </para> + <para> + The portal name value. + </para> + <para> +<screen><![CDATA[ +<!ELEMENT supported-modes (mode*)>]]> +</screen> + </para> + <para> + The supported modes of a portal. + </para> + <para> + The following is an example of the <computeroutput>&lt;supported-mode&gt;</computeroutput> element: + </para> + <para> +<screen><![CDATA[ <supported-mode> <mode>view</mode> <mode>edit</mode> <mode>help</mode> -</supported-mode>]]></programlisting></para> -</listitem><listitem> -<para> -Element <![CDATA[<!ELEMENT mode (#PCDATA)>]]> -</para><para><programlisting><![CDATA[ -A portlet mode value.]]></programlisting></para> -</listitem><listitem> -<para> -Element <![CDATA[<!ELEMENT supported-window-states (window-state*)>]]> -</para><para><programlisting><![CDATA[ -The supported window states of a portal. - -Example: - +</supported-mode>]]> +</screen> + </para> +</listitem> +</varlistentry> +<varlistentry><term><screen><![CDATA[ +<![CDATA[<!ELEMENT mode (#PCDATA)>]]> +</screen></term> +<listitem> + <para> + A portlet mode value. + </para> +</listitem> +</varlistentry> +<varlistentry><term><screen><![CDATA[ +<![CDATA[<!ELEMENT supported-window-states (window-state*)>]]> +</screen></term> +<listitem> + <para> + The supported window states of a portal. The following is an example of the <computeroutput>&lt;supported-window-states&gt;</computeroutput> element: + </para> + <para> +<screen><![CDATA[ <supported-window-states> <window-state>normal</window-state> <window-state>minimized</window-state> <window-state>maximized</window-state> -</supported-window-states>]]></programlisting></para> -</listitem><listitem> -<para> +</supported-window-states>]]> +</screen></para> +</listitem> +</varlistentry> +</variablelist> +</para> +</sect2> +<!--<para> Element <![CDATA[<!ELEMENT window-state (#PCDATA)>]]> </para><para><programlisting><![CDATA[A window state value.]]></programlisting></para> </listitem><listitem> @@ -755,7 +825,7 @@ </listitem></itemizedlist> </para> - </sect2> + </sect2> --> <sect2> <title>JBoss App DTD</title> <para>