portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tay...@apache.org
Subject svn commit: r355205 - /portals/jetspeed-2/trunk/xdocs/guides/guide-ajax-api.xml
Date Thu, 08 Dec 2005 20:52:30 GMT
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="taylor@apache.org"/>
+    </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: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org


Mime
View raw message