raphael 2002/11/13 09:26:09
Modified: xdocs registry_syntax.xml
Log:
complete Registry DTD and portlet-entry description
Revision Changes Path
1.2 +298 -63 jakarta-jetspeed/xdocs/registry_syntax.xml
Index: registry_syntax.xml
===================================================================
RCS file: /home/cvs/jakarta-jetspeed/xdocs/registry_syntax.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- registry_syntax.xml 13 Nov 2002 08:42:42 -0000 1.1
+++ registry_syntax.xml 13 Nov 2002 17:26:09 -0000 1.2
@@ -27,11 +27,14 @@
</ul>
</section>
<section name="Registry">
- <p>
- The registry element needs to be the root elements of any registry fragment.
- It can contains any of the currently defined entries.
- </p>
- <source><![CDATA[
+ <subsection name="Overview">
+ <p>
+ The registry element needs to be the root elements of any registry fragment.
+ It can contains any of the currently defined entries.
+ </p>
+ </subsection>
+ <subsection name="DTD">
+ <source><![CDATA[
<!ELEMENT registry ( portlet-entry*,
portlet-control-entry*,
portlet-controller-entry*,
@@ -42,58 +45,258 @@
)>
<!ATTLIST registry
version CDATA "1.0">
- ]]></source>
+ ]]></source>
+ </subsection>
</section>
<section name="Portlet">
- <p>
- The <code>portlet-entry</code> element
- </p>
- <source><![CDATA[
-<!ELEMENT portlet-entry ( portlet-entry*,
- portlet-control-entry*,
- portlet-controller-entry*,
- skin-entry*,
- media-type-entry*,
- client-entry*,
- security-entry*
- )>
- ]]></source>
+ <subsection name="Overview">
+ <p>
+ The <code>portlet-entry</code> element is the main element encountered in the
Registry.
+ It describes a Portlet object that can be used within a portal page
description.
+ </p>
+ <p>
+ There are 3 main types of <code>portlet-entry</code> definitions,
controlled by
+ the value of the <code>type</code> attribute in the entry:
+ </p>
+ <dl>
+ <dt><strong>abstract</strong></dt>
+ <dd>
+ <p>These portlets cannot be used directly in a portlet page and simply
provide
+ a configuration template for creating ref portlet-entry.</p>
+ <p>The <code>classname</code> element is required in an abstract
portlet</p>
+ </dd>
+ <dt><strong>instance</strong></dt>
+ <dd>
+ <p>
+ These are the default portlet entries created within the registry and
describe
+ standard Java component complying to the Portlet API that can be added
directly
+ within a portal page.
+ </p>
+ <p>The <code>classname</code> element is required in an instance
portlet</p>
+ </dd>
+ <dt><strong>ref</strong></dt>
+ <dd>
+ <p>
+ These entries are the more frequently encountered definitions in the
registry.
+ They define portlets that reference another existing portlet entry in
the registry,
+ yet override or complement the previous definitions with additionnal
parameters.
+ </p>
+ <p>
+ The <code>parent</code> attribute is required in a ref portlet and must
refer another
+ existing abstract or instance portlet, but not another ref portlet.<br
/>
+ The <code>classname</code> element should not occur within a ref prtlet
definition.
+ </p>
+ </dd>
+ </dl>
+ <p>
+ In addition to the <code>type</code> attribute, portlet entries can also
use standard
+ attributes and elements that can be used in most other registry entries and
are explained
+ <a href="registry_syntax.html#Standard">here</a>
+ </p>
+ </subsection>
+ <subsection name="DTD">
+ <source><![CDATA[
+<!ELEMENT portlet-entry ( security?,
+ security-ref?,
+ meta-info?,
+ classname?,
+ parameter*,
+ media-type*,
+ url?,
+ category* )>
+<!ATTLIST portlet-entry
+ name ID #REQUIRED
+ hidden ( true | false ) "false"
+ type ( abstract | instance | ref ) "instance"
+ application ( true | false ) "false"
+ parent IDREF #IMPLIED >
+
+<!ELEMENT parameter ( security?, security-ref?, meta-info? )>
+<!ATTLIST parameter
+ name CDATA #REQUIRED
+ value CDATA #REQUIRED
+ type (int | boolean | string | list) "string"
+ cachedOnName ( true | false ) "false"
+ cachedOnValue ( true | false ) "false" >
+
+<!ELEMENT classname CDATA>
+
+<!ELEMENT meta-info ( title?, description?, image? ) >
+<!ELEMENT title CDATA>
+<!ELEMENT description CDATA>
+<!ELEMENT image CDATA>
+
+<!ELEMENT media-type EMPTY>
+<!ATTLIST media-type
+ ref IDREF #REQUIRED >
+
+<!ELEMENT url CDATA>
+<!ATTLIST url
+ cachedOnUrl ( true | false ) "false" >
+
+<!ELEMENT category CDATA>
+<!ATTLIST category
+ group CDATA #IMPLIED >
+ ]]></source>
+ </subsection>
+ <subsection name="Usage notes">
+ <h2>Parameter handling</h2>
+ <p>
+ Some parameters have special meanings when encountered in a
<code>portlet-entry</code>
+ defintion:
+ </p>
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Minimum<br/>Version</th>
+ <th>Usage</th>
+ </tr>
+ <tr>
+ <th>_showtitlebar</th>
+ <td>1.4b1</td>
+ <td>
+ Will cause the default portlet control not to draw any title bar around
the portlet.
+ This behavior is deprecated 1.4b2 and replaced by the more powerful
<code>_control</code>
+ attribute associated with a no title bar control like "ClearControl"
+ </td>
+ </tr>
+ <tr>
+ <th>_control</th>
+ <td>1.4b2</td>
+ <td>
+ Will cause any new instance of this <code>portlet-entry</code> to be
associated with the
+ control specified in the parameter value when added to a portal page.
+ </td>
+ </tr>
+ </table>
+ <p>
+ Also note that any parameter starting with a "_" will not be ignored by the
default
+ portlet customizer.
+ </p>
+ </subsection>
+ <subsection name="Examples">
+ <p>
+ The first example presents a minimal abstract type portlet definition.
+ Note that it's defined as hidden to prevent the entry from showing up
+ when browsing for portlets
+ </p>
+ <source><![CDATA[
+<portlet-entry name="Velocity" type="abstract" hidden="true">
+ <classname>org.apache.jetspeed.portal.portlets.VelocityPortlet</classname>
+</portlet-entry>
+ ]]></source>
+ <p>
+ The second example provides a standard instance type portlet definition.
+ </p>
+ <source><![CDATA[
+<portlet-entry name="JetspeedContent" type="instance">
+ <meta-info>
+ <title>Jetspeed Content Example</title>
+ <description>Example of Jetspeed Content portlet.</description>
+ </meta-info>
+ <classname>org.apache.jetspeed.portal.portlets.JetspeedContent</classname>
+ <parameter name="provider-name" value="jetspeed" hidden="false"/>
+ <media-type ref="html"/>
+</portlet-entry>
+ ]]></source>
+ <p>
+ The third example shows how to reference the above abstract definition
+ and add additionnal parameters that will specify the actual behavior of
+ the portlet.
+ </p>
+ <source><![CDATA[
+<portlet-entry name="SecurityExample" type="ref" parent="Velocity">
+ <security-ref parent="user-view_admin-all"/>
+ <meta-info>
+ <title>SecurityExample</title>
+ <description>Simple Security Example</description>
+ </meta-info>
+ <parameter name="template" value="SecurityExample" hidden="false"/>
+ <media-type ref="html"/>
+ <category>demo</category>
+ <category>velocity.demo</category>
+</portlet-entry>
+ ]]></source>
+ </subsection>
</section>
<section name="Control">
- <p>
- The <code>portlet-control-entry</code> element
- </p>
- <source><![CDATA[
-<!ELEMENT portlet-control-entry ( portlet-entry*,
- portlet-control-entry*,
- portlet-controller-entry*,
- skin-entry*,
- media-type-entry*,
- client-entry*,
- security-entry*
- )>
- ]]></source>
+ <subsection name="Overview">
+ <p>
+ The <code>portlet-control-entry</code> element defines
+ </p>
+ </subsection>
+ <subsection name="DTD">
+ <source><![CDATA[
+<!ELEMENT portlet-control-entry ( security?,
+ security-ref?,
+ meta-info?,
+ classname?,
+ parameter*,
+ media-type+ )>
+<!ATTLIST portlet-control-entry
+ name ID #REQUIRED
+ hidden ( true | false ) "false" >
+
+<!ELEMENT parameter ( security?, security-ref?, meta-info? )>
+<!ATTLIST parameter
+ name CDATA #REQUIRED
+ value CDATA #REQUIRED
+ type (int | boolean | string | list) "string" >
+
+<!ELEMENT classname CDATA>
+
+<!ELEMENT meta-info ( title?, description?, image? ) >
+<!ELEMENT title CDATA>
+<!ELEMENT description CDATA>
+<!ELEMENT image CDATA>
+
+<!ELEMENT media-type EMPTY>
+<!ATTLIST media-type
+ ref IDREF #REQUIRED >
+ ]]></source>
+ </subsection>
+ <subsection name="Usage notes">
+ </subsection>
+ <subsection name="Examples">
+ </subsection>
</section>
<section name="Controller">
- <p>
+ <subsection name="Overview">
+ <p>
The <code>portlet-controller-entry</code> element
- </p>
- <source><![CDATA[
-<!ELEMENT portlet-controller-entry ( portlet-entry*,
- portlet-control-entry*,
- portlet-controller-entry*,
- skin-entry*,
- media-type-entry*,
- client-entry*,
- security-entry*
- )>
- ]]></source>
+ </p>
+ </subsection>
+ <subsection name="DTD">
+ <source><![CDATA[
+<!ELEMENT portlet-controller-entry ( parameter*, media-type+ )>
+<!ATTLIST portlet-controller-entry
+ name ID #REQUIRED
+ hidden ( true | false ) "false" >
+
+<!ELEMENT parameter EMPTY>
+<!ATTLIST parameter
+ name CDATA #REQUIRED
+ value CDATA #REQUIRED
+ type (int | boolean | string | list) "string" >
+
+<!ELEMENT media-type EMPTY>
+<!ATTLIST media-type
+ ref IDREF #REQUIRED >
+ ]]></source>
+ </subsection>
+ <subsection name="Usage notes">
+ </subsection>
+ <subsection name="Examples">
+ </subsection>
</section>
<section name="Skin">
- <p>
+ <subsection name="Overview">
+ <p>
The <code>skin-entry</code> element
- </p>
- <source><![CDATA[
+ </p>
+ </subsection>
+ <subsection name="DTD">
+ <source><![CDATA[
<!ELEMENT skin-entry ( property+ )>
<!ATTLIST skin-entry
name ID #REQUIRED
@@ -105,13 +308,21 @@
value CDATA #REQUIRED
type (int | boolean | string | list) "string" >
- ]]></source>
+ ]]></source>
+ </subsection>
+ <subsection name="Usage notes">
+ </subsection>
+ <subsection name="Examples">
+ </subsection>
</section>
<section name="Media">
- <p>
+ <subsection name="Overview">
+ <p>
The <code>media-type-entry</code> element
- </p>
- <source><![CDATA[
+ </p>
+ </subsection>
+ <subsection name="DTD">
+ <source><![CDATA[
<!ELEMENT media-type-entry ( mime-type,
character-set?,
capability-map?
@@ -125,13 +336,21 @@
<!ELEMENT capability-map ( capability* )>
<!ELEMENT capability CDATA>
- ]]></source>
+ ]]></source>
+ </subsection>
+ <subsection name="Usage notes">
+ </subsection>
+ <subsection name="Examples">
+ </subsection>
</section>
<section name="Client">
- <p>
+ <subsection name="Overview">
+ <p>
The <code>client-entry</code> element
- </p>
- <source><![CDATA[
+ </p>
+ </subsection>
+ <subsection name="DTD">
+ <source><![CDATA[
<!ELEMENT client-entry ( user-agent-pattern,
manufacturer,
model,
@@ -153,13 +372,24 @@
<!ELEMENT capability-map ( capability* )>
<!ELEMENT capability CDATA>
- ]]></source>
+ ]]></source>
+ </subsection>
+ <subsection name="Usage notes">
+ </subsection>
+ <subsection name="Examples">
+ </subsection>
</section>
<section name="Security">
- <p>
- The <code>security-entry</code> element
- </p>
- <source><![CDATA[
+ <subsection name="Overview">
+ <p>
+ The <code>security-entry</code> element is used to describe standard sets
+ of access rules that can be used to protect portal elements or actions.
+ These security entry are referenced by the other types of registry entries
+ by using the <code>security-ref</code> element.
+ </p>
+ </subsection>
+ <subsection name="DTD">
+ <source><![CDATA[
<!ELEMENT security-entry ( meta-info?, access+ )>
<!ATTLIST security-entry
name ID #REQUIRED >
@@ -173,8 +403,12 @@
role CDATA #REQUIRED >
<!ELEMENT allow-if-owner EMPTY>
- ]]></source>
- <source><![CDATA[
+ ]]></source>
+ </subsection>
+ <subsection name="Usage notes">
+ </subsection>
+ <subsection name="Examples">
+ <source><![CDATA[
<security-entry name="user-view_admin-all">
<meta-info>
<title>Users+V and Admin+C</title>
@@ -187,7 +421,8 @@
<allow-if role="user"/>
</access>
</security-entry>
- ]]></source>
+ ]]></source>
+ </subsection>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:jetspeed-dev-unsubscribe@;jakarta.apache.org>
For additional commands, e-mail: <mailto:jetspeed-dev-help@;jakarta.apache.org>
