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

>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
_______________________________________________
seaside mailing list
[hidden email]
http://lists.squeakfoundation.org/cgi-bin/mailman/listinfo/seaside