Author: bdaw Date: 2007-05-02 03:59:09 -0400 (Wed, 02 May 2007) New Revision: 7172 Modified: docs/trunk/referenceGuide/en/modules/xmldescriptors.xml Log: - update dtd description in XML chapter Modified: docs/trunk/referenceGuide/en/modules/xmldescriptors.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/xmldescriptors.xml 2007-05-02 07:58:28 UTC (rev 7171) +++ docs/trunk/referenceGuide/en/modules/xmldescriptors.xml 2007-05-02 07:59:09 UTC (rev 7172) @@ -57,17 +57,17 @@ ]]> </para><para><programlisting><![CDATA[ -The remotable element is used to configure the default behavior of the portlets with respect -to WSRP exposure. +The remotable element is used to configure the default behavior of the portlets with +respect to WSRP exposure. -For each portlet defined in portlet.xml, it is possible to configure specific settings -of the portlet container. +For each portlet defined in portlet.xml, it is possible to configure specific +settings of the portlet container. -It is also possible to inject services in the portlet context of the application using the -service elements.]]></programlisting></para> +It is also possible to inject services in the portlet context of the application +using the service elements.]]></programlisting></para> </listitem><listitem> <para> -Element <![CDATA[<!ELEMENT portlet (portlet-name,remotable?,session-config?,transaction?,header-content?)> +Element <![CDATA[<!ELEMENT portlet (portlet-name,remotable?,ajax?,session-config?,transaction?,header-content?)> ]]> </para><para><programlisting><![CDATA[ @@ -77,15 +77,15 @@ in portlet.xml of the same web application. The remotable element configures the portlet exposure to WSRP. If no value is present -then the value considered is either the value defined globally at the portlet application -level or false. +then the value considered is either the value defined globally at the portlet +application level or false. The trans-attribute value specifies the behavior of the portlet when it is invoked at runtime with respect to the transactionnal context. According to how the portlet is invoked a transaction may exist or not before the portlet is invoked. Usually in the -local context the portal transaction could be present. By default the value -considered is NotSupported which means that the portal transaction will be suspended -for the duration of the portlet invocation. +local context the portal transaction could be present. By default the value considered is + NotSupported which means that the portal transaction will be suspended for the duration + of the portlet invocation. Example: @@ -107,15 +107,31 @@ ]]> </para><para><programlisting><![CDATA[ -The remotable value is used for WSRP exposure. -The accepted values are the litterals true of false.]]> -</programlisting></para> +The remotable value is used for WSRP exposure. The accepted values are the +litterals true of false.]]></programlisting></para> </listitem><listitem> - <para> - Element <![CDATA[<!ELEMENT session-config (distributed)> +<para> +Element <![CDATA[<!ELEMENT ajax (partial-refresh)> ]]> </para><para><programlisting><![CDATA[ +The ajax tag allows to configure the ajax capabilities of the portlet. If +the portlet is tagged as partial-refresh then the portal may use partial page +refreshing and render only that portlet. If the portlet partial-refresh value +is false, then the portal will perform a full page refresh when the portlet is refreshed.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT partial-refresh (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The authorized values for the partial-refresh element are true or false.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT session-config (distributed)> + +]]> +</para><para><programlisting><![CDATA[ This element configure the portlet session of the portlet. The distributed element instructs the container to distribute the session attributes @@ -162,40 +178,39 @@ ]]> </para><para><programlisting><![CDATA[ -Specify content which should be included in the portal aggregated page when the -portlet is present on that page. This setting only applies when the portlet is -used in the local mode.]]></programlisting></para> +Specify content which should be included in the portal aggregated page when the portlet +is present on that page. This setting only applies when the portlet is used in the local mode.]]></programlisting></para> </listitem><listitem> <para> -Element <![CDATA[<!ELEMENT link ANY> +Element <![CDATA[<!ELEMENT link EMPTY> ]]> </para><para><programlisting><![CDATA[ -todo + check if ANY cannot be restricted]]></programlisting></para> +No content is allowed inside an link element.]]></programlisting></para> </listitem><listitem> <para> -Element <![CDATA[<!ELEMENT script ANY> +Element <![CDATA[<!ELEMENT script (#PCDATA)> ]]> </para><para><programlisting><![CDATA[ -todo + check if ANY cannot be restricted]]></programlisting></para> +The script header element can contain inline script definitions.]]></programlisting></para> </listitem><listitem> <para> -Element <![CDATA[<!ELEMENT meta ANY> +Element <![CDATA[<!ELEMENT meta EMPTY> ]]> </para><para><programlisting><![CDATA[ -todo + check if ANY cannot be restricted]]></programlisting></para> +No content is allowed for meta element.]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT service (service-name,service-class,service-ref)> ]]> </para><para><programlisting><![CDATA[ -Declare a service that will be injected by the portlet container as an attribute -of the portlet context. +Declare a service that will be injected by the portlet container as an +attribute of the portlet context. -Example : +Example: <service> <service-name>UserModule</service-name> @@ -203,8 +218,8 @@ <service-ref>:service=Module,type=User</service-ref> </service> -In the portlet it is then possible to use it by doing a lookup on the service name, -for example in the init() lifecycle method : +In the portlet it is then possible to use it by doing a lookup on the service +name, for example in the init() lifecycle method : public void init() { @@ -230,10 +245,11 @@ ]]> </para><para><programlisting><![CDATA[ -The reference to the service. In the JMX Microkernel environment it consist of the -JMX name of the service MBean. For an MBean reference if the domain is left out, -then the current domain of the portal will be used.]]></programlisting></para> +The reference to the service. In the JMX Microkernel environment it consist of the JMX +name of the service MBean. For an MBean reference if the domain is left out, then the +current domain of the portal will be used.]]></programlisting></para> </listitem></itemizedlist> + </para> </sect2> <sect2> @@ -260,7 +276,11 @@ ]]> </para><para><programlisting><![CDATA[ -]]></programlisting></para> +The if-exists element is used to define action to take if instance with such name is +already present. Possible values are overwrite or keep . Overwrite will destroy the +existing object in the database and create a new one, based on the content of the +deployment. Keep will maintain the existing object deployment or create a new one if +it does not yet exist.]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT instance (instance-id,portlet-ref,preferences?,security-constraint?)> @@ -268,9 +288,9 @@ ]]> </para><para><programlisting><![CDATA[ The instance element is used to create an instance of a portlet from the portlet -application of the same war file containing the portlet-instances.xml file. -The portlet will be created and configured only if the portlet is present -and an instance with such a name does not already exist. +application of the same war file containing the portlet-instances.xml file. The portlet +will be created and configured only if the portlet is present and an instance with +such a name does not already exist. Example : @@ -334,39 +354,64 @@ A string value.]]></programlisting></para> </listitem><listitem> <para> -Element <![CDATA[<!ELEMENT security-constraint (policy-permission)> +Element <![CDATA[<!ELEMENT security-constraint (policy-permission*)> ]]> </para><para><programlisting><![CDATA[ -todo]]></programlisting></para> +The security-constraint element is a container for policy-permission elements + +Examples: + +<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>]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT policy-permission (action-name*,unchecked?,role-name*)> ]]> </para><para><programlisting><![CDATA[ -todo]]></programlisting></para> +The policy-permission element is used to secure a specific portlet instance based on a user's role.]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT action-name (#PCDATA)> ]]> </para><para><programlisting><![CDATA[ -todo]]></programlisting></para> +The action-name element is used to define the access rights given to the role defined. +Possible values are: + + * view - Users can view the page. + * viewrecursive - Users can view the page and child pages. + * personalize - Users are able to view AND personalize the page. + * personalizerecursive - Users are able to view AND personalize the page AND its child + pages.]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT unchecked EMPTY> ]]> </para><para><programlisting><![CDATA[ -todo]]></programlisting></para> +The unchecked element is used to define (if present) that anyone can view this instance]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT role-name (#PCDATA)> ]]> </para><para><programlisting><![CDATA[ -todo]]></programlisting></para> +The role-name element is used to define a role that this security constraint will apply to + + * <role-name>SOMEROLE</role-name> Access to this instance is limited to the defined role.]]></programlisting></para> </listitem></itemizedlist> </para> </sect2> @@ -389,10 +434,10 @@ </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. +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: @@ -405,12 +450,11 @@ 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. +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. +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> @@ -426,9 +470,11 @@ 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> +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)> @@ -436,8 +482,8 @@ ]]> </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> +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*)> @@ -445,8 +491,8 @@ ]]> </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> +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)> @@ -461,10 +507,10 @@ ]]> </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> +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)> @@ -522,9 +568,9 @@ ]]> </para><para><programlisting><![CDATA[ -A portal object of type page. A page type represents a page which can have children -of type page and window. The children windows are the windows of the page and the -children pages are the subpages of this page.]]></programlisting></para> +A portal object of type page. A page type represents a page which can have children of +type page and window. The children windows are the windows of the page and the children +pages are the subpages of this page.]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT page-name (#PCDATA)> @@ -538,13 +584,13 @@ ]]> </para><para><programlisting><![CDATA[ -A portal object of type window. A window type represents a window. Beside -the common properties a window has a content and belong to a region on the page. +A portal object of type window. A window type represents a window. Beside the common +properties a window has a content and belong to a region on the page. -The instance-ref or content tags are used to define the content of the window. -The usage of the content tag is generic and can be used to describe any kind of -content. The instance-ref is a shortcut to define a content type of portlet -which points to a portlet instance. +The instance-ref or content tags are used to define the content of the window. The +usage of the content tag is generic and can be used to describe any kind of content. +The instance-ref is a shortcut to define a content type of portlet which points to a +portlet instance. The region and height defines how the window is placed in the page.]]></programlisting></para> </listitem><listitem> @@ -560,8 +606,8 @@ ]]> </para><para><programlisting><![CDATA[ -Define the content of the window as a reference to a portlet instance. -The value is the id of the instance. +Define the content of the window as a reference to a portlet instance. The value +is the id of the instance. Example: @@ -572,8 +618,8 @@ ]]> </para><para><programlisting><![CDATA[ -Define the content of the window in a generic manner. The content is define -by the type of the content and an URI which acts as an identificator for the content. +Define the content of the window in a generic manner. The content is define by +the type of the content and an URI which acts as an identificator for the content. Example: @@ -651,40 +697,62 @@ A value.]]></programlisting></para> </listitem><listitem> <para> -Element <![CDATA[<!ELEMENT security-constraint (policy-permission)> +Element <![CDATA[<!ELEMENT security-constraint (policy-permission*)> ]]> </para><para><programlisting><![CDATA[ -]]></programlisting></para> +The security-constraint element is a container for policy-permission elements + +Examples: + +<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>]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT policy-permission (action-name*,unchecked?,role-name*)> ]]> </para><para><programlisting><![CDATA[ -]]></programlisting></para> +The policy-permission element is used to secure a specific portal page based on a user's role.]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT action-name (#PCDATA)> ]]> </para><para><programlisting><![CDATA[ -]]></programlisting></para> +The role-name element is used to define a role that this security constraint will apply to + + * <role-name>SOMEROLE</role-name> Access to this portal page is limited to the defined role.]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT unchecked EMPTY> ]]> </para><para><programlisting><![CDATA[ -]]></programlisting></para> +The unchecked element is used to define (if present) that anyone can view this portal page]]></programlisting></para> </listitem><listitem> <para> Element <![CDATA[<!ELEMENT role-name (#PCDATA)> ]]> </para><para><programlisting><![CDATA[ -]]></programlisting></para> +The action-name element is used to define the access rights given to the role defined. +Possible values are: + + * view - Users can view the page.]]></programlisting></para> </listitem></itemizedlist> + </para> </sect2> <sect2> @@ -708,12 +776,12 @@ </para><para><programlisting><![CDATA[ When a web application is deployed, the context path under wich it is deployed is taken as application name. The application name value in this descriptor is -used to override it. When a component references a references a portlet, it -needs to reference the application too and if the portlet application war file -is renammed the reference is not valid anymore. Therefore this tag is used to -have an application name that does not depend upon the context path under which -the application is deployed.]]></programlisting></para> +used to override it. When a component references a references a portlet, it needs to +reference the application too and if the portlet application war file is renammed +the reference is not valid anymore. Therefore this tag is used to have an application +name that does not depend upon the context path under which the application is deployed.]]></programlisting></para> </listitem></itemizedlist> + </para> </sect2> </sect1>