In the Trenches

Dialogs in Seaside

Mon, 9 Jul 2007 16:25:53 -0700

A common task in web applications is asking users for information. At some point one needs to obtain data like a users name, address, phone number, credit card number, password, etc. Typically one does the following:
Display some overall explanatory text
Display a text field or other appropriate input widget for each datum
Display a label for each datum
Display some explanatory text, perhaps on request, for each datum
Validate each datum
Save the data in a database
The request for the data may be spread across multiple pages for a number of reasons. At this is a common task a web framework should make this easy. We will look at several ways this can be done in Seaside. The database access is not discussed here. That is a subject for a later post.
The examples are done using VisualWorks Smalltalk 7.5, Seaside 2.61.140 and Magritte lr.193. This version of Seaside still used both original renderer, WAHtmlRenderer and the newer WARenderCanvas. As the later will be the only render in Seaside 2.8, it is used here.
For our examples we will restrict the requested information to:
Name
Phone number
We will start with the following "model" class for this information.
Smalltalk.Seaside defineClass: #Contact
superclass: #{Core.Object}
instanceVariableNames: 'name phoneNumber '

name
^name

name: anObject
name := anObject

phoneNumber
^phoneNumber

phoneNumber: anObject
phoneNumber := anObject

hasValidName
^name notNil

hasValidPhoneNumber
phoneNumber ifNil:[^false].
^phoneNumber size > 6

By Hand
We will start by creating a single component to perform the task. As you can see below the code is not too bad. The good news is that we have complete control over all aspects of the application - how to display the request, validation, how to display the errors, etc. The bad news is that there is a lot of logic that is repeated each time we do this. Note in particular the logic needed to detect and handle errors.
The class methods handle different aspects of registering the component as a web application, hence are not directly related to the issues at hand.

Smalltalk.Seaside defineClass: #FormExample
superclass: #{Seaside.WAComponent}
instanceVariableNames: 'contact errors '

Class Methods
canBeRoot
"Allow the component to be standalone application"
^ true

initialize
"Register application url"
(self registerAsApplication: 'whitneyExamples/form')

description
"Application description"
^'Doing it the hard way'

Instance Methods
renderContentOn: html
html heading: 'Enter your information'.
self hasErrors
ifTrue:
[html text: ['Please correct the following errors'].
html unorderedList addAll: errors].
html form:
[html text: 'Name'.
(html textInput)
on: #name of: contact;
exampleText: 'John Doe'.
html break.
html text: 'Phone'.
html textInput on: #phoneNumber of: contact.
html break.
html submitButton callback: [self ok]]

rendererClass
"Use new rendering engine"
^WARenderCanvas

hasErrors
^errors size > 0

ok
"Action on submitting data"
self validate.
self hasErrors ifTrue:[^self].
self answer: contact

updateRoot: anHtmlRoot
super updateRoot: anHtmlRoot.
anHtmlRoot title: 'Form Decorator Example'.

validate
errors := OrderedCollection new.
contact hasValidName ifFalse:
[errors add: 'You must enter a valid name'].
contact hasValidPhoneNumber ifFalse:
[errors add: 'Enter a valid phone number'].

initialize
contact := Contact new.

Using Decorators
Seaside supports the decorator pattern on components. We will use the following standard decorators: WAMessageDecoration, WAValidationDecoration and WAFormDecoration. The complete code for the example is below.
First we will look at setting up the decorator chain. The order of the decorators in given in the following diagram.

In the FormDecoratorExample>>initialize method the decorator chain is created with the code:
form := WAFormDecoration new buttons: self buttons.
self addDecoration: form.
self validateWith: [:aContactOrSelf | aContactOrSelf validate].
self addMessage: 'Please enter the following information'.

The addDecoration: method in WAComponent add decorators to the front of the decorator chain of a component. The methods validateWith: and addMessage: are helper methods that create the decorators for us.
A WAMessageDecoration object just displays the message (string actually) that it is given. The WAMessageDecoration is place first on the chain so that any error messages occur after the message. If you want the error messages to appear above the message then place the WAMessageDecoration object after the WAValidationDecoration object.
When creating a WAValidationDecoration object you give it a block, which it runs to validate your component. This validation is done when your component "exits" using answer or answer:. When the exit is done via answer: the argument of answer: is passed as the argument to the validation block. When the exit is done via answer the sender of the method answer is the argument of the validation block. If the validation code detects a problem it raises the WAValidationNotification error to indicate a problem. Typically this is done by calling the Object>>validationError: method. The argument of the method is the error message that is to be displayed to the user. Below is the validation code in the Contact class.
Contact>>validate
self hasValidName
ifFalse:
[self validationError: 'You must provide a valid name'].
self hasValidPhoneNumber
ifFalse:
[self validationError: 'You must provide a valid phone
number'].

Since one can only pass a string as an argument of Object>>validationError: it is hard to provide multiple error messages that can be displayed reasonable. The validation code above only indicated one error at a time, which is a poor way to treat a user. Below is a screen shot after the user click on the Ok button without entering either a name or a phone number. The layout is the default produced by the decorators. Use CSS to provide a better view. The message is marked with <h3> tag. The error message is in a <div class="validation-error"> tag. Seaside makes it easy to view the source of a page, so you can determine what tags you need CSS for to improve the layout & look of the page.

The WAFormDecoration object requires a list of buttons (as a collection of strings or symbols) for the form. The text displayed in each button is generated from the text in the list of the buttons. The first letter of the string is capitalized. A space is added before any capital letters inside the string. So "cancel" is displayed as "Cancel" and "goHome" is displayed as "Go Home". The buttons above were generated from #(ok cancel). The unmodified text for the button also is the callback message sent to the component. So in our example the FormDecoratorExample class needs to implement the methods ok and cancel. FormDecoratorExample also needs to implement the method defaultButton which is to return the string for the button the form is to treat as default button. The form decorator sends this message to the next item in the decorator chain. This message is not part of the standard decorrator protocol and is not passes on the chain in the version of Seaside used for these examples. As a result no decorators can be between the form decorator and your component.
Smalltalk.Seaside defineClass: #FormDecoratorExample
superclass: #{Seaside.WAComponent}
instanceVariableNames: 'contact '

Class Methods
initialize
(self registerAsApplication: 'whitneyExamples/formDecorator')

description
^'Using a form decorator'

canBeRoot
^ true

Instance Methods
initialize
| form |
super initialize.
contact := Contact new.
"Add decorators"
form := WAFormDecoration new buttons: self buttons.
self addDecoration: form.
self validateWith:
[:aContactOrSelf | aContactOrSelf validate].
self addMessage: 'Please enter the following information'.

renderContentOn: html
"Display labels and input fields"
html text: 'Name'.
(html textInput)
on: #name of: contact;
exampleText: 'John Doe'.
html break.
html text: 'Phone'.
html textInput on: #phoneNumber of: contact

rendererClass
^WARenderCanvas

buttons
^#(ok cancel)

cancel
"User clicked on the Cancel button"
self answer

defaultButton
^self buttons first

ok
"user clicked on the Ok button"
self answer: contact

validate
"Only called when cancel (self answer) is call, so nothing to
validate"
^true

updateRoot: anHtmlRoot
super updateRoot: anHtmlRoot.
anHtmlRoot title: 'Form Decorator Example'.

Labeled Dialog
The decorator solution is better than the first solution in that some of the logic common to dialogs can be reused and some of the low level details are done for us. The decorator solution still requires one to layout the input widgets and their labels, which can be automated. In Seaside the WALabelledFormDialog component does just that.
WALabelledFormDialog is an abstract class. To use it one must create a subclass. Your subclass needs to implement the methods labelForSelector:, model and rows. If you want to change the default set of buttons used on the form you need to override the buttons method in your class. For each submit button on the form you need to implement a callback method.
WALabelledFormDialog uses the same decorator structure as we used in the decorator example FormDecoratorExample.

Since WALabelledFormDialog already adds a WAFormDecoration we do not need to add it to the decorator chain. Here is the initialize method for the LabelledFormDialogExample (full source code for the example is below).
LabelledFormDialogExample>>initialize
super initialize.
contact := Contact new.
self validateWith: [:aContact | aContact validate].
self addMessage: 'Please enter the following information'.

As mentioned above we need to implement the methods labelForSelector:, model and rows in our subclass of WALabelledFormDialog. The model method just returns the object whose fields we wish to populate with date. The rows method returns a collections of symbols. One symbol for each row of data in the dialog. The symbol is used generate the accessor methods for the data in the model. The method labelForSelector: returns the labels for each row and each submit button in the form. See the source code for the example below.
The contact example generates the following page:

The default input widget is the html input tag. To override the default implement the method renderXOn:, where x is the symbol for the row, in your subclass of WALabelledFormDialog. To use a different input widget for "name" in our example we would use:
LabelledFormDialogExample>>renderNameOn: html
html
selectFromList: #( 'Roger' 'Pete')
selected: 'Roger'
callback: [:v | contact name: v]

The resulting page is below. Since I am using Seaside 2.6 the renderer passed to this method is WAHtmlRenderer. In Seaside 2.8 that renderer is completely replaced by WARenderCanvas. Since in Seaside 2.6 WALabelledFormDialog uses WAHtmlRenderer you cannot use WARenderCanvas in your subclass.

Here is the complete Contact example using WALabelledFormDialog.
Smalltalk.Seaside defineClass: #LabelledFormDialogExample
superclass: #{Seaside.WALabelledFormDialog}
instanceVariableNames: 'contact '
Class Methods

canBeRoot
^ true

initialize
(self registerAsApplication: 'whitneyExamples/formDialog')

description
^'Using a form Dialog'

Instance Methods
initialize
super initialize.
contact := Contact new.
self validateWith: [:aContact | aContact validate].
self addMessage: 'Please enter the following information'.

model
^ contact

rows
^ #(name phoneNumber)

ok
self answer: contact

labelForSelector: aSymbol
aSymbol == #name ifTrue: [^'Your Name'].
aSymbol == #phoneNumber ifTrue: [^'Phone Number'].
aSymbol == #ok ifTrue: [^'Ok'].
^ super labelForSelector: aSymbol

updateRoot: anHtmlRoot
super updateRoot: anHtmlRoot.
anHtmlRoot title: 'Form Dialog Example'.

Edit Dialog
WAEditDialog is useful in editing new or existing model objects. The main thing it adds to WALabelledFormDialog is the automatic rollback of the model if the user cancels the operation. WAEditDialog is an abstract subclass of WALabelledFormDialog. Your subclass needs to implement the methods labelForSelector: and rows. The method labelForSelector: does not have to handle the form buttons. Your model class has to implement the method copyFrom: as it is used to rollback changes when the user cancels the edit. Here is the method for our Contact class.
Contact>>copyFrom: aContact
name := aContact name.
phoneNumber := aContact phoneNumber

Since it is used to edit existing model objects WAEditDialog operates slightly differently than WALabelledFormDialog. When a WAEditDialog object returns from a call it returns a boolean not the model. Here is sample code using a WAEditDialog subclass.
contact := Contact new.
editor := EditFormExample model: contact.
wasChanged := self call: editor.

Note in the source for EditFormExample how the validate block has changed from previous examples. Don't get too fond of WAEditDialog as it was dropped in Seaside 2.8.
Smalltalk.Seaside defineClass: #EditFormExample
superclass: #{Seaside.WAEditDialog}
instanceVariableNames: ''

Instance Methods
initialize
super initialize.
self validateWith:
[:saved | saved ifTrue:[self model validate]].
self addMessage: 'Please enter the following information'.

labelForSelector: aSymbol
aSymbol == #name ifTrue: [^'Your Name'].
aSymbol == #phoneNumber ifTrue: [^'Phone Number'].
^ super labelForSelector: aSymbol

rows
^ #(name phoneNumber)

updateRoot: anHtmlRoot
super updateRoot: anHtmlRoot.
anHtmlRoot title: 'Edit Dialog Example'.

Magritte
Magritte, developed by Lukas Renggli, provides a different approach to these types of dialogs. In Magritte one provides meta-data about the model. This meta-data is used to generate the dialogs. For each instance variable of interest you create a class method called descriptionX, where X is some meaningful text. The description contains information about the type and restrictions of the described instance variable and its display location.
Given the Contact class below we generate a dialog page using:
contact := Contact new asComponent.
contact addValidatedForm.
self call: contact.

which generates the page:

If one clicks on the Save button without entering any text one gets the following page.

Magritte is an interesting system. There are a number of things that need to be covered about Magritte, but that will have to wait for another posting.
Smalltalk.Seaside defineClass: #Contact
superclass: #{Core.Object}
instanceVariableNames: 'name phoneNumber '
classInstanceVariableNames: ''
imports: '
Magritte.*
'
category: 'SeasideExamples'

Class Methods

descriptionName
^(MAStringDescription auto: 'name' label: 'Name' priority: 30)
beRequired;
yourself.

descriptionNumber
| description |
description := MAStringDescription
auto: 'phoneNumber'
label: 'Phone number'
priority: 40.
^description
beRequired;
addCondition:
[:value | value size > 6]
labelled: 'invalid phone number';
yourself

Instance Methods
name
^name

name: anObject
name := anObject

phoneNumber
^ phoneNumber

phoneNumber: anObject
phoneNumber := anObject

Special Purpose Dialogs
Seaside comes with some special purpose dialogs. Below I give a code snippet showing the use and the small screenshot of the result. Two of the dialogs (WAInputDialog and WAYesOrNoDialog) can be used via connivence methods, which I use.
WAChoiceDialog
selection := WAChoiceDialog options:
#('Smalltalk' 'Perl' 'Python' 'Ruby').
result := self call: selection.

WASelection
selection := WASelection new.
selection items: #(1 'cat' 'rat').
selectedItem := self call: selection.

WAYesOrNoDialog
aBoolean := self confirm: 'Time to sleep?'.

WAInputDialog
aString := self
request: 'Do you like Seaside?'
label: 'Ok'
default: 'Suggested answer'.

If you are using Seaside 2.6 you may notice that some dialogs are missing. For Seaside 2.8 dialog classes that were not being used were removed to clean up the Seaside core. The dialogs that were removed are:
WAChangePassword
WAEditDialog
WAEmailConfirmation
WAGridDialog
WALoginDialog
WANoteDialog

Static Abuse

Mon, 21 May 2007 21:51:38 -0700

I just finished an end-of-the semester marathon session of grading programs. I noticed a number of students that misuse static method and static fields. To help illustrate I will use a Stack class.

class Stack {
private ArrayList elements = new ArrayList();

public void push(Object element) {
elements.add(element);
}

public Object pop() {
return elements.remove(elements.size() -1);
}
}

On rare occasions I will come across a student that tests the code using main. They write:

class Stack {
private ArrayList elements = new ArrayList();

public void push(Object element) {
elements.add(element);
}

public Object pop() {
return elements.remove(elements.size() -1);
}

public static void main(String[] args) {
push("cat");
System.out.println(pop()):
}

Of course the compiler complains about and they then "fix" the problem by making everything static:

class Stack {
private static ArrayList elements = new ArrayList();

public static void push(Object element) {
elements.add(element);
}

public static Object pop() {
return elements.remove(elements.size() -1);
}

public static void main(String[] args) {
push("cat");
System.out.println(pop()):
}

Hopefully you are shaking your head at this and wondering what the student was thinking.

More commonly students make all fields and methods static because they:

Think they only need one instance of the class
Want a easy way to provide global access to that instance

The students assumptions are frequently wrong. The test cases they use only need one instance at a time of the class but there are times when the program will need multiple instance of the class. The use of the static fields introduces errors into their code, which they are not aware of. If they are lucky I will catch the error and they will lose points on their assignment. They are often wrong about the need for a global access to the one instance of the class. Sometimes here is a way to provide the needed access in the program and they are just being lazy. Other times there are design problems in their code, which they get around using static methods.

So students when you start to use static method stop and think about what you are doing. Do you really need the global access? If so investigate the singleton pattern. Are you just trying to find a home for a bunch of functions? If so look at your classes and ask yourself why you don't have a class where the functions belong as methods.

HandsOn - A visual programming language for web applications

Sat, 3 Jun 2006 16:04:41 -0700

Peter Howell, a masters student of mine, has generated some interest in his thesis project: HandsOn. Ian Prince comments about HandsOn in a blog entries here and here. Peter has his thesis online with two screencasts. You can also download his project.

This was a very nice project. If you are a graduate student wondering what type of projects my students do for a thesis take a look at Peter's HandsOn.

The Changing Web - ET Fall 2006

Tue, 23 May 2006 22:11:30 -0700

I am starting to get inquiries about the course CS 683 Emerging Technologies (ET) to be offered in the Fall 2006 semester so it is time to produce a course description.

Overview

The short description is that the course will cover Ruby, Ruby on Rails, Python, Django, CSS, Javascript, AJAX and Web Services. For details read on.

Course Background

CS 683 is a graduate topics course course covering some new technologies. As a graduate course undergraduate students can only take it if graduate students do not fill up the course. Normally I turn way graduate students in this course. In the six times the course has been offered no undergraduate student has been able to take the course.

The leading edge of technology is often called the bleeding edge. There has not been time to polish the technology. There are rough edges (bugs, poor or no documentation, incomplete implementations, rapidly changing api, missing features, poor tool support) that make it harder to deal with the technology. This means that the course is a bit more work than normal. Since this will be the first time that I cover these areas and there are no textbooks covering these things the course will also be rougher than normal. This is the trade off one makes dealing with new technology. As a result the course will require a fair amount of work and initiative of the students. The course covers a number of topics, which means we will not cover anyone topic in detail.

Some Motivation

While the World Wide Web is always changing it seems to be changing even more these days. Venture capital is flowing into web based companies. One area of change is the development of new frameworks for creating web applications. We will look at two new frameworks that have promise to reduce the time required to develop web applications: Ruby on Rails and Django. What one can do on the web is changing, for example look at Google Maps and Gmail. AJAX is being used to provide this functionality. There are a number of mashup web sites, that is sites that combine and use other sites and data. A good example is Housing Maps, which combines Google Maps and Craigslist showing the location of rentals and housing for sale. Such mashups are possible due to APIs provided by companies to access their services. Often these APIs are done with Web Services.

To learn these technologies students will develop programs that use the technologies. If you are looking for a survey course that just talks about technologies or one that talks about the social, economic and technological ramifications this course is not for you. The goal is to give computer science students some experience with these technologies.

Some Details

Ruby. Ruby is an interesting and powerful dynamic programming language. Recently interest in the language has grown greatly mainly due to Ruby on Rails, which is why the course will look at Ruby. The standard text on Ruby is Programming Ruby 2n’d Edition by Thomas & Hunt. The first edition is available on-line, but covers a much older version of Ruby. The course will spend about 2 weeks on Ruby. See last years course for the old lecture notes and assignments. There are some on-line tutorials to ruby, here is a popular one.

Ruby on Rails. This is a new framework for developing web applications and has a lot of promise and interest. The developers paid attention to the difficulties with other web application frameworks. Developers are reporting that they can develop web applications in much less time using Ruby on Rails. Last year a students took one day to redo his semester Java/Struts web project in Ruby on Rails. We will spend about three weeks on Rails. The Ruby on Rails site has a documentation page with links and information to books, tutorials and on-line api.

Python. Python is a popular dynamic programming language. See the main Python web site for more details. The course will spend about two weeks on Python. The main motivation for covering Python is Django.

Django. This is a really new framework for developing web applications that uses Python. The current version of Django is 0.91. Hopefully version 1.0 will be out by the fall. Some claim that Django is to Ruby on Rails as Ruby on Rails is to Java/Structs, that is really fast development of web applications. We shall see. The course will spend about three weeks on Django. See the Django web site for documentation, there are no books on Django yet.

AJAX. Ajax uses CSS, Javascript and Xhtml to provide some interesting client side functionality in web browsers. Some web application frameworks, like Ruby on Rails, generate the needed Javascript. So it is not clear how much time we will need to spend on Javascript. I estimate 2 weeks on CSS, Javascript and Ajax.

Web Services. Ruby and Python have SOAP implementations. It is not clear how much detail we will need to add a Web service interface to a web application. Estimate 2 weeks on this topic.

Prerequisites

The course changes each time it is taught, so there can not be a fixed list of prerequisites. This is an advanced graduate course at the Masters level. None of the topics in the course are that deep. If I were a manager in industry I would expect anyone with a CS Masters degree to be able to learn any topic in the course by themselves. Past lecture notes and assignments for the course are on-line. With all this information an advanced graduate student should know if they are capable of taking this course.

Future of Books

Thu, 18 May 2006 10:11:35 -0700

Kevin Kelly has an excellent article (registration required) in the New York Times about the efforts to scan all the world’s estimated 25 million books. The current rate is estimated at 1 millions books scanned each year. One company in China claims to have scanned 50% of all books published in China since 1949. Of course he discusses Googles scanning efforts and the issues raised by the project. He also discusses Amazon’s efforts, automated machines that scan 1,000 pages an hour, and China and India’s scanning factories. It is estimated that the USA 15% of the books are in the public domain, 10% are currently in print, with the remaining 75% are out of print but still copyrighted. For a long time a copyright protected a book for 14 years after publication. Now in the USA a copyright protects a book for 70 years after the author’s death. One result if this long copyright is that most of the books that fall out of print will vanish. The book will still be covered by copyright but it will be impossible to find anyone that owns the copyright.

Of course the interesting thing is when these millions of scanned books become available on-line. Already libraries can purchase scanned books at about 50 cents per book. The SDSU library contains about 1.2 millions books and bound periodicals. What will happen when students have 1 million books on their laptop or iPod?