tutorial! part 1 ++

Author: vindarel

content/tutorial/_index.md

@@ -3,4 +3,33 @@ title = "Tutorial part 1"
 weight = -1
 +++
 
-rst
+
+Are you ready to build a web app in Common Lisp? Welcome.
+
+In this first tutorial we will build a simple app that shows a web
+form that will search and display a list of products.
+
+![](web-app.png?lightbox=false&shadow=true)
+
+
+In doing so, we will see many necessary building blocks to write web apps in Lisp:
+
+- how to start a server
+- how to create routes
+- how to define and use path and URL parameters
+- how to define HTML templates
+- how to run and build the app, from our editor and from the terminal.
+
+In doing so, we'll experience the interactive nature of Common Lisp
+and we'll learn important commands: running `sbcl` from the command
+line with a couple options, what is `load`, how to interactively
+compile our app with a keyboard shortcut, how to structure a project
+with an .asd definition and a package, etc.
+
+We expect that you have Quicklisp installed. If not, please see the [Cookbook: getting started](https://lispcookbook.github.io/cl-cookbook/getting-started.html).
+
+Now let's go.
+
+But beware. There is no going back.
+
+*(look at the menu and don't miss the small previous-next arrows on the top right)*

content/tutorial/first-URL-parameters.md

@@ -1,5 +1,5 @@
 +++
-title = "Part 1: the first URL parameter"
+title = "the first URL parameter"
 weight = 100
 +++
 
@@ -56,7 +56,7 @@ So:
 {% if debug %} debug info! {% endif %}
 ```
 
-And add arguments to the `render` function:
+And pass the variable to the `render` function:
 
 ```lisp
 (render *template-product*
@@ -108,15 +108,13 @@ Our app looks like this:
 </body>
 ")
 
-(defun products (&optional (n 5))
-  (loop for i from 0 below n
-        collect (list i
-                      (format nil "Product nb ~a" i)
-                      9.99)))
-
 (defun get-product (n)
   (list n (format nil "Product nb ~a" n) 9.99))
 
+(defun products (&optional (n 5))
+  (loop for i from 0 below n
+        collect (get-product i)))
+
 (defun render (template &rest args)
   (apply
    #'djula:render-template*
@@ -137,11 +135,11 @@ Our app looks like this:
   (format t "~&Starting the web server on port ~a" port)
   (force-output)
   (setf *server* (make-instance 'easy-routes:easy-routes-acceptor
-                                :port (or port *port*)))
+                                :port port))
   (hunchentoot:start *server*))
 ```
 
-Everything is contained in one file (don't forget the .asd), and we
+Everything is contained in one file, and we
 can run everything from sources or we can build a self-contained
 binary. Pretty cool!
 

content/tutorial/first-bonus-CSS.md

@@ -1,6 +1,6 @@
 +++
 title = "Bonus: pimp your CSS"
-weight = 1000
+weight = 250
 +++
 
 ## Bonus: pimp your CSS
@@ -54,8 +54,15 @@ So, for instance:
 ")
 ```
 
-Note how our root template is benefiting from the CSS, and not the
-product page. The two pages should inherit from a base template. It's
-about time we setup our templates in their own directory.
-
 Refresh [http://localhost:8899/?query=one](http://localhost:8899/?query=one). Do you enjoy the difference?!
+
+I see this:
+
+![](/tutorial/web-app.png?lightbox=false&shadow=true)
+
+ 
+
+However note how our root template is benefiting from the CSS, and the
+product page isn't. The two pages should inherit from a base
+template. It's about time we setup our templates in their own
+directory.

content/tutorial/first-build.md

@@ -1,5 +1,5 @@
 +++
-title = "Part 1: the first build"
+title = "the first build"
 weight = 300
 +++
 
@@ -83,7 +83,8 @@ To load "myproject":
     myproject
 ; Loading "myproject"
 ..............
-Starting the web server on port 8899 While evaluating the form starting at line 5, column 0
+Starting the web server on port 8899
+While evaluating the form starting at line 5, column 0
   of #P"/home/vince/projets/web-apps-in-lisp/walk/walk-book/content/tutorial/run.lisp":
 
 debugger invoked on a USOCKET:ADDRESS-IN-USE-ERROR in thread
@@ -141,7 +142,7 @@ To use another port, what would you prefer?
 - we can give the port as an argument on the command line, like `--port 9000`.
 - we can find the next available port.
 
-Let's start with the latter.
+Let's do the latter.
 
 
 ## Find a port number
@@ -174,13 +175,11 @@ Our .asd file now looks like:
                :djula        ;; HTML templates
 
                ;; utils
-               :str          ;; strings library
                :find-port    ;;                 <------- added
                )
   :components ((:module "src"  ;; a src/ subdirectory
                 :components
                 (
-                 (:file "packages")  ;; = src/packages.lisp
                  (:file "myproject") ;; = src/myproject.lisp
                 )))
 
@@ -313,8 +312,9 @@ But wait, do we *really* want to develop our app from this limited
 terminal REPL? No! If you don't already, it's time you understand the
 usefulness of the `load` function.
 
-What we want is to edit our .lisp source file, instead of the REPL,
-and then to reload the app. The reloading is done with
+What we want is to edit our .lisp source file, instead of copy-pasting
+stuff in the REPL, and then to reload the app. The reloading is done
+with
 
     * (load "src/myproject.lisp")
 
@@ -356,7 +356,7 @@ compression, they get to ±20MB. As your application grows, they'll
 stay roughly this size. An app of mine, with dozens of dependencies
 and all the application code, templates and static assets (JS and CSS)
 is 35MB. LispWorks binaries, reduced in size with their tree shaker,
-are know to be smaller, a hello world being ±5MB, a web app around
+are known to be smaller, a hello world being ±5MB, a web app around
 10MB. This tree shaker isn't in the free version.
 
 Enough talk, let's do it. Create a new `build.lisp` file. We need these steps:
@@ -528,7 +528,7 @@ app. Congrats!
 
 ## Closing words
 
-We are only scratching the surface of what we can do with a real app:
+We are only scratching the surface of what we'll want to do with a real app:
 
 - parse CLI args
 - handle a `C-c` and other signals

content/tutorial/first-form.md

@@ -1,5 +1,5 @@
 +++
-title = "Part 1: the first form"
+title = "the first form"
 weight = 200
 +++
 
@@ -41,8 +41,8 @@ As a consequence, your route should have a parameter named `query`.
 {{% notice info %}}
 
 It's best to declare your parameters, but rest assured that
-Hunchentoot allows you to get the value of any URL parameter with the
-function `hunchentoot:parameter`.
+Hunchentoot allows you to get the value of any URL parameter of the
+current web request with the function `hunchentoot:parameter`.
 
 {{% /notice %}}
 
@@ -102,14 +102,12 @@ Our products are named "product nb …" and we will search for the
 We can make things a lil' bit more interesting with this small change:
 
 ```lisp
-(defun products (&optional (n 5))
-  (loop for i from 0 below n
-        collect (list i
-                      (format nil "Product nb ~r" i)
-                      9.99)))
+
+(defun get-product (n)
+  (list n (format nil "Product nb ~r" n) 9.99))
 ```
 
-Did you notice? `format … "~r"`, for the Radix directive. It prints numbers in english.
+Did you notice? `format … "~r"` instead of `"~a"`, for the Radix directive. It prints numbers in english.
 
 ```lisp
 MYPROJECT> (products)
@@ -189,7 +187,9 @@ I did this for the template:
 ")
 ```
 
-And this for the route:
+I used a `results` variable, which is a list of product objects.
+
+I did this for the route:
 
 ```lisp
 (easy-routes:defroute root ("/") (query)
@@ -272,14 +272,12 @@ Our app now look like this:
    args))
 
 ;;; Models.
+(defun get-product (n)
+  (list n (format nil "Product nb ~r" n) 9.99))
+
 (defun products (&optional (n 5))
   (loop for i from 0 below n
-        collect (list i
-                      (format nil "Product nb ~r" i)
-                      9.99)))
-
-(defun get-product (n)
-  (list n (format nil "Product nb ~a" n) 9.99))
+        collect (get-product i)))
 
 (defun search-products (products query)
   (loop for product in products

content/tutorial/first-path-parameter.md

@@ -1,5 +1,5 @@
 +++
-title = "Part 1: the first path parameter"
+title = "the first path parameter"
 weight = 20
 +++
 
@@ -137,7 +137,7 @@ Here are mine:
 
 yeah I'm just printing the product, as a list, very simply.
 
-I added a `get-product (n)` function helper.
+I added a `get-product (n)` helper function. You should edit `products` to use it too.
 
 However I don't like the copy-pasting between `render-product` and `render-products` so I'll fix it. Can you too?
 

content/tutorial/first-route.md

@@ -1,5 +1,5 @@
 +++
-title = "Part 1: the first route"
+title = "the first route"
 weight = -1
 +++
 
@@ -32,7 +32,7 @@ It's time to start our web server:
 
 ```lisp
 (defun start-server (&key (port *port*))
-  (format t "~&Starting the web server on port ~a" port)
+  (format t "~&Starting the web server on port ~a~&" port)
   (force-output)
   (setf *server* (make-instance 'easy-routes:easy-routes-acceptor
                                 :port port))
@@ -50,7 +50,7 @@ the running Lisp image.
 Now call the function `(myproject::start-server)` or simply
 `(start-server)` if you did the `(in-package :myproject`) in the REPL.
 
-Yourather instantly) should see:
+You should see:
 
 ```
 CL-USER> (myproject::start-server )
@@ -75,4 +75,11 @@ By the way, did you notice that while developping, you didn't have to stop the
 app, to stop the web server, nor to reload anything? Any changes
 compiled in the running image are immediately available.
 
+Did you wait for something? You didn't, and I promise that as the
+applications grows, with this interactive development style, you will
+never have to wait for stuff re-compiling or re-loading. You'll
+compile your code with a shortcut and have instant feedback. SBCL
+warns us on bad syntax, undefined variables and other typos, some type
+mismatches, unreachable code (meaning we might have an issue), etc.
+
 To stop the app, use `(hunchentoot:stop *server*)`. You can put this in a "stop-app" function.

content/tutorial/first-template.md

@@ -1,5 +1,5 @@
 +++
-title = "Part 1: the first template"
+title = "the first template"
 weight = -1
 +++
 
@@ -88,7 +88,7 @@ simply use `:key` arguments, like this:
 (djula:render-template*
    (djula:compile-string *template-root*)
    nil
-   :products (products))
+   :products (products))   ;; <----- added
 ```
 
 you can compile the route again and refresh the page at [localhost:8899/](localhost:8899/).
@@ -114,16 +114,16 @@ We have a very cool route:
   (djula:render-template*
    (djula:compile-string *template-root*)
    nil
-   :products (products)))  ;; <----- added
+   :products (products)))
 ```
 
 To test it and see its output, we had to re-compile it (OK), and
-refresh our browser. ARGH! We can do better. It may not look necessary
+refresh our browser. ARGH! We can do better. It may not look obvious
 now, but we are already writing business logic inside a web route. We
 should extract as much logic as possible from the route. It will make
-everything so much easier to test in the long run.
+everything so much easier to write and test in the long run.
 
-My point here is that we have one business rule: rendering
+My point here is that we have one application function: rendering
 products. We can have a function for this:
 
 ```lisp
@@ -137,7 +137,7 @@ products. We can have a function for this:
   (render-products))
 ```
 
-The great benefit is that you can run `(render-products)` by itself (and
+The benefit is that you can run `(render-products)` by itself (and
 very quickly with `C-c C-y` `M-x slime-call-defun`) to test it in the
 REPL, and see the HTML output.