Author: mmcallis Date: 2008-04-20 21:02:11 -0400 (Sun, 20 Apr 2008) New Revision: 10665 Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/xmldescriptors.xml Log: 6.4.1. Defining a new Portal Page adding content, fixing my passive voice 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-04-21 00:38:37 UTC (rev 10664) +++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/xmldescriptors.xml 2008-04-21 01:02:11 UTC (rev 10665) @@ -327,7 +327,7 @@ </screen> </para> <para> - The <computeroutput>&lt;if-exists&gt;</computeroutput> element is 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 maintains the existing object deployment, or creates a new one if it does not exist. + 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 maintains the existing object deployment, or creates a new one if it does not exist. </para> </listitem> </varlistentry> @@ -337,7 +337,7 @@ </screen></term> <listitem> <para> - The <computeroutput>&lt;instance&gt;</computeroutput> element is used in the <filename>WEB-INF/portlet-instances.xml</filename> file, which is used to create instances of portlets. The portlet will only be created and configured if the portlet is present, and an instance with the same name does not already exist. + The <computeroutput>&lt;instance&gt;</computeroutput> element is used in the <filename>WEB-INF/portlet-instances.xml</filename> file, which creates instances of portlets. The portlet will only be created and configured if the portlet is present, and an instance with the same name does not already exist. </para> <para> The following is an example of the <computeroutput>&lt;instance&gt;</computeroutput> element, which also contains the <computeroutput>&lt;security-constraint&gt;</computeroutput> element. Descriptions of each element follow afterwards: @@ -444,7 +444,7 @@ </screen></term> <listitem> <para> - The <computeroutput>&lt;policy-permission&gt;</computeroutput> element is used to secure a specific portlet instance based on a user's role. + The <computeroutput>&lt;policy-permission&gt;</computeroutput> element secures a specific portlet instance based on a user's role. </para> <para> <screen><![CDATA[ @@ -452,7 +452,7 @@ </screen> </para> <para> - The <computeroutput>&lt;action-name&gt;</computeroutput> element is used to define the access rights given to the role defined. Accepted values are: + The <computeroutput>&lt;action-name&gt;</computeroutput> element defines the access rights given to the role defined. Accepted values are: </para> <para> <itemizedlist> @@ -484,7 +484,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 defines anyone can view the instance. </para> <para> <screen><![CDATA[ @@ -492,7 +492,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 defines 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: </para> <para> <screen><![CDATA[ @@ -600,7 +600,7 @@ </screen> </para> <para> - The <computeroutput>&lt;if-exists&gt;</computeroutput> element is 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. + 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> @@ -875,7 +875,7 @@ </screen></term> <listitem> <para> - The <computeroutput>&lt;policy-permission&gt;</computeroutput> element is used to secure a specific portlet instance based on a user's role. + The <computeroutput>&lt;policy-permission&gt;</computeroutput> element is secures a specific portlet instance based on a user's role. </para> <para> <screen><![CDATA[ @@ -883,7 +883,7 @@ </screen> </para> <para> - The <computeroutput>&lt;action-name&gt;</computeroutput> element is used to define the access rights given to the role defined. Accepted values are: + The <computeroutput>&lt;action-name&gt;</computeroutput> element defines the access rights given to the role defined. Accepted values are: </para> <para> <itemizedlist> @@ -915,7 +915,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 defines that anyone can view the instance. </para> <para> <screen><![CDATA[ @@ -960,9 +960,7 @@ </para> <para> When a web application is deployed, the context path under which it is deployed - is taken as the application name. The application name value in the <computeroutput>&lt;app-name&gt;</computeroutput> element is - used to override it. When a component references a portlet, it needs to - reference the application too, and if the portlet application WAR file is renamed, + is taken as the application name. The application name value in the <computeroutput>&lt;app-name&gt;</computeroutput> element overrides it. When a component references a portlet, it needs to reference the application too, and if the portlet application WAR file is renamed, the reference is no longer valid; therefore, the <computeroutput>&lt;app-name&gt;</computeroutput> element is used to have an application name that does not depend upon the context path, under which the application is deployed. </para> </listitem> @@ -974,12 +972,12 @@ <sect1 id="descriptors_portlet"> <title>Portlet Descriptors</title> <para> - The following sections describe the descriptors used to define portal objects, such as portals, pages, portlet instances, windows, and portlets. Refer to <xref linkend="tutorials_tutorials"/> and <xref linkend="desc_examples"/> for examples on using these descriptors within a portlet application. + The following sections describe the descriptors that define portal objects, such as portals, pages, portlet instances, windows, and portlets. Refer to <xref linkend="tutorials_tutorials"/> and <xref linkend="desc_examples"/> for examples on using these descriptors within a portlet application. </para> <sect2 id="desc_objectxml"> <title><filename>*-object.xml</filename> Descriptors</title> <para> - The <filename>*-object.xml</filename> descriptors are used to define portal instances, pages, windows, and the window layout. As well, themes and layouts for specific portal instances, pages, and windows, can be defined. The following example defines a portlet window being added to the <computeroutput>default</computeroutput> page, in the <computeroutput>default</computeroutput> portal. For advanced functionality using these descriptors, refer to <xref linkend="desc_examples"/>: + The <filename>*-object.xml</filename> descriptors define portal instances, pages, windows, and the window layout. As well, themes and layouts for specific portal instances, pages, and windows, can be defined. The following example defines a portlet window being added to the <computeroutput>default</computeroutput> page, in the <computeroutput>default</computeroutput> portal. For advanced functionality using these descriptors, refer to <xref linkend="desc_examples"/>: </para> <para> <programlisting><![CDATA[ @@ -1040,7 +1038,7 @@ <programlisting><![CDATA[<window>...</window>]]></programlisting> </para> <para> - The <computeroutput>&lt;window&gt;</computeroutput> element defines a portlet window. The <computeroutput>&lt;window&gt;</computeroutput> element requires an <computeroutput>&lt;instance-ref&gt;</computeroutput> element, which is used to assign a portal instance to a window. + The <computeroutput>&lt;window&gt;</computeroutput> element defines a portlet window. The <computeroutput>&lt;window&gt;</computeroutput> element requires an <computeroutput>&lt;instance-ref&gt;</computeroutput> element, which assigns a portal instance to a window. </para> </listitem> <listitem> @@ -1167,7 +1165,7 @@ </deployment>]]></programlisting> </para> <para> - The <computeroutput>&lt;deployment&gt;</computeroutput> element, and the embedded <computeroutput>&lt;instance&gt;</computeroutput> element, specify a portlet instance. The <computeroutput>&lt;deployment&gt;</computeroutput> element specifies object deployments, such as portals, pages, windows, and so on. The <computeroutput>&lt;instance&gt;</computeroutput> element is used to create instances of portlets. The portlet will only be created and configured if the portlet is present, and an instance with the same name does not already exist. + The <computeroutput>&lt;deployment&gt;</computeroutput> element, and the embedded <computeroutput>&lt;instance&gt;</computeroutput> element, specify a portlet instance. The <computeroutput>&lt;deployment&gt;</computeroutput> element specifies object deployments, such as portals, pages, windows, and so on. The <computeroutput>&lt;instance&gt;</computeroutput> element creates instances of portlets. The portlet will only be created and configured if the portlet is present, and an instance with the same name does not already exist. </para> </listitem> <listitem> @@ -1225,7 +1223,7 @@ The <computeroutput>&lt;security-constraint&gt;</computeroutput> element is a container for <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. This example demonstrates the <computeroutput>&lt;security-constraint&gt;</computeroutput> and <computeroutput>&lt;policy-permission&gt;</computeroutput> elements. </para> <para> - The <computeroutput>&lt;action-name&gt;</computeroutput> element is used to define the access rights given to the role defined. Accepted values are: + The <computeroutput>&lt;action-name&gt;</computeroutput> element defines the access rights given to the role defined. Accepted values are: </para> <para> <itemizedlist> @@ -1760,7 +1758,7 @@ &lt;if-exists&gt; </screen> <para> - The <computeroutput>&lt;if-exists&gt;</computeroutput> element is 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. + 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> <listitem> @@ -1784,7 +1782,7 @@ &lt;page&gt; </screen> <para> - The start of a page definition. Among others, the <computeroutput>&lt;page&gt;</computeroutput> element is a container for the <computeroutput>&lt;page-name&gt;</computeroutput>, <computeroutput>&lt;window&gt;</computeroutput>, and <computeroutput>&lt;security-contraint&gt;</computeroutput> elements. + The start of a page definition. Among others, the <computeroutput>&lt;page&gt;</computeroutput> element is a container for the <computeroutput>&lt;page-name&gt;</computeroutput>, <computeroutput>&lt;window&gt;</computeroutput>, and <computeroutput>&lt;security-constraint&gt;</computeroutput> elements. </para> </listitem> <listitem> @@ -1800,7 +1798,7 @@ &lt;window&gt; </screen> <para> - The <computeroutput>&lt;window&gt;</computeroutput> element defines a portlet window. The <computeroutput>&lt;window&gt;</computeroutput> element requires an <computeroutput>&lt;instance-ref&gt;</computeroutput> element, which is used to assign a portal instance to a window. + The <computeroutput>&lt;window&gt;</computeroutput> element defines a portlet window. The <computeroutput>&lt;window&gt;</computeroutput> element requires an <computeroutput>&lt;instance-ref&gt;</computeroutput> element, which assigns a portal instance to a window. </para> </listitem> <listitem> @@ -1828,19 +1826,114 @@ The <computeroutput>&lt;region&gt;</computeroutput> and <computeroutput>&lt;height&gt;</computeroutput> elements define where the window appears within the page layout. The <computeroutput>&lt;region&gt;</computeroutput> element specifies where the window appears on the page. The <computeroutput>&lt;region&gt;</computeroutput> element often depends on other regions defined in the portal layout. The <computeroutput>&lt;height&gt;</computeroutput> element can be assigned a value between one and <replaceable>X</replaceable>. </para> </listitem> - </listitem> - <listitem> - <emphasis role="bold">&lt;instance&gt;</emphasis> - The start of an instance - definition. page. - </listitem> - <listitem> - <emphasis role="bold">&lt;instance-name&gt;</emphasis> - Maps to the above - &lt;instance-ref&gt; variable. - </listitem> - <listitem> - <emphasis role="bold">&lt;component-ref&gt;</emphasis> + <listitem> +<screen> +&lt;instance&gt; +</screen> + <para> + The <computeroutput>&lt;instance&gt;</computeroutput> element creates instances of portlets. The portlet will only be created and configured if the portlet is present, and an instance with the same name does not already exist. + </para> + </listitem> + <listitem> +<screen> +&lt;instance-name&gt; +</screen> + <para> + The <computeroutput>&lt;instance-name&gt;</computeroutput> maps to the <computeroutput>&lt;instance-ref&gt;</computeroutput> element. + </para> + </listitem> + <listitem> +<screen> +&lt;component-ref&gt; +</screen> + <para> + The <computeroutput>&lt;component-ref&gt;</computeroutput> element takes the name of the application, followed by the name of the portlet, as defined in the <filename>WEB-INF/portlet.xml</filename> file. + </para> + </listitem> + </itemizedlist> +</para> +<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> +<screen><![CDATA[ +<security-constraint> + <policy-permission> + <role-name>User</role-name> + <action-name>view</action-name> + </policy-permission> +</security-constraint> + +<security-constraint> + <policy-permission> + <unchecked/> + <action-name>view</action-name> + </policy-permission> +</security-constraint>]]> +</screen> +</para> +<para> +<screen> +&lt;action-name&gt; +</screen> + </para> + <para> + The <computeroutput>&lt;action-name&gt;</computeroutput> element defines the access rights given to the role defined. Accepted values are: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <computeroutput>view</computeroutput>: users can view the page. + </para> + </listitem> + <listitem> + <para> + <computeroutput>viewrecursive</computeroutput>: users can view the page and child pages. + </para> + </listitem> + <listitem> + <para> + <computeroutput>personalize</computeroutput>: users are able personalize the page's theme. + </para> + </listitem> + <listitem> + <para> + <computeroutput>personalizerecursive</computeroutput>: users are able personalize the page and child pages themes. + </para> + </listitem> + </itemizedlist> + </para> + <para> + <screen><![CDATA[ + <!ELEMENT unchecked EMPTY>]]> + </screen> + </para> + <para> + If present, the <computeroutput>&lt;unchecked&gt;</computeroutput> element defines that anyone can view the instance. + </para> + <para> + <screen><![CDATA[ + <!ELEMENT role-name (#PCDATA)>]]> + </screen> + </para> + <para> + The <computeroutput>&lt;role-name&gt;</computeroutput> element defines 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: + </para> + <para> + <screen><![CDATA[ + <role-name>EXAMPLEROLE</role-name>]]> + </screen> + </para> + + + + + + + + + Takes the name of the application followed by the name of the portlet, as defined in the <emphasis>portlet.xml</emphasis>