14.3: Seaside Components

As we mentioned in the previous section, Seaside applications are built out of components. Let’s take a closer look at how Seaside works by implementing the Hello World component.

Figure \(\PageIndex{1}\): Hello World in Seaside.

Every Seaside component should inherit directly or indirectly from WAComponent, as shown in Figure \(\PageIndex{2}\). (Incidentally, the ’WA’ prefix often used in Seaside code stands for ’Web Application’.)

Figure \(\PageIndex{2}\): The WACounter class, which implements the counter application. Methods with underlined names are on the class-side; those with plain-text names are on the instance side.

Define a subclass of WAComponent called WAHelloWorld.

Components must know how to render themselves. Usually this is done by implementing the method renderContentOn:, which gets as its argument an instance of WAHtmlCanvas, which knows how to render HTML.

Implement the following method, and put it in a protocol called rendering:

WAHelloWorld >> renderContentOn: html
    html text: 'hello world'

Now we must inform Seaside that this component is willing to be a standalone application.

Implement the following method on the class side of WAHelloWorld.

WAHelloWorld class >> canBeRoot
    ^ true

We are almost done!
Point your web browser at http://localhost:8080/config, add a new entry point called hello, and set its root component to be WAHelloWorld.

Now navigate to http://localhost:8080/hello. That’s it! You should see a web page similar to Figure \(\PageIndex{1}\).

State backtracking and the Counter application

The counter application is only slightly more complex than the hello world application.

The class WACounter is a standalone application, so WACounter class must answer true to the canBeRoot message. It must also register itself as an application; this is done in its class-side initialize method, as shown in Figure \(\PageIndex{2}\).

WACounter defines two methods, increase and decrease, which will be triggered from the ++ and –– links on the web page. It also defines an instance variable count to record the state of the counter. However, we also want Seaside to synchronize the counter with the browser page: when the user clicks on the browser’s Back button, we want seaside to backtrack the state of the WACounter object. Seaside includes a general mechanism for backtracking, but each application has to tell Seaside which parts of its state to track.

A component enables backtracking by implementing the states method on the instance side: states should answer an array containing all the objects to be tracked. In this case, the WACounter object adds itself to Seaside’s table of backtrackable objects by returning Array with: self.

Backtracking caveat There is a subtle but important point to watch for when declaring objects for backtracking. Seaside tracks state by making a copy of all the objects declared in the states array. It does this using a WASnapshot object; WASnapshot is a subclass of IdentityDictionary that records the objects to be tracked as keys and shallow copies of their state as values. If the state of an application is backtracked to a particular snapshot, the state of each object entered into the snapshot dictionary is overwritten by the copy saved in the snapshot.

Here is the point to watch out for: In the case of WACounter, you might think that the state to be tracked is a number — the value of the count instance variable. However, having the states method answer Array with: count won’t work. This is because the object named by count is an integer, and integers are immutable. The increase and decrease methods don’t change the state of the object 0 into 1 or the object 3 into 2. Instead, they make count hold a different integer: every time the count is incremented or decremented, the object named by count is replaced by another. This is why WACounter>>states must return Array with: self. When the state of a WACounter object is replaced by a previous state, the value of each of the instance variable in the object is replaced by a previous value; this correctly replaces the current value of count by a prior value.