Author: julien(a)jboss.com Date: 2007-02-13 17:58:50 -0500 (Tue, 13 Feb 2007) New Revision: 6256 Modified: docs/trunk/referenceGuide/en/modules/xmldescriptors.xml Log: added dtd descriptions Modified: docs/trunk/referenceGuide/en/modules/xmldescriptors.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/xmldescriptors.xml 2007-02-13 18:09:04 UTC (rev 6255) +++ docs/trunk/referenceGuide/en/modules/xmldescriptors.xml 2007-02-13 22:58:50 UTC (rev 6256) @@ -47,6 +47,657 @@ <listitem>For portlet-instances.xml descriptors: "-//JBoss Portal//DTD Portlet Instances 2.6//EN"</listitem> </itemizedlist> <para>Those files are available in the <emphasis>jboss-portal.sar/dtd/</emphasis> folder</para> + <sect2> + <title>JBoss Portlet DTD</title> + <para> +<itemizedlist> +<listitem> +<para> +Element <![CDATA[<!ELEMENT portlet-app (remotable?,portlet*,service*)> + +]]> +</para><para><programlisting><![CDATA[ +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. + +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?)> + +]]> +</para><para><programlisting><![CDATA[ +Additional configuration for a portlet. + +The portlet-name defines the name of the portlet. It must match a portlet defined already 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. + +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. + +Example: + +<portlet> + <portlet-name>MyPortlet</portlet-name> + <remotable>true</remotable> + <trans-attribute>Required</trans-attribute> +</portlet>]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT portlet-name (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The portlet name.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT remotable (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +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><para><programlisting><![CDATA[ +This element configure the portlet session of the portlet. + +The distributed element instructs the container to distribute the session attributes using the +portal session replication. It applies only to local portlets are not to remote portlets. +The default value is false. + +Example: + +<session-config> + <distributed>true</distributed> +</session-config>]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT distributed (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The authorized values for the distributed element are true or false.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT transaction (trans-attribute)> + +]]> +</para><para><programlisting><![CDATA[ +Defines how the portlet behaves with the transactionnal context. The default value +is Never. + +Example: + +<transaction> + <trans-attribute>Required</transaction> +<transaction>]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT trans-attribute (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The trans-attribute value defines the transactionnal behavior. The accepted values are Required, +Mandatory, Never, Supports, NotSupported and RequiresNew.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT header-content (link | script | meta)*> + +]]> +</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> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT link ANY> + +]]> +</para><para><programlisting><![CDATA[ +todo + check if ANY cannot be restricted]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT script ANY> + +]]> +</para><para><programlisting><![CDATA[ +todo + check if ANY cannot be restricted]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT meta ANY> + +]]> +</para><para><programlisting><![CDATA[ +todo + check if ANY cannot be restricted]]></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. + +Example : + +<service> + <service-name>UserModule</service-name> + <service-class>org.jboss.portal.identity.UserModule</service-class> + <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 : + +public void init() +{ + UserModule userModule = (UserModule)getPortletContext().getAttribute("UserModule"); +}]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT service-name (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The service name that will be used to bind the service as a portlet context attribute.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT service-class (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The full qualified name of the interface that the service implements.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT service-ref (#PCDATA)> + +]]> +</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> +</listitem></itemizedlist> + </para> + </sect2> + <sect2> + <title>Portlet Instance DTD</title> + <para> +<itemizedlist> +<listitem> +<para> +Element <![CDATA[<!ELEMENT deployments (deployment*)> + +]]> +</para><para><programlisting><![CDATA[ +The deployements element is a container for deployment elements.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT deployment (if-exists?,instance)> + +]]> +</para><para><programlisting><![CDATA[ +The deployment is a container for an instance element.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT if-exists (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT instance (instance-id,portlet-ref,preferences?,security-constraint?)> + +]]> +</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. + +Example : + +<instance> + <instance-id>MyPortletInstance</instance-id> + <portlet-ref>MyPortlet</portlet-ref> + <preferences> + <preference> + <name>abc</name> + <value>def</value> + </preference> + </preferences> + <security-constraint> + <policy-permission> + <role-name>User</role-name> + <action-name>view</action-name> + </policy-permission> + </security-constraint> +</instance>]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT instance-id (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The identifier of the instance.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT portlet-ref (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The reference to the portlet which is its portlet name.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT preferences (preference)> + +]]> +</para><para><programlisting><![CDATA[ +The preferences element configures the instance with a specific set of preferences.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT preference (name,value)> + +]]> +</para><para><programlisting><![CDATA[ +The preference configure one preference of a set of preferences.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT name (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +A name.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT value (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +A string value.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT security-constraint (policy-permission)> + +]]> +</para><para><programlisting><![CDATA[ +todo]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT policy-permission (action-name*,unchecked?,role-name*)> + +]]> +</para><para><programlisting><![CDATA[ +todo]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT action-name (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +todo]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT unchecked EMPTY> + +]]> +</para><para><programlisting><![CDATA[ +todo]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT role-name (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +todo]]></programlisting></para> +</listitem></itemizedlist> + </para> + </sect2> + <sect2> + <title>Portal Object DTD</title> + <para> +<itemizedlist> +<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: + +<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: + +<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-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> +Element <![CDATA[<!ELEMENT window-state (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +A window state value.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT page (page-name,properties?,listener?,security-constraint?,(page | window)*)> + +]]> +</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> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT page-name (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The page name value.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT window (window-name,(instance-ref | content),region,height,properties?,listener?)> + +]]> +</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. + +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> +<para> +Element <![CDATA[<!ELEMENT window-name (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The window name value.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT instance-ref (#PCDATA)> + +]]> +</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. + +Example: + +<instance-ref>MyPortletInstance</instance-ref>]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT content (content-type,content-uri)> + +]]> +</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. + +Example: + +<content> + <content-type>portlet</content-type> + <content-uri>MyPortletInstance</content-uri> +</content> + +<content> + <content-type>cms</content-type> + <content-uri>/default/index.html</content-uri> +</content>]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT content-type (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The content type of the window.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT content-uri (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The content URI of the window.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT region (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The region the window belongs to.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT height (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +The height of the window in the particular region.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT listener (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +Define a listener for a portal object. The value is the id of the listener.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT properties (property*)> + +]]> +</para><para><programlisting><![CDATA[ +A set of generic properties for the portal object.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT property (name,value)> + +]]> +</para><para><programlisting><![CDATA[ +A generic string property.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT name (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +A name value.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT value (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +A value.]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT security-constraint (policy-permission)> + +]]> +</para><para><programlisting><![CDATA[ +]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT policy-permission (action-name*,unchecked?,role-name*)> + +]]> +</para><para><programlisting><![CDATA[ +]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT action-name (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT unchecked EMPTY> + +]]> +</para><para><programlisting><![CDATA[ +]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT role-name (#PCDATA)> + +]]> +</para><para><programlisting><![CDATA[ +]]></programlisting></para> +</listitem></itemizedlist> + </para> + </sect2> + <sect2> + <title>JBoss App DTD</title> + <para> +<itemizedlist> +<listitem> +<para> +Element <![CDATA[<!ELEMENT jboss-app (app-name?)> + +]]> +</para><para><programlisting><![CDATA[ +<!DOCTYPE jboss-app PUBLIC + "-//JBoss Portal//DTD JBoss Web Application 2.6//EN" + "http://www.jboss.org/portal/dtd/jboss-app_2_6.dtd">]]></programlisting></para> +</listitem><listitem> +<para> +Element <![CDATA[<!ELEMENT app-name (#PCDATA)> + +]]> +</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> +</listitem></itemizedlist> + </para> + </sect2> </sect1> <sect1 id="descriptors_portlet"> <title>Portlet Descriptors</title>