You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jetspeed-dev@portals.apache.org by ra...@apache.org on 2002/11/13 18:26:09 UTC

cvs commit: jakarta-jetspeed/xdocs registry_syntax.xml

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:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>