Author: taylor
Date: Thu Dec 8 12:52:29 2005
New Revision: 355205
URL: http://svn.apache.org/viewcvs?rev=355205&view=rev
Log:
ajax api docs
Added:
portals/jetspeed-2/trunk/xdocs/guides/guide-ajax-api.xml
Added: portals/jetspeed-2/trunk/xdocs/guides/guide-ajax-api.xml
URL:
http://svn.apache.org/viewcvs/portals/jetspeed-2/trunk/xdocs/guides/guide-ajax-api.xml?rev=355205&view=auto
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-ajax-api.xml (added)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-ajax-api.xml Thu Dec 8
12:52:29 2005
@@ -0,0 +1,543 @@
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<document>
+ <properties>
+ <title>AJAX XML API</title>
+ <subtitle>Documentation for Jetspeed-2 AJAX XML API</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="[EMAIL PROTECTED]"/>
+ </authors>
+ </properties>
+ <body>
+<section name="AJAX XML API Overview">
+<p>
+The Jetspeed XML AJAX API is an XML-based API provided to AJAX clients for
making
+asynchronous requests to Jetspeed-2 services. </p>
+<p>
+Typical use cases:
+</p>
+<ul>
+ <li><b>Page Customization and Portlet Placement</b> - To move, copy, add,
or remove portlets on a page</li>
+ <li><b>Layout Selection</b> - change the layout (number of rows and
columns, size of columns) on a page</li>
+ <li><b>Theme and Decorator Selection</b> - change the page theme and
portlet decorators on a page.</li>
+ <li><b>Portlet Selectors</b> - provide a select-list of portlets to the
end user</li>
+ <li><b>Security Configuration</b> - configure the security constraints or
policy on a resource (page, portlet, folder, link, fragment), or portal
wide</li>
+ <li><b>Menu Configuration</b> - create and edit menus for the Jetspeed
Site</li>
+ <li><b>General Administration</b> - all use cases for general
administration have not yet been explored.</li>
+</ul>
+<subsection name='Secured Access'>
+<p>
+All AJAX XML API requests run through
+a standard Jetspeed <a href='guide-pipeline.html'>Pipeline</a> request. This
means that you can configure your AJAX
+request with the usual array of Jetspeed components. The default AJAX pipeline
secures
+access to all requests. Each AJAX action may have its own security
constraints. All
+requests made to a page will use the declarative security constraints
configured for that page.
+AJAX request actions are enforced under edit or view mode, depending on the
nature of the action.
+</p>
+</subsection>
+</section>
+<section name='API'>
+<p>
+The AJAX XML API is simply a HTTP request-based API, communicating over a
simple REST (Representational State Transfer) protocol.
+The API is accessed over HTTP via the "ajaxapi" servlet path on the portal URL:
+<source><![CDATA[
+http://hostname/contextname/ajaxapi
+]]></source>
+</p>
+<subsection name='Request Parameters and the Page'>
+<p>Request Parameters specify the requested API action, and additional API
parameters.
+The page that a request is referencing is implied in the HTTP URL.
+Thus if we are making a request to modify a page, the page is specified in the
HTTP URL:
+<source><![CDATA[
+http://localhost:8080/jetspeed/ajaxapi/Public/db-browser.psml
+]]></source>
+The page location algorithm using standard Jetspeed Profiling rules to locate
the page.
+A page is actually not required in the URL, since the <a
href='guide-profiler.html'>Jetspeed Profiler</a> will locate the page
+for you. Example:
+<source><![CDATA[
+http://localhost:8080/jetspeed/ajaxapi
+]]></source>
+goes to the default page for the current user.
+</p>
+<p>Request Parameters are specific to each API. One request parameter, the
"action" parameter,
+ is almost always required, (except in the default case). The default action
is "action=getpage"
+which returns an XML representation of the profile-located page in <a
href='guide-psml.html'>PSML</a>. (PSML is an XML format).
+See the table below for specific examples of request parameters.
+</p>
+<p>Here are the APIs currently available:
+</p>
+</subsection>
+<subsection name='Get Page'>
+<table>
+ <tr>
+ <td>API:</td>
+ <td>getpage</td>
+ </tr>
+ <tr>
+ <td>Component:</td>
+ <td>AjaxGetPage</td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>Get Page retrieves a page from the Page Manager store in <a
href='guide-psml.html'>PSML</a> format.
+ </td>
+ </tr>
+ <tr>
+ <td>Parameters:</td>
+ <table>
+ <tr>
+ <td>page</td>
+ <td>implied in the URL</td>
+ </tr>
+ <tr>
+ <td>action</td>
+ <td>getportlets (optional, this is the default
action)</td>
+ </tr>
+ </table>
+ </tr>
+ <tr>
+ <td>API example:</td>
+ <td>
+<source><![CDATA[
+http://localhost:8080/jetspeed/ajaxapi/Public/content.psml
+]]></source>
+ </td>
+ </tr>
+ <tr>
+ <td>XML Response:</td>
+ <td>
+<source><![CDATA[
+<js>
+<status>success</status>
+<action>getpage</action>
+ <page hidden="false">
+ <defaults layout-decorator="tigris" portlet-decorator="tigris"/>
+ <name>public.psml</name>
+ <path>/Public/public.psml</path>
+ <title>Public Share</title>
+ <short-title>Public Share</short-title>
+ <metadata name="title" xml:lang="es">Carpeta compartida</metadata>
+ <fragment id="ps-1000" type="layout"
name="jetspeed-layouts::VelocityTwoColumns" decorator="">
+ <fragment id="ps-1001" type="portlet" name="rss::RSS" decorator="">
+ <property name="row" value="0"/>
+ <property name="column" value="0"/>
+ </fragment>
+ <fragment id="ps-1002" type="portlet" name="demo::BookmarkPortlet"
decorator="">
+ <property name="row" value="1"/>
+ <property name="column" value="1"/>
+ </fragment>
+ <fragment id="ps-1003" type="portlet" name="jsf-demo::CalendarPortlet"
decorator="">
+ <property name="row" value="0"/>
+ <property name="column" value="1"/>
+ </fragment>
+ <fragment id="P-1080bff9b03-10000" type="portlet"
name="jsf-demo::CalendarPortlet" decorator="">
+ <property name="row" value="1"/>
+ <property name="column" value="0"/>
+ </fragment>
+ </fragment>
+</page>
+</js>
+]]></source>
+
+ </td>
+ </tr>
+</table>
+</subsection>
+<subsection name='Move Absolute'>
+<table>
+ <tr>
+ <td>API:</td>
+ <td>moveabs</td>
+ </tr>
+ <tr>
+ <td>Component:</td>
+ <td>AjaxMovePortletAbsolute</td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>Move a portlet on a page to an absolute position specified in the
row and col request parameters.</td>
+ </tr>
+ <tr>
+ <td>Parameters:</td>
+ <table>
+ <tr>
+ <td>page</td>
+ <td>implied in the URL</td>
+ </tr>
+ <tr>
+ <td>action</td>
+ <td>moveabs</td>
+ </tr>
+ <tr>
+ <td>id</td>
+ <td>the portlet PSML fragment id of the portlet
to be moved</td>
+ </tr>
+ <tr>
+ <td>row</td>
+ <td>the absolute new row location to place the
portlet fragment (zero based)</td>
+ </tr>
+ <tr>
+ <td>col</td>
+ <td>the absolute new column location to place
the portlet fragment (zero based)</td>
+ </tr>
+ </table>
+ </tr>
+ <tr>
+ <td>API example:</td>
+ <td>
+<source><![CDATA[
+http://localhost:8080/jetspeed/ajaxapi/Public/public.psml?action=moveabs&id=ps-1003&row=0&col=1
+]]></source>
+ </td>
+ </tr>
+ <tr>
+ <td>XML Response:</td>
+ <td>
+<source><![CDATA[
+<js>
+ <status>success</status>
+ <action>moveabs</action>
+ <id>ps-1003</id>
+ <old_position>
+ <col>1</col>
+ <row>1</row>
+ </old_position>
+ <new_position>
+ <col>1</col>
+ <row>0</row>
+ </new_position>
+</js>
+]]></source>
+
+ </td>
+ </tr>
+</table>
+</subsection>
+<subsection name='Move'>
+<table>
+ <tr>
+ <td>APIs:</td>
+ <td>moveleft, moveright, moveup, movedown</td>
+ </tr>
+ <tr>
+ <td>Components:</td>
+ <td>AjaxMovePortletLeft, AjaxMovePortletRight, AjaxMovePortletUp,
AjaxMoveDown</td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>Move a portlet on a page relatively one position, based on the
action.</td>
+ </tr>
+ <tr>
+ <td>Parameters:</td>
+ <table>
+ <tr>
+ <td>page</td>
+ <td>implied in the URL</td>
+ </tr>
+ <tr>
+ <td>action</td>
+ <td>moveleft, moveright, moveup, movedown</td>
+ </tr>
+ <tr>
+ <td>id</td>
+ <td>the portlet PSML fragment id of the portlet
to be moved</td>
+ </tr>
+ </table>
+ </tr>
+ <tr>
+ <td>API example:</td>
+ <td>
+<source><![CDATA[
+http://localhost:8080/jetspeed/ajaxapi/Public/public.psml?action=movedown&id=ps-1003
+]]></source>
+ </td>
+ </tr>
+ <tr>
+ <td>XML Response:</td>
+ <td>
+<source><![CDATA[
+<js>
+ <status>success</status>
+ <action>movedown</action>
+ <id>ps-1003</id>
+ <old_position>
+ <col>1</col>
+ <row>0</row>
+ </old_position>
+ <new_position>
+ <col>1</col>
+ <row>1</row>
+ </new_position>
+</js>
+]]></source>
+
+ </td>
+ </tr>
+
+</table>
+</subsection>
+<subsection name='Add Portlet'>
+<table>
+ <tr>
+ <td>API:</td>
+ <td>add</td>
+ </tr>
+ <tr>
+ <td>Component:</td>
+ <td>AjaxAddPortlet</td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>Adds a new portlet to the current page. The portlet can be added
at a specified row and column.
+ If either the row or column or not specified, defaults to
zero respectively.</td>
+ </tr>
+ <tr>
+ <td>Parameters:</td>
+ <table>
+ <tr>
+ <td>page</td>
+ <td>implied in the URL</td>
+ </tr>
+ <tr>
+ <td>action</td>
+ <td>add</td>
+ </tr>
+ <tr>
+ <td>id</td>
+ <td>The portlet full name to be placed on the
page, using Jetspeed Portlet Naming (PortletApplicationName::PortletName)</td>
+ </tr>
+ <tr>
+ <td>row</td>
+ <td>optional: the absolute new row location to
place the new portlet fragment (zero based)</td>
+ </tr>
+ <tr>
+ <td>col</td>
+ <td>optional: the absolute new column location
to place the new portlet fragment (zero based)</td>
+ </tr>
+ </table>
+ </tr>
+ <tr>
+ <td>API example:</td>
+ <td>
+<source><![CDATA[
+http://localhost:8080/jetspeed/ajaxapi/Public/public.psml?action=add&id=jsf-demo::CalendarPortlet
+]]></source>
+ </td>
+ </tr>
+ <tr>
+ <td>XML Response:</td>
+ <td>
+<source><![CDATA[
+<js>
+ <status>success</status>
+ <action>add</action>
+ <id>jsf-demo::CalendarPortlet</id>
+ <new_position>
+ <col>0</col>
+ <row>0</row>
+ </new_position>
+</js>
+]]></source>
+
+ </td>
+ </tr>
+</table>
+</subsection>
+<subsection name='Remove Portlet'>
+<table>
+
+ <tr>
+ <td>API:</td>
+ <td>remove</td>
+ </tr>
+ <tr>
+ <td>Component:</td>
+ <td>AjaxRemovePortlet</td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>Removes a new portlet from the current page.</td>
+ </tr>
+ <tr>
+ <td>Parameters:</td>
+ <table>
+ <tr>
+ <td>page</td>
+ <td>implied in the URL</td>
+ </tr>
+ <tr>
+ <td>action</td>
+ <td>remove</td>
+ </tr>
+ <tr>
+ <td>id</td>
+ <td>the portlet PSML fragment id of the portlet
to be removed</td>
+ </tr>
+ </table>
+ </tr>
+ <tr>
+ <td>API example:</td>
+ <td>
+<source><![CDATA[
+http://localhost:8080/jetspeed/ajaxapi/Public/public.psml?action=remove&id=ps-1003
+]]></source>
+ </td>
+ </tr>
+ <tr>
+ <td>XML Response:</td>
+ <td>
+<source><![CDATA[
+<js>
+ <status>success</status>
+ <action>remove</action>
+ <id>jsf-demo::CalendarPortlet</id>
+ <new_position>
+ <col>0</col>
+ <row>0</row>
+ </new_position>
+</js>
+]]></source>
+
+ </td>
+ </tr>
+</table>
+</subsection>
+<subsection name='Get Portlets'>
+<table>
+
+ <tr>
+ <td>API:</td>
+ <td>getportlets</td>
+ </tr>
+ <tr>
+ <td>Component:</td>
+ <td>AjaxGetPortlets</td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>Get Portlets retrieves the (sorted) portlet list available to the
current subject, filtered
+ the portlet list, and returning portlets which the current
subject may view.
+ The Jetspeed (JAAS) security policy enforces this
filtering. Portlets are returned
+ in XML format, with name, displayName, and description for
each portlet.</td>
+ </tr>
+ <tr>
+ <td>Parameters:</td>
+ <table>
+ <tr>
+ <td>page</td>
+ <td>implied in the URL</td>
+ </tr>
+ <tr>
+ <td>action</td>
+ <td>getportlets</td>
+ </tr>
+ <tr>
+ <td>filter</td>
+ <td>not yet implemented. A query filter to be
defined.</td>
+ </tr>
+
+ </table>
+ </tr>
+ <tr>
+ <td>API example:</td>
+ <td>
+<source><![CDATA[
+http://localhost:8080/jetspeed/ajaxapi?action=getportlets
+]]></source>
+ </td>
+ </tr>
+ <tr>
+ <td>XML Response:</td>
+ <td>
+<source><![CDATA[
+<js>
+<status>success</status>
+<action>getportlets</action>
+-
+ <portlets>
+<portlet name="demo::AttributeScopePortlet" displayName="Attribute Scope Demo"
description="$portlet.Description">
+ </portlet>
+<portlet name="demo::BookmarkPortlet" displayName="Bookmark Portlet"
description="Bookmark Portlet">
+ </portlet>
+<portlet name="demo::BookmarkPortletForXHTMLBasic" displayName="Bookmark
Portlet for XHTML Basic" description="Bookmark Portlet for XHTML Basic">
+ </portlet>
+<portlet name="demo::CSSDemoPortlet" displayName="CSS Demo Portlet"
description="$portlet.Description">
+ </portlet>
+....
+<portlet name="rss::RSS" displayName="RSS Portlet" description="RSS Portlet">
+ </portlet>
+<portlet name="rss::RomeRSS" displayName="Rome RSS Portlet" description="Rome
RSS Portlet">
+ </portlet>
+</portlets>
+</js>
+]]></source>
+
+ </td>
+ </tr>
+</table>
+</subsection>
+</section>
+
+<section name='Spring Assembly'>
+<p>
+The <code>AjaxRequestService</code> is a Spring component that handles AJAX
requests.
+It is hooked into the AJAX <a href='guide-pipeline.html'>Pipeline</a> for
special processing
+of AJAX request. Here is the Spring Assembly. Each API is configured in the
Ajax Service.
+</p>
+<source><![CDATA[
+<bean id="AjaxRequestService"
class="org.apache.jetspeed.ajax.AjaxRequestServiceImpl">
+ <constructor-arg index="0">
+ <map>
+ <entry key="moveabs">
+ <ref bean="AjaxMovePortletAbsolute"/>
+ </entry>
+ <entry key="moveleft">
+ <ref bean="AjaxMovePortletLeft"/>
+ </entry>
+ <entry key="moveright">
+ <ref bean="AjaxMovePortletRight"/>
+ </entry>
+ <entry key="moveup">
+ <ref bean="AjaxMovePortletUp"/>
+ </entry>
+ <entry key="movedown">
+ <ref bean="AjaxMovePortletDown"/>
+ </entry>
+ <entry key="add">
+ <ref bean="AjaxAddPortlet"/>
+ </entry>
+ <entry key="remove">
+ <ref bean="AjaxRemovePortlet"/>
+ </entry>
+ <entry key="getportlets">
+ <ref bean="AjaxGetPortlets"/>
+ </entry>
+ <entry key="getpage">
+ <ref bean="AjaxGetPage"/>
+ </entry>
+ </map>
+ </constructor-arg>
+ <constructor-arg index="1">
+ <ref bean="AjaxVelocityEngine"/>
+ </constructor-arg>
+</bean>
+]]></source>
+
+</section>
+</body>
+</document>
+
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
