Building Blocks, more topics: organize per task

Author: vindarel

content/_index.md

@@ -1,5 +1,5 @@
 
-## Web apps in Lisp
+## Web Apps in Lisp: Know-how
 
 You want to write a web application in Common Lisp and you don't know
 where to start? Or you don't want to re-invent the wheel? Follow the guide.
@@ -92,7 +92,13 @@ We will learn:
 
 Your feedback and contributions are appreciated!
 
-Now let's start with a [frameworks overview](/frameworks).
+**In [part 1](/part-1/), we will get to know a classical stack: Hunchentoot, easy-routes for easier routing and Djula templates.**
+
+In part 2, we will add interactivity on the client side, with or without JavaScript.
+
+In part 3, we will build an interactive Ajax-based Todo-app without writing any JavaScript, thanks to ISSR and Weblocks.
+
+Now let's start with a [libraries overview](/part 1/).
 
 
 {{% notice note  %}}
@@ -106,6 +112,15 @@ If you find similar content from the Cookbook, this is normal. I am the main con
 {{% /notice %}}
 
 
+{{% notice info %}}
+
+Here's a 5 minutes refresh on how to create a project, how to run it from sources, how to build a binary and how to load everything in SLIME:
+
+{{% /notice %}}
+
+{{< youtube XFc513MJjos >}}
+
+
 [hunchentoot]: https://edicl.github.io/hunchentoot
 [clack]: https://github.com/fukamachi/clack
 [caveman]: https://github.com/fukamachi/caveman

content/frameworks/_index.md renamed to content/building-blocks/_index.md

@@ -1,19 +1,27 @@
+
 +++
-title = "Frameworks overview"
-weight = 10
+title = "Building blocks"
+weight = 1
 +++
 
+In this chapter we'll start by creating our first route, we'll serve
+local files and we'll run more than one web app in the same running
+image.
+
+Let's install the libraries we'll use:
 
-[Hunchentoot][hunchentoot] and [Clack][clack] are two projects that
-you'll often hear about.
+~~~lisp
+(ql:quickload '("hunchentoot" "easy-routes" "djula" "spinneret"))
+~~~
 
 {{% notice info %}}
+You can create a web project with our project generator: [cl-cookieweb](https://github.com/vindarel/cl-cookieweb).
+{{% /notice %}}
 
-CL-USER> `(ql:quickload "hunchentoot")`
 
-{{% /notice %}}
+We will use the [Hunchentoot][hunchentoot] web server, but we should say a few words about [Clack][clack] too.
 
-Hunchentoot is
+**Hunchentoot** is
 
 > a web server and at the same time a toolkit for building dynamic websites. As a stand-alone web server, Hunchentoot is capable of HTTP/1.1 chunking (both directions), persistent connections (keep-alive), and SSL. It provides facilities like automatic session handling (with and without cookies), logging, customizable error handling, and easy access to GET and POST parameters sent by the client.
 
@@ -26,7 +34,7 @@ write a function for the `:uri` parameter that does the check, when it
 is a built-in keyword in other frameworks. We will use
 the `easy-routes` library for that.
 
-Clack is
+**Clack** is
 
 > a web application environment for Common Lisp inspired by Python's WSGI and Ruby's Rack.
 
@@ -69,11 +77,6 @@ For a full list of libraries for the web, please see the [awesome-cl list
 #network-and-internet](https://github.com/CodyReichert/awesome-cl#network-and-internet)
 and [Cliki](https://www.cliki.net/Web).
 
-**In [part 1](/part-1/), we will use a classical stack: Hunchentoot, easy-routes for easier routing and Djula templates.**
-
-In part 2, we will add Ajax interactivity on the client side with some pure JavaScript and some Vue.js.
-
-In part 3, we will build an interactive Ajax-based Todo-app without writing any JavaScript, thanks to ISSR, and Weblocks.
 
 
 [hunchentoot]: https://edicl.github.io/hunchentoot

content/part 1/database.md renamed to content/building-blocks/database.md

@@ -1,7 +1,7 @@
 
 +++
 title = "Connecting to a database"
-weight = 17
+weight = 170
 +++
 
 Please see the [databases section](databases.html). The Mito ORM
@@ -138,4 +138,3 @@ library.
 ~~~
 
 *Credit: `/u/arvid` on [/r/learnlisp](https://www.reddit.com/r/learnlisp/comments/begcf9/can_someone_give_me_an_eli5_on_hiw_to_encrypt_and/)*.
-

content/deployment/_index.md renamed to content/building-blocks/deployment.md

@@ -1,6 +1,6 @@
 +++
 title = "Deployment"
-weight = 100
+weight = 200
 +++
 
 
@@ -17,16 +17,7 @@ We must ensure:
 - to install the required dependencies (this demands we have installed Quicklisp previously)
 - and to run our application's entry point.
 
-{{% notice info %}}
-
-Here's a 5 minutes refresh on how to create a project, how to run it from sources, how to build a binary, how to load everything in SLIME:
-
-{{% /notice %}}
-
-{{< youtube XFc513MJjos >}}
-
-
-So, the recipe to run our project from sources can look like this:
+So, the recipe to run our project from sources can look like this (you can find such a recipe in our project generator):
 
 ~~~lisp
 ;; run.lisp

content/building-blocks/error-handling.md

@@ -0,0 +1,18 @@
++++
+title = "Error handling"
+weight = 150
++++
+
+In all frameworks, we can choose the level of interactivity. The web
+framework can return a 404 page and print output on the repl, it can
+catch errors and invoke the interactive lisp debugger, or it can show
+the lisp backtrace on the html page.
+
+### Hunchentoot
+
+The global variables to set are `*catch-errors-p*`,
+`*show-lisp-errors-p*` and `*show-lisp-backtraces-p*`.
+
+Hunchentoot also defines condition classes.
+
+See the documentation: [https://edicl.github.io/hunchentoot/#conditions](https://edicl.github.io/hunchentoot/#conditions).

content/part 1/_index.md renamed to content/building-blocks/routing.md

@@ -1,104 +1,16 @@
-
 +++
-title = "Part 1: first project"
+title = "Routing"
 weight = 15
 +++
 
-Let's install the libraries we'll use:
-
-~~~lisp
-(ql:quickload '("hunchentoot" "easy-routes" "spinneret" "djula"))
-~~~
-
-We'll start by creating our first route, we'll serve local files and
-we'll run more than one web app in the same running image.
 
 {{% notice info %}}
 
-You can create a web project with our project generator: [cl-cookieweb](https://github.com/vindarel/cl-cookieweb).
+I prefer the easy-routes library than pure Hunchentoot to define routes, skip to its section if you want.
 
 {{% /notice %}}
 
-
-## Simple webserver
-
-### Serve local files
-
-Create and start a webserver like this:
-
-~~~lisp
-(defvar *acceptor* (make-instance 'hunchentoot:easy-acceptor :port 4242))
-(hunchentoot:start *acceptor*)
-~~~
-
-We create an instance of `easy-acceptor` on port 4242 and we start
-it. We can now access [http://127.0.0.1:4242/](http://127.0.0.1:4242/). You should get a welcome
-screen with a link to the documentation and logs to the console.
-
-By default, Hunchentoot serves the files from the `www/` directory in
-its source tree. Thus, if you go to the source of
-`easy-acceptor` (`M-.` in Slime), which is probably
-`~/quicklisp/dists/quicklisp/software/hunchentoot-v1.2.38/`, you'll
-find the `root/` directory. It contains:
-
-- an `errors/` directory, with the error templates `404.html` and `500.html`,
-- an `img/` directory,
-- an `index.html` file.
-
-To serve another directory, we give the option `document-root` to
-`easy-acceptor`. We can also set the slot with its accessor:
-
-~~~lisp
-(setf (hunchentoot:acceptor-document-root *acceptor*) #p"path/to/www")
-~~~
-
-Let's create our `index.html` first. Put this in a new
-`www/index.html` at the current directory (of the lisp repl):
-
-~~~html
-<html>
-  <head>
-    <title>Hello!</title>
-  </head>
-  <body>
-    <h1>Hello local server!</h1>
-    <p>
-    We just served our own files.
-    </p>
-  </body>
-</html>
-~~~
-
-Let's start a new acceptor on a new port:
-
-~~~lisp
-(defvar *my-acceptor* (make-instance 'hunchentoot:easy-acceptor :port 4444
-                                   :document-root #p"www/"))
-(hunchentoot:start *my-acceptor*)
-~~~
-
-go to [http://127.0.0.1:4444/](http://127.0.0.1:4444/) and see the difference.
-
-Note that we just created another web application on a different port on
-the same lisp image. This is already pretty cool.
-
-
-## Access your server from the internet
-
-With Hunchentoot we have nothing to do, we can see the server from the
-internet right away.
-
-If you evaluate this on your VPS:
-
-    (hunchentoot:start (make-instance 'hunchentoot:easy-acceptor :port 4242))
-
-You can see it right away on your server's IP.
-
-Stop it with `(hunchentoot:stop *)`.
-
-## Routing
-
-> Note: you can skip to the easy-routes part if you want.
+## Hunchentoot
 
 ### The dispatch table
 
@@ -182,7 +94,7 @@ It also has a `default-parameter-type` which we'll use in a minute to get url pa
 There are also keys to know for the lambda list. Please see the documentation.
 
 
-### Easy-routes
+## Easy-routes
 
 [easy-routes](https://github.com/mmontone/easy-routes) is a route
 handling extension on top of Hunchentoot. It provides:
@@ -310,24 +222,3 @@ or a compound list:
 - `'(:hash-table <type>)`
 
 where `<type>` is a simple type.
-
-
-<!-- ## Sessions -->
-
-<!-- ## Cookies -->
-
-## Error handling
-
-In all frameworks, we can choose the level of interactivity. The web
-framework can return a 404 page and print output on the repl, it can
-catch errors and invoke the interactive lisp debugger, or it can show
-the lisp backtrace on the html page.
-
-### Hunchentoot
-
-The global variables to set are `*catch-errors-p*`,
-`*show-lisp-errors-p*` and `*show-lisp-backtraces-p*`.
-
-Hunchentoot also defines condition classes.
-
-See the documentation: [https://edicl.github.io/hunchentoot/#conditions](https://edicl.github.io/hunchentoot/#conditions).

content/building-blocks/simple-web-server.md

@@ -0,0 +1,99 @@
+
++++
+title = "Simple web server"
+weight = 10
++++
+
+Before dwelving into web development, we might want to do something simple: serve some files we have on disk.
+
+### Serve local files
+
+Create and start a webserver like this:
+
+~~~lisp
+(defvar *acceptor* (make-instance 'hunchentoot:easy-acceptor :port 4242))
+(hunchentoot:start *acceptor*)
+~~~
+
+We create an instance of `easy-acceptor` on port 4242 and we start
+it. We can now access [http://127.0.0.1:4242/](http://127.0.0.1:4242/). You should get a welcome
+screen with a link to the documentation and logs to the console.
+
+{{% notice info %}}
+
+You can also use Roswell's [http.server](https://github.com/roswell/http.server/) from the command line:
+
+    $ ros install roswell/http.server
+    $ ros -s http.server
+    Hunchentoot server is going to start.
+    Listening on 127.0.0.1:5000.
+
+{{% /notice %}}
+
+By default, Hunchentoot serves the files from the `www/` directory in
+its source tree. Thus, if you go to the source of
+`easy-acceptor` (`M-.` in Slime), which is probably
+`~/quicklisp/dists/quicklisp/software/hunchentoot-v1.2.38/`, you'll
+find the `root/` directory. It contains:
+
+- an `errors/` directory, with the error templates `404.html` and `500.html`,
+- an `img/` directory,
+- an `index.html` file.
+
+To serve another directory, we give the option `document-root` to
+`easy-acceptor`. We can also set the slot with its accessor:
+
+~~~lisp
+(setf (hunchentoot:acceptor-document-root *acceptor*) #p"path/to/www")
+~~~
+
+Let's create our `index.html` first. Put this in a new
+`www/index.html` at the current directory (of the lisp repl):
+
+~~~html
+<html>
+  <head>
+    <title>Hello!</title>
+  </head>
+  <body>
+    <h1>Hello local server!</h1>
+    <p>
+    We just served our own files.
+    </p>
+  </body>
+</html>
+~~~
+
+Let's start a new acceptor on a new port:
+
+~~~lisp
+(defvar *my-acceptor* (make-instance 'hunchentoot:easy-acceptor :port 4444
+                                   :document-root #p"www/"))
+(hunchentoot:start *my-acceptor*)
+~~~
+
+go to [http://127.0.0.1:4444/](http://127.0.0.1:4444/) and see the difference.
+
+Note that we just created another web application on a different port on
+the same lisp image. This is already pretty cool.
+
+
+## Access your server from the internet
+
+With Hunchentoot we have nothing to do, we can see the server from the
+internet right away.
+
+If you evaluate this on your VPS:
+
+    (hunchentoot:start (make-instance 'hunchentoot:easy-acceptor :port 4242))
+
+You can see it right away on your server's IP.
+
+Stop it with `(hunchentoot:stop *)`.
+
+Now on the next section, we'll create some routes to build a dynamic website.
+
+
+<!-- ## Sessions -->
+
+<!-- ## Cookies -->