[Seaside] JQuery Widget box (was: Scriptaculous in-place editor)

Mon Nov 2 18:44:22 UTC 2009

>Do I wait to see how you structured the whole, before committing any  
>changes?

Hi John,

the repository now has some wrappers extracted. So you can 
take them as examples.

Here is also a short guide on the loading/coding rules:

-------------------------------------------------------------------------
JQuery Widgetbox seperates production code ("CORE") from developer code "DEV".
To use a widget you only need the core packages, if you want to extend a widget wrapper
you should also load the developer packages.

Point your monticello browser to: 

  http://www.squeaksource.com/JQueryWidgetBox

1. Load JQWidgetBox-Core
========================
   This is a core package currently only providing the "JQWidgetBoxLibrary". This class is
   a subclass of WAFileLibrary and is extended by wrapper packages with the appropriate
   resources like the javascript code, stylesheets, images and other resources (see below).

2. Load the widget you need
===========================
   You can load one of the provided packages "JQWidgetBox-XXX-Core" widget packages,
   where XXX is the name of the widget.	

3. Optional - Load "JQWidgetBox-Dev" for test and example support
=================================================================
   This package provides basic support for tests and examples common to all widget
   dev packages.

4. Optional - Load the widgets example and test code
====================================================
   After loading the support package (3) you will be able to load all the 
   "JQWidgetBox-XXX-Dev" packages.  If you load one of these manually you should evaluate

     JQWidgetExample initialize

   in a workspace to register all loaded examples dynamically before pointing your 
   browser to  http://localhost:8080/browse/jquery-widgets

Check out each widget and implementation in Smalltalk to find out how it is done.

5. Short Guide on how to create an own wrapper
==============================================
   Lets assume you have found a jquery widget on the internet called "MyWidget" and 
   it is implemented in a script "jq-mywidget-min.js" together with a "jq-mywidget.js".

   The first one is the minimal version which is typically used in production since it 
   is reduced in size while the second JavaScript - the standard script includes comments and 
   preserves formatting. This one is typically only used for debugging and development 
   purposes on the client side. 

   Since we just want to wrap a working jquery plugin in Smalltalk we will first concentrate
   on the stripped down version "jq-mywidget-min.js":

The steps:

THE CORE PACKAGE 
----------------
a) Add a new package (class category) called "JQWidgetBox-MyWidget-Core" to your Smalltalk
   system

b) within this package/category create a new subclass of the class "JQWidget"
   which is provided with Seaside:

	JQWidget subclass: #JQMyWidget
		 instanceVariableNames: ''
	 	 classVariableNames: ''
 		 poolDictionaries: ''
		 category: 'JQWidgetBox-MyWidget-Core'

   Add a class comment to this new class including the URL where you've found
   the widget. This helps other to find it easily later or extend the wrapper if there is
   a new version.

c) Point your browser to "http://localhost:8080/config", click on 
   "files" and select "JQWidgetBoxDeploymentLibrary". Now click on configure.

   Here you can add files to the prefefined library class via upload.
   Now upload the script "jq-mywidget-min.js" to the class.

   By default Seaside will now create a method #jqmywidgetminJs on
   the class JQWidgetBoxDeploymentLibrary in the "uploaded" method category.   

   To have it packaged with our widget package we have to recategorize
   this method into "*jqwidgetbox-mywidget-core"

d) Now implement an extension method on the instance side of the class 
   "JQueryInstance" returning your widget wrapper class.

	mywidget
	   "A jquery widget ..."

	   ^self create: JQMyWidget

   Since "JQueryInstance" is an existing class and we want to provide
   this method as an extension we have to put it into a method category    
   "*jqwidgetbox-mywidget-core"

e) Now implement the method #method on the instance side of JQMyWidget returning the 
   jquery javascript selector that is used by the plugin:

	method
	  ^'mywidget'

   The preferred protocol for this method is "accessing".

f) You can now implement specific methods to wrap the widgets options and events.
   Have a look at the other examples to get started. 

g) Open the Monticello browser and add a package "JQWidgetBox-MyWidget-Core".

NOTE:
Before releasing the new package "JQWidgetBox-MyWidget-Core" make sure it includes
anything that is required: the implementation class (here JQMyWidget) and the
two extensions methods on JQueryInstance and JQWidgetBoxDeploymentLibrary.

You can verify this by clicking on "Browse" in the Monticello Browser when the new
package is selected.

THE DEV PACKAGE 
----------------
Why an own package? The answer is simple: to seperate the production
code from the tests and examples.
To provide tests and examples we now have to load the package 
"JQWidgetBox-Dev" (see step 3 above) with special support code.

h) Provide a test

   Lets create a package/class category "JQWidgetBox-MyWidget-Dev". 

   Within that create a subcategory "JQWidgetBox-MyWidget-Dev-Tests"
   with an own subclass of "JQWidgetBoxWidgetTest". Here we implement the
   SUnit test for the widget:

    JQWidgetBoxWidgetTest subclass: #JQMyWidgetTest
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'JQWidgetBox-MyWidget-Dev-Tests'	

   Have a look how other packages implement to test to get started.
   Note that these kind of tests are for the smalltalk wrapper only, 
   and is not a replacement for a functional test within the webbrowser.	

i) Provide an example   

   To provide an example for the widget We also create a subcategory 
   "JQWidgetBox-MyWidget-Dev-Example" with an own subclass of "JQWidgetExample":

    JQWidgetExample subclass: #JQMyWidgetExample
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'JQWidgetBox-MyWidget-Dev-Example'

   We then implement #description and #shortName on the class side.
   The last one is used to register the example in the widget box example
   gallery. Just evaluate 

	"JQWidgetExample initialize"

   to reregister and point your browser to http://localhost:8080/browse/jquery-widgets

   To include the script into your example just implement:	

	updateRoot: anHtmlRoot
		super updateRoot: anHtmlRoot.
		anHtmlRoot javascript url: self library / #jqmywidgetminJs

   Now you are ready to implement the usual #renderContentOn: method to
   implement the example.

j) Note that it is also good style to also upload the "jq-mywidget.js" (the one
   that is not stripped/packed) and package it with the tests and examples.

   This allows for easy client side javascript debugging later if the jquery 
   widget does not work in a specifc browser/environment.

   You can put it as extension method on the class "JQWidgetBoxDevelopmentLibrary"
   (which is similar to JQWidgetBoxDeploymentLibrary, but intended for development)
   by using the "*jqwidgetbox-mywidget-dev" category.

j) Make sure your tests are green and the example is working and all methods are
   correctly packaged. Now you are ready to upload your new packages

    "JQWidgetBox-MyWidget-Core" (the production code)
    "JQWidgetBox-MyWidget-Dev" (the example and tests)

   to http://www.squeaksource.com/JQueryWidgetBox
-- 
GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01