[jboss-svn-commits] JBoss Portal SVN: r5126 - branches/tomek/portal-dnd

[jboss-svn-commits at lists.jboss.org]

Author: szimano
Date: 2006-08-31 16:15:33 -0400 (Thu, 31 Aug 2006)
New Revision: 5126

Added:
   branches/tomek/portal-dnd/README
Log:
readme file for portaldnd


Added: branches/tomek/portal-dnd/README
===================================================================
--- branches/tomek/portal-dnd/README	2006-08-31 15:21:41 UTC (rev 5125)
+++ branches/tomek/portal-dnd/README	2006-08-31 20:15:33 UTC (rev 5126)
@@ -0,0 +1,58 @@
+******************
+ Portal DnD Guide
+******************
+
+Tomasz Szymanski (tomasz.szymanski at jboss.com)
+
+1. Project Structure
+
+	Jesuit - Jesuit files, testRunner, needed jars 
+	lib - libraries needed to build as standalone project (portal and jboss libs)
+	src - source code
+	test - test files
+	build.xml - simple ant script for building
+	dndRenderer.war - YAHOO library scripts, dnd.properties, descriptors
+	README - this readme file
+
+	Whole DnD logic is basically 4 renderers (plus a helping DnDTool class) stored in src/java/org/jboss/portal/core/theme/render/impl/ and a AjaxServlet handling ajax calls + skeleton for persistence in src/java/org/jboss/portal/dnd/
+
+	In dndRenderer.war there's an important dnd.properties file that has a definition of what renderer classes should it use. This should probably be achievable also by passing properties in -object.xml files.
+
+	In that directory there's also whole YAHOO js library with additional /js/portal/PortalDD.js file - extended DDProxy object with some features needed for dragging and dropping portlets.
+
+	Other modification is in /js/connection/connection.js - that allows invoking synchronous callback instead of asynchronous. This is used for testing.
+
+	
+2. Workflow
+
+	All DnDRenderers load appropriate renderers, specified in dnd.properties and execute their functions, adding some html/javascript around it.
+
+	DnDRegionRenederer adds whole javascript definitions (see DnDTools.java), wraps every region in <div></div> (so if there is no container in current renderer around one region it will still work) and adds YAHOO PortalDD definitions for every portlet.
+
+	It also sets for the portlet div container some extra attributes - ID of "DROP TO" object and id of this region and windowid for portlet object.
+
+	DnDWindowRenderer adds <div></div> around every portlet and makes it draggable. It also adds invisible by default "DROP TO" object that is showed up when there's no any portlets in region left (of course one per region).
+
+	When portlet is dragged YAHOO.util.PortalDD.prototype.onDragDrop gets executed automatically when its hoovered around other PortalDD object. The most important logic is there - code simply modifies DOM of the page removing Node from the old parent of portlet and adding it to new parent (of the dragged over object). This leaves whole layout managing to the browser. After that ajax call is invoked sending back to server WindowID (is this enough ?), old regionid, new regionid and position number.
+
+3. Testing
+
+	I've chose JSUnit instead of Selenium as this is port of JUnit to JavaScript - something that everyone is familiar with - writing asserts and that basically is it.
+
+	What should have been done is using it to test AJAX callbacks. First of all in test I don't do asynchronous calls - in JavaScript there's no way to put a current function to "sleep" so inside a test you can't wait till the "handle" function will be executed after server responce. So calls are synchronous - but it those work we can assume asynchronous work as well (server will give the same answer and that's what are we worried mainly with ajax calls).
+
+	The other thing with ajax is that the ajax handling is execute is some different "thread" so you're not able to catch those exceptions (yes - JavaScript does exceptions :-) ). I've made whole set of asserts (plus failAjax) with -Ajax suffix - they don't throw exception right away, but set flag that the exception has to be thrown and it is after the ajax call is done - see handleAjaxError(). That way you're able to test ajax effectively. For whole ajax extra test abilities see ajaxAsserts.js in /test .
+
+	The file with tests is testPortletDrop.html. To execute it - start the server, go to /dndRenderer/test/testRunner.html and point the "file" to /dndRenderer/test/testPortletDrop.html
+
+	If you look in setUp() and tearDown() functions - they enter and leave test mode. It sets ajax calls not to be executed in code (this will be changed later) and sets ajaxServlet not to do real persisting - just to pretend it's working - for testing purposes.
+	
+	Example tests:
+		* testDragAndDrop() - simple test with DOM handling
+		* testAjaxWrongParamsTestMode() - sends wrong ajax call and waits for error
+		* testPersistData() - sends 2 ajax calls - one good and one bad
+
+4. Known issues
+	* IE and Konqueror throw errors
+	* There is problem with border around hoovered portlet in Safari
+