1 ;;;# ParenScript Tutorial
3 ;;; This chapter is a short introductory tutorial to ParenScript. It
4 ;;; hopefully will give you an idea how ParenScript can be used in a
5 ;;; Lisp web application.
7 ;;;# Setting up the ParenScript environment
9 ;;; In this tutorial, we will use the Portable Allegroserve webserver
10 ;;; to serve the tutorial web application. We use the ASDF system to
11 ;;; load both Allegroserve and ParenScript. I assume you have
12 ;;; installed and downloaded Allegroserve and Parenscript, and know
13 ;;; how to setup the central registry for ASDF.
15 (asdf:oos
'asdf
:load-op
:aserve
)
17 ; ... lots of compiler output ...
19 (asdf:oos
'asdf
:load-op
:parenscript
)
21 ; ... lots of compiler output ...
23 ;;; The tutorial will be placed in its own package, which we first
26 (defpackage :js-tutorial
27 (:use
:common-lisp
:net.aserve
:net.html.generator
:parenscript
))
29 (in-package :js-tutorial
)
31 ;;; The next command starts the webserver on the port 8080.
35 ;;; We are now ready to generate the first JavaScript-enabled webpages
36 ;;; using ParenScript.
38 ;;;# A simple embedded example
40 ;;; The first document we will generate is a simple HTML document,
41 ;;; which features a single hyperlink. When clicking the hyperlink, a
42 ;;; JavaScript handler opens a popup alert window with the string
43 ;;; "Hello world". To facilitate the development, we will factor out
44 ;;; the HTML generation to a separate function, and setup a handler
45 ;;; for the url "/tutorial1", which will generate HTTP headers and
46 ;;; call the function `TUTORIAL1'. At first, our function does nothing.
48 (defun tutorial1 (req ent
)
49 (declare (ignore req ent
))
52 (publish :path
"/tutorial1"
53 :content-type
"text/html; charset=ISO-8859-1"
54 :function
(lambda (req ent
)
55 (with-http-response (req ent
)
56 (with-http-body (req ent
)
57 (tutorial1 req ent
)))))
59 ;;; Browsing "http://localhost:8080/tutorial1" should return an empty
60 ;;; HTML page. It's now time to fill this rather page with
61 ;;; content. ParenScript features a macro that generates a string that
62 ;;; can be used as an attribute value of HTML nodes.
64 (defun tutorial1 (req ent
)
65 (declare (ignore req ent
))
68 (:head
(:title
"ParenScript tutorial: 1st example"))
69 (:body
(:h1
"ParenScript tutorial: 1st example")
70 (:p
"Please click the link below." :br
71 ((:a
:href
"#" :onclick
(ps-inline
72 (alert "Hello World")))
75 ;;; Browsing "http://localhost:8080/tutorial1" should return the
78 <html
><head
><title
>ParenScript tutorial
: 1st example
</title
>
80 <body
><h1
>ParenScript tutorial
: 1st example
</h1
>
81 <p
>Please click the link below.
<br
/>
83 onclick
="javascript:alert("Hello World");">Hello World
</a
>
88 ;;;# Adding an inline ParenScript
90 ;;; Suppose we now want to have a general greeting function. One way
91 ;;; to do this is to add the javascript in a `SCRIPT' element at the
92 ;;; top of the HTML page. This is done using the `JS-SCRIPT' macro
93 ;;; (defined below) which will generate the necessary XML and comment
94 ;;; tricks to cleanly embed JavaScript. We will redefine our
95 ;;; `TUTORIAL1' function and add a few links:
97 (defmacro js-script
(&rest body
)
98 "Utility macro for including ParenScript into the HTML notation
99 of net.html.generator library that comes with AllegroServe."
100 `((:script
:type
"text/javascript")
101 (:princ
(format nil
"~%// <![CDATA[~%"))
103 (:princ
(format nil
"~%// ]]>~%"))))
105 (defun tutorial1 (req ent
)
106 (declare (ignore req ent
))
110 (:title
"ParenScript tutorial: 2nd example")
112 (defun greeting-callback ()
113 (alert "Hello World"))))
115 (:h1
"ParenScript tutorial: 2nd example")
116 (:p
"Please click the link below." :br
117 ((:a
:href
"#" :onclick
(ps-inline (greeting-callback)))
119 :br
"And maybe this link too." :br
120 ((:a
:href
"#" :onclick
(ps-inline (greeting-callback)))
122 :br
"And finally a third link." :br
123 ((:a
:href
"#" :onclick
(ps-inline (greeting-callback)))
126 ;;; This will generate the following HTML page, with the embedded
127 ;;; JavaScript nicely sitting on top. Take note how
128 ;;; `GREETING-CALLBACK' was converted to camelcase, and how the lispy
129 ;;; `DEFUN' was converted to a JavaScript function declaration.
131 <html
><head
><title
>ParenScript tutorial
: 2nd example
</title
>
132 <script type
="text/javascript">
134 function greetingCallback
() {
135 alert
("Hello World");
140 <body
><h1
>ParenScript tutorial
: 2nd example
</h1
>
141 <p
>Please click the link below.
<br
/>
143 onclick
="javascript:greetingCallback();">Hello World
</a
>
145 And maybe this link too.
<br
/>
147 onclick
="javascript:greetingCallback();">Knock knock
</a
>
150 And finally a third link.
<br
/>
152 onclick
="javascript:greetingCallback();">Hello there
</a
>
157 ;;;# Generating a JavaScript file
159 ;;; The best way to integrate ParenScript into a Lisp application is
160 ;;; to generate a JavaScript file from ParenScript code. This file can
161 ;;; be cached by intermediate proxies, and webbrowsers won't have to
162 ;;; reload the JavaScript code on each pageview. We will publish the
163 ;;; tutorial JavaScript under "/tutorial.js".
165 (defun tutorial1-file (req ent
)
166 (declare (ignore req ent
))
168 (ps (defun greeting-callback ()
169 (alert "Hello World"))))))
171 (publish :path
"/tutorial1.js"
172 :content-type
"text/javascript; charset=ISO-8859-1"
173 :function
(lambda (req ent
)
174 (with-http-response (req ent
)
175 (with-http-body (req ent
)
176 (tutorial1-file req ent
)))))
178 (defun tutorial1 (req ent
)
179 (declare (ignore req ent
))
183 (:title
"ParenScript tutorial: 3rd example")
184 ((:script
:language
"JavaScript" :src
"/tutorial1.js")))
186 (:h1
"ParenScript tutorial: 3rd example")
187 (:p
"Please click the link below." :br
188 ((:a
:href
"#" :onclick
(ps-inline (greeting-callback)))
190 :br
"And maybe this link too." :br
191 ((:a
:href
"#" :onclick
(ps-inline (greeting-callback)))
193 :br
"And finally a third link." :br
194 ((:a
:href
"#" :onclick
(ps-inline (greeting-callback)))
197 ;;; This will generate the following JavaScript code under
200 function greetingCallback
() {
201 alert
("Hello World");
204 ;;; and the following HTML code:
206 <html
><head
><title
>ParenScript tutorial
: 3rd example
</title
>
207 <script language
="JavaScript" src
="/tutorial1.js"></script
>
209 <body
><h1
>ParenScript tutorial
: 3rd example
</h1
>
210 <p
>Please click the link below.
<br
/>
211 <a href
="#" onclick
="javascript:greetingCallback();">Hello World
</a
>
213 And maybe this link too.
<br
/>
214 <a href
="#" onclick
="javascript:greetingCallback();">Knock knock
</a
>
217 And finally a third link.
<br
/>
218 <a href
="#" onclick
="javascript:greetingCallback();">Hello there
</a
>
223 ;;;# A ParenScript slideshow
225 ;;; While developing ParenScript, I used JavaScript programs from the
226 ;;; web and rewrote them using ParenScript. This is a nice slideshow
229 http
://www.dynamicdrive.com
/dynamicindex14
/dhtmlslide.htm
231 ;;; The slideshow will be accessible under "/slideshow", and will
232 ;;; slide through the images "photo1.png", "photo2.png" and
233 ;;; "photo3.png". The first ParenScript version will be very similar
234 ;;; to the original JavaScript code. The second version will then show
235 ;;; how to integrate data from the Lisp environment into the
236 ;;; ParenScript code, allowing us to customize the slideshow
237 ;;; application by supplying a list of image names. We first setup the
240 (publish :path
"/slideshow"
241 :content-type
"text/html"
242 :function
(lambda (req ent
)
243 (with-http-response (req ent
)
244 (with-http-body (req ent
)
245 (slideshow req ent
)))))
247 (publish :path
"/slideshow.js"
248 :content-type
"text/html"
249 :function
(lambda (req ent
)
250 (with-http-response (req ent
)
251 (with-http-body (req ent
)
252 (js-slideshow req ent
)))))
254 ;;; The images are just random files I found on my harddrive. We will
255 ;;; publish them by hand for now.
257 (publish-file :path
"/photo1.jpg"
258 :file
"/home/viper/photo1.jpg")
259 (publish-file :path
"/photo2.jpg"
260 :file
"/home/viper/photo2.jpg")
261 (publish-file :path
"/photo3.jpg"
262 :file
"/home/viper/photo3.jpg")
264 ;;; The function `SLIDESHOW' generates the HTML code for the main
265 ;;; slideshow page. It also features little bits of ParenScript. These
266 ;;; are the callbacks on the links for the slideshow application. In
267 ;;; this special case, the javascript generates the links itself by
268 ;;; using `document.write' in a "SCRIPT" element. Users that don't
269 ;;; have JavaScript enabled won't see anything at all.
271 ;;; `SLIDESHOW' also generates a static array called `PHOTOS' which
272 ;;; holds the links to the photos of the slideshow. This array is
273 ;;; handled by the ParenScript code in "slideshow.js". Note how the
274 ;;; HTML code issued by the JavaScript is generated using the `HTML'
275 ;;; construct. In fact, we have two different HTML generators in the
276 ;;; example below, one is the standard Lisp HTML generator, and the
277 ;;; other is the JavaScript HTML generator, which generates a
278 ;;; JavaScript expression.
280 (defun slideshow (req ent
)
281 (declare (ignore req ent
))
284 (:head
(:title
"ParenScript slideshow")
285 ((:script
:language
"JavaScript"
286 :src
"/slideshow.js"))
288 (defvar *linkornot
* 0)
289 (defvar photos
(array "photo1.jpg"
292 (:body
(:h1
"ParenScript slideshow")
297 (:tr
((:td
:width
"100%" :colspan
2 :height
22)
301 ((:img
:src
(aref photos
0)
304 (lisp (ps (reveal-trans
306 (setf transition
23)))))
309 (if (= *linkornot
* 1)
310 (ps-html ((:a
:href
"#"
311 :onclick
(lisp (ps-inline (transport))))
314 (:tr
((:td
:width
"50%" :height
"21")
317 :onclick
(ps-inline (backward)
320 ((:td
:width
"50%" :height
"21")
323 :onclick
(ps-inline (forward)
325 "Next Slide"))))))))))
327 ;;; `SLIDESHOW' generates the following HTML code (long lines have
328 ;;; been broken down):
330 <html
><head
><title
>ParenScript slideshow
</title
>
331 <script language
="JavaScript" src
="/slideshow.js"></script
>
332 <script type
="text/javascript">
335 var photos
= [ "photo1.jpg", "photo2.jpg", "photo3.jpg" ];
339 <body
><h1
>ParenScript slideshow
</h1
>
341 <table border
="0" cellspacing
="0" cellpadding
="0">
342 <tr
><td width
="100%" colspan
="2" height
="22">
343 <center
><script type
="text/javascript">
346 "<img src=\"" + photos
[0]
347 + "\" name=\"photoslider\"
348 style=\"filter:revealTrans(duration=2,transition=23)\"
349 border=\"0\"></img>";
350 document.write(LINKORNOT == 1 ?
352 onclick=\"javascript:transport()\">"
360 <tr><td width="50%" height="21"><p align="left">
362 onclick="javascript:backward(); return false;">Previous Slide</a>
366 <td width="50%" height="21"><p align="right">
368 onclick="javascript:forward(); return false;">Next Slide</a>
377 ;;; The actual slideshow application is generated by the function
378 ;;; `JS-SLIDESHOW', which generates a ParenScript file. Symbols are
379 ;;; converted to JavaScript variables, but the dot "." is left as
380 ;;; is. This enables convenient access to object slots without using
381 ;;; the `SLOT-VALUE' function all the time. However, when the object
382 ;;; we are referring to is not a variable, but for example an element
383 ;;; of an array, we have to revert to `SLOT-VALUE'.
385 (defun js-slideshow (req ent)
386 (declare (ignore req ent))
390 (defvar *preloaded-images* (make-array))
391 (defun preload-images (photos)
392 (dotimes (i photos.length)
393 (setf (aref *preloaded-images* i) (new *Image)
394 (slot-value (aref *preloaded-images* i) 'src)
397 (defun apply-effect ()
398 (when (and document.all photoslider.filters)
399 (let ((trans photoslider.filters.reveal-trans))
400 (setf (slot-value trans '*Transition)
401 (floor (* (random) 23)))
405 (defun play-effect ()
406 (when (and document.all photoslider.filters)
407 (photoslider.filters.reveal-trans.play)))
413 (+ "Image " (1+ *which*) " of " photos.length)))
419 (setf document.images.photoslider.src
420 (aref photos *which*))
425 (when (< *which* (1- photos.length))
428 (setf document.images.photoslider.src
429 (aref photos *which*))
434 (setf window.location (aref photoslink *which*)))))))
436 ;;; `JS-SLIDESHOW' generates the following JavaScript code:
438 var PRELOADEDIMAGES = new Array();
439 function preloadImages(photos) {
440 for (var i = 0; i != photos.length; i = i++) {
441 PRELOADEDIMAGES[i] = new Image;
442 PRELOADEDIMAGES[i].src = photos[i];
445 function applyEffect() {
446 if (document.all && photoslider.filters) {
447 var trans = photoslider.filters.revealTrans;
448 trans.Transition = Math.floor(Math.random() * 23);
453 function playEffect() {
454 if (document.all && photoslider.filters) {
455 photoslider.filters.revealTrans.play();
459 function keepTrack() {
460 window.status = "Image " + (WHICH + 1) + " of " +
463 function backward() {
467 document.images.photoslider.src = photos[WHICH];
473 if (WHICH < photos.length - 1) {
476 document.images.photoslider.src = photos[WHICH];
481 function transport() {
482 window.location = photoslink[WHICH];
485 ;;;# Customizing the slideshow
487 ;;; For now, the slideshow has the path to all the slideshow images
488 ;;; hardcoded in the HTML code, as well as in the publish
489 ;;; statements. We now want to customize this by publishing a
490 ;;; slideshow under a certain path, and giving it a list of image urls
491 ;;; and pathnames where those images can be found. For this, we will
492 ;;; create a function `PUBLISH-SLIDESHOW' which takes a prefix as
493 ;;; argument, as well as a list of image pathnames to be published.
495 (defun publish-slideshow (prefix images)
496 (let* ((js-url (format nil "~Aslideshow.js" prefix))
497 (html-url (format nil "~Aslideshow" prefix))
499 (mapcar (lambda (image)
500 (format nil "~A~A.~A" prefix
501 (pathname-name image)
502 (pathname-type image)))
504 (publish :path html-url
505 :content-type "text/html"
506 :function (lambda (req ent)
507 (with-http-response (req ent)
508 (with-http-body (req ent)
509 (slideshow2 req ent image-urls)))))
510 (publish :path js-url
511 :content-type "text/html"
512 :function (lambda (req ent)
513 (with-http-response (req ent)
514 (with-http-body (req ent)
515 (js-slideshow req ent)))))
516 (map nil (lambda (image url)
517 (publish-file :path url
521 (defun slideshow2 (req ent image-urls)
522 (declare (ignore req ent))
525 (:head (:title "ParenScript slideshow")
526 ((:script :language "JavaScript"
527 :src "/slideshow.js"))
528 ((:script :type "text/javascript")
529 (:princ (format nil "~%// <![CDATA[~%"))
530 (:princ (ps (defvar *linkornot* 0)))
531 (:princ (ps* `(defvar photos (array ,@image-urls))))
532 (:princ (format nil "~%// ]]>~%"))))
533 (:body (:h1 "ParenScript slideshow")
538 (:tr ((:td :width "100%" :colspan 2 :height 22)
542 ((:img :src (aref photos 0)
545 (lisp (ps (reveal-trans
547 (setf transition 23)))))
550 (if (= *linkornot* 1)
551 (ps-html ((:a :href "#"
552 :onclick (lisp (ps-inline (transport))))
555 (:tr ((:td :width "50%" :height "21")
558 :onclick (ps-inline (backward)
561 ((:td :width "50%" :height "21")
564 :onclick (ps-inline (forward)
566 "Next Slide"))))))))))
568 ;;; We can now publish the same slideshow as before, under the
571 (publish-slideshow "/bknr/"
572 `("/home/viper/photo1.jpg" "/home/viper/photo2.jpg" "/home/viper/photo3.jpg"))
574 ;;; That's it, we can now access our customized slideshow under
576 http://localhost:8080/bknr/slideshow