Peter Siebel - Practical Common Lisp

(defun list-item-for-page (what row)

(if (eql what :song)

(with-column-values (song file album artist genre) row

(html

(:li

(:a :href (link "playlist" :file file :action "add-songs") (:b song)) " from "

(:a :href (link "browse" :what :song :album album) album) " by "

(:a :href (link "browse" :what :song :artist artist) artist) " in genre "

(:a :href (link "browse" :what :song :genre genre) genre))))

(let ((value (column-value row what)))

(html

(:li value " - "

(browse-link :genre what value)

(browse-link :artist what value)

(browse-link :album what value)

(browse-link :song what value))))))

(defun browse-link (new-what what value)

(unless (eql new-what what)

(html

"["

(:a :href (link "browse" :what new-what what value) (:format "~(~as~)" new-what))

"] ")))

The other thing on the browsepage is a form with several hidden INPUTfields and an "Add all" submit button. You need to use an HTML form instead of a regular link to keep the application stateless—to make sure all the information needed to respond to a request comes in the request itself. Because the browse page results can be partially random, you need to submit a fair bit of data for the server to be able to reconstitute the list of songs to add to the playlist. If you didn't allow the browse page to return randomly generated results, you wouldn't need much data—you could just submit a request to add songs with whatever search criteria the browse page used. But if you added songs that way, with criteria that included a randomargument, then you'd end up adding a different set of random songs than the user was looking at on the page when they hit the "Add all" button.

The solution you'll use is to send back a form that has enough information stashed away in a hidden INPUTelement to allow the server to reconstitute the list of songs matching the browse page criteria. That information is the list of values returned by values-for-pageand the value of the whatparameter. This is where you use the base64-listparameter type; the function values->base64extracts the values of a specified column from the table returned by values-for-pageinto a list and then makes a base 64-encoded string out of that list to embed in the form.

(defun values->base-64 (column values-table)

(flet ((value (r) (column-value r column)))

(obj->base64 (map-rows #'value values-table))))

When that parameter comes back as the value of the valuesquery parameter to a URL function that declares valuesto be of type base-64-list, it'll be automatically converted back to a list. As you'll see in a moment, that list can then be used to construct a query that'll return the correct list of songs. [310] This solution has its drawbacks—if a browse page returns a lot of results, a fair bit of data is going back and forth under the covers. Also, the database queries aren't necessarily the most efficient. But it does keep the application stateless. An alternative approach is to squirrel away, on the server side, information about the results returned by browse and then, when a request to add songs come in, find the appropriate bit of information in order to re-create the correct set of songs. For instance, you could just save the values list instead of sending it back in the form. Or you could copy the RANDOM-STATE object before you generate the browse results so you can later re-create the same "random" results. But this approach causes its own problems. For instance, you'd then need to worry about when you can get rid of the squirreled-away information; you never know when the user might hit the Back button on their browser to return to an old browse page and then hit the "Add all" button. Welcome to the wonderful world of Web programming. When you're browsing by :song, you use the values from the :filecolumn since they uniquely identify the actual songs while the song names may not.

This brings me to the next URL function, playlist. This is the most complex page of the three—it's responsible for displaying the current contents of the user's playlist as well as for providing the interface to manipulate the playlist. But with most of the tedious bookkeeping handled by define-url-function, it's not too hard to see how playlistworks. Here's the beginning of the definition, with just the parameter list:

(define-url-function playlist

(request

(playlist-id string (playlist-id request) :package)

(action keyword) ; Playlist manipulation action

(what keyword :file) ; for :add-songs action

(values base-64-list) ; "

file ; for :add-songs and :delete-songs actions

genre ; for :delete-songs action

artist ; "

album ; "

(order-by keyword) ; for :sort action

(shuffle keyword) ; for :shuffle action

(repeat keyword)) ; for :set-repeat action

In addition to the obligatory requestparameter, playlisttakes a number of query parameters. The most important in some ways is playlist-id, which identifies which playlistobject the page should display and manipulate. For this parameter, you can take advantage of define-url-function's "sticky parameter" feature. Normally, the playlist-idwon't be supplied explicitly, defaulting to the value returned by the playlist-idfunction, namely, the IP address of the client machine on which the browser is running. However, users can also manipulate their playlists from different machines than the ones running their MP3 clients by allowing this value to be explicitly specified. And if it's specified once, define-url-functionwill arrange for it to "stick" by setting a cookie in the browser. Later you'll define a URL function that generates a list of all existing playlists, which users can use to pick a playlist other than the one for the machines they're browsing from.

The actionparameter specifies some action to take on the user's playlist object. The value of this parameter, which will be converted to a keyword symbol for you, can be :add-songs, :delete-songs, :clear, :sort, :shuffle, or :set-repeat. The :add-songsaction is used by the "Add all" button in the browse page and also by the links used to add individual songs. The other actions are used by the links on the playlist page itself.

The file, what, and valuesparameters are used with the :add-songsaction. By declaring valuesto be of type base-64-list, the define-url-functioninfrastructure will take care of decoding the value submitted by the "Add all" form. The other parameters are used with other actions as noted in the comments.

Now let's look at the body of playlist. The first thing you need to do is use the playlist-idto look up the queue object and then acquire the playlist's lock with the following two lines: