Update next script and instructions

Author: Joy Clark

todo-app/next

@@ -7,7 +7,7 @@ current_exercise_no=$(ls test/todo_app/*_tests.clj \
  | tail -n 1)
 next_exercise_no="$(printf "%02d" "$(( ${current_exercise_no} + 1 ))")"
 
-lein test .
+lein test
 
 rc=$?
 if [[ $rc != 0 ]]
@@ -16,25 +16,14 @@ then
 exit $rc; 
 fi
 
-echo "Retrieving exercise $next_exercise_no"
-
-#(git checkout $(whoami) || git checkout -b $(whoami)) 2> /dev/null
-
-#if ! git status | grep "nothin.*to commit" &> /dev/null
-#then 
-# git add *.clj && git commit --allow-empty -anm "Commit exercise $(printf "%02d" ${current_exercise_no})"
-#fi
-
-
-#git fetch --all
-
-
-#if ! git branch -a | grep "/origin/${next_exercise_no}" &> /dev/null
-#then
-# echo "The next exercise is not yet available"
-# exit 1
-#fi 
-
-#git merge --no-ff -m "Fetching exercise ${next_exercise_no}" origin/${next_exercise_no}
+if ! ls tests | grep "${next_exercise_no}_tests.clj" &> /dev/null
+then
+echo "There are no test for the next exercise!"
+echo "You must be done with your web application!"
+ echo
+ echo "Congratulations!"
+ exit 1
+fi
 
-#cat tutorial/chapters/${next_exercise_no}_instructions.md
+echo "Retrieving tests for $next_exercise_no"
+cp tests/${next_exercise_no}_tests.clj test/todo_app

tutorial/chapters/00_instructions.md

@@ -1,22 +1,33 @@
-# Tutorial Step 1
+# First Steps
 
-Install [leinigen](http://github.com/technomancy/leinigen) to build your clojure project.
+If you are reading this tutorial, the chances that you have downloaded the correct git archive are quite high. 
 
-Create a leinigen project for your todo app based on the compojure template.
+Congratulations!
 
-`lein new compojure todo-app`
+If you are viewing this tutorial in a browser, the chances that you have already installed [leinigen](http://github.com/technomancy/leinigen) are also quite high. If this is not the case, please do this right now.
 
-Update the `project.clj` so that it contains the latest version of the hiccup templating library (currently version "1.0.5")
+During this tutorial we want to have a hands on experience with Clojure and build a Clojure web application from the base up.
 
-The application can be started with the command:
+The app that we are going to be working on is the `todo-app` (so if you `'cd tutorial'`ed to start this tutorial, `cd ../todo-app` to get into the correct directory now). From now on, we will assume you are working in this directory. 
+ 
+The app was created using the compojure leinigen template
 
-`lein ring server`
+ lein new compojure todo-app
 
-By default, this will start a server on port 3000.
+If you are using the [Nightcode IDE](https://sekao.net/nightcode/) for developing Clojure (which I recommend, especially when starting out with the language), you can start the application directly from the IDE.
 
-Try to modify the application so that it returns the string "Hello My Lovely World!"
+Otherwise, you can start the app from the command line:
 
-Once you are done, execute the `./next` script to retrieve the next instruction step. 
+ lein ring server
 
-If you don't know what to do, execute the `./next` script to retrieve an example application.
+By default, this will start a server on port 3000 (the port can also be optionally specified as an additional argument)
 
+For each task in the tutorial, we have created a test file to test if the the task has been fulfilled. The first test file can already be found in the project test files: `/test/todo_app/01_tests.clj`
+
+The tests can be run as follows:
+
+ lein test
+
+Further tests for each task can be found in the `tests/` directory. If you are stuck on a specific task, don't despair! There is a `cheats/` directory which contains an example namespace that you can copy over to your project source files (`src/todo_app`) so that the tests will pass. 
+
+If you think that you have finished one of the tasks, you can execute the `next` script which will check if all tests pass, and if so, will copy over the next test file.

tutorial/chapters/01_instructions.md

@@ -1,25 +1,67 @@
-# Chapter 01
+# Basics, HTML Templating, and Namespaces
 
-Congratulations! You have created your first Clojure web application!
+If you have started the `todo-app` with `lein ring server` you can see what the app looks like at `http://localhost:3000`
 
-Currently, the application has one route '/' which returns a message in text format.
+The app currently only has a single route '/' which returns a message in text format. We want to return HTML instead of text, so let's look at what resources Clojure has to help us with this.
 
-We've created an example application `example-todo-app` which will illustrate our solution to the different tasks throughout the rest of the tutorial.
+## Basics
 
-## HTML Templating
+Clojure is a [Lisp](https://en.wikipedia.org/wiki/Lisp_(programming_language\)) which runs on the [JVM](https://en.wikipedia.org/wiki/Java_virtual_machine), which means that elements that belong together are grouped together in parentheses `(` `)`.
+
+As far as data types go, Clojure implements all of the basic data types, including integers:
+
+ 42
+
+Strings:
 
-We would like for this route to return an HTML page instead of using text. For this, we can use the Hiccup library which translates Clojure data structures into the HTML format.
+ "I'm a string!"
 
-In Clojure, one of the datatypes is a keyword. This is a symbolic identifier which stands for itself. A keyword looks like this:
+Keywords (a symbolic identifier that stands for itself):
 
  :keyword
 
- :anotherKeyword
+In Clojure, there is also great support for [persistent data structures](https://en.wikipedia.org/wiki/Persistent_data_structure) which are immutable by default and use structural sharing to remain efficient. Because Clojure is dynamically typed, they can contain a mixture of any data types. 
 
-Another important data type in Clojure are vectors. Vectors are a collection type that are similar in functionality to a list but are optimized to provide a quick lookup time for finding elements within the collection. A vector is denoted by square brackets `[` `]` and, because Clojure is a dynamic programming language, can contain elements of any type.
+The most common collection types are lists: 
+
+ (list 1 2 3)
+
+Vectors (similar in functionality to lists, but optimized to provide a quick lookup time):
 
  [:I :am :a :vector :of :keywords :and [:a :subvector :of :keywords]]
 
+Maps:
+
+ {:someKey "Some Value" "String can be keys too" 2}
+
+Commas are optional and are treated as whitespace.
+
+As stated above, in Clojure all elements which belong together are grouped in parentheses. In addition to this, [prefix notation](https://en.wikipedia.org/wiki/Polish_notation) is exclusively used, so the function or [macro](https://clojure.org/reference/macros) which is being called is always found in the first position followed by all arguments.
+
+A variable can be defined in Clojure with the `def` keyword
+
+ (def x 5)
+
+`def` should only be used for values which do not change!
+
+A function can be defined with the keyword `fn`
+
+ (fn [x] (+ x 5))
+
+To define a function which has a specific name, these two can be combined with the `defn` keyword:
+
+ (defn add2 [x y] (+ x y))
+
+That's pretty much it as far as the syntax goes! Any additional syntax that we will need for our application will be introduced as we go.
+
+The [Clojure Cheatsheet](https://clojure.org/api/cheatsheet) is a good reference for finding useful functions that can be used when developing Clojure.
+
+For programming Clojure, it is a good idea to follow [this style guide](https://github.com/bbatsov/clojure-style-guide). This has the added benefit that if you are using the [parinfer plugin](https://shaunlebron.github.io/parinfer/) (which comes built in with Nightcode), by styling your Clojure code according to the style guide, the parentheses will be correctly generated and set.
+
+## HTML Templating
+
+We can use the [Hiccup](https://github.com/weavejester/hiccup) for doing HTML templating using Clojure data structures.
+
 Hiccup takes advantage of the fact that conceptually, an HTML element is a list of subelements which has a particular name, i.e.
 
  <div>
@@ -35,11 +77,12 @@ In Clojure we have something like a list (Vectors!) and something like a name (K
 
 Hiccup provides the `hiccup.page/html5` element for generating an HTML5 page from such a data structure. This can also be combined with functions to have reusable templates!
 
- (defn page [title content]
+ (defn page [title & content]
   (html5
   [:head [:title title]]
-  [:body [:h1 title]
-  content]))
+  [:body content]))
+
+The `&` in the function specifies that the function takes a variable number of arguments. The first argument `title` is required, and any others that are passed in will be bound to `content` as a list. In Hiccup, you can simply insert the list of elements, and these will be rendered correctly within the body tag.
 
 ## Namespaces
 
@@ -66,10 +109,16 @@ Or you can just refer all of the functions from a namespace (only a good idea if
  (ns example.handler
   (:require [hiccup.page :refer :all]))
 
-Task 01:
+## Task 01:
+
+Update your application by modifiying the `project.clj` file to include a dependency to hiccup (currently in version `2.0.0-alpha1`).
+
+In the `src/todo_app/handler.clj` file, create a `page` function which sets the title of the page and adds a variable number of elements to the body of the page. Also include the 'splendor.css' file that is a static resource in the project (found under `resources/public`) to the HTML page (HINT: use the `hiccup.page/include-css` function).
+
+Use this function to produce HTML for the main route "/" which sets the title of the page to `TODO App`.
+
+Tests for this task are already present in the `/test/todo_app/01_tests.clj` file. 
 
-Update your application to include a dependency to hiccup (currently in version `2.0.0-alpha1`).
-Create a `page` function which takes the title of a page and embeds it in a generated HTML document.
-Use this function to produce HTML for the main route which sets the title of the page to `TODO App`.
+If you think you are done, execute the `next` script which will run the tests and, if successful, will copy the tests for Task 2 into the project. Then go on to the next step!
 
-Tests for this behavior can be found in the `handler_test.clj` file.
+If you need some help, look at the `project.clj` and `handler.clj` files in the `cheats/01/` directory.

tutorial/chapters/02_instructions.md

@@ -1,15 +1,14 @@
-# Chapter 02
-## Creating our domain objects
+# Creating Domain Objects
 
-In Clojure, all data types are immutable. When adding to a collection, a new collection is returned. This uses [persistent data structures](https://en.wikipedia.org/wiki/Persistent_data_structure) so that the data structures are still efficient. 
+In Clojure, all data types are immutable. When adding to a collection, a new collection is returned. As stated in [the last section](/01_instructions.md), this uses [persistent data structures](https://en.wikipedia.org/wiki/Persistent_data_structure) so that the data structures are still efficient. 
 
 This is done because a value in the real world does not and cannot change: the value `42` will always be `42`. 
 
 However, when we are dealing with the real world we have the concept of **identity** which is where we associate a logical entity with a series of values which may change over time. For instance, we may associate the entity _mouse_ with the positions `x,y` that our computer mouse takes on while we move it around our screen.
 
 This logical entity will have exactly one state at any given point of time.
 
-An in depth explanation can be found here: https://clojure.org/about/state
+An in depth explanation can be found [here](https://clojure.org/about/state).
 
 In Clojure, we can use atoms to model this concept of identity. For instance, we can define a logical entity 'counter' whose state will be incremented over time.
 
@@ -27,7 +26,7 @@ In Clojure the `!` is used to denote a function which has a side effect.
 
 ## Task 02:
 
-Define a new namespace `domain.clj` in your project.
+Define a new namespace `src/todo_app/domain.clj` in your project.
 
 Define the domain objects for the application in this file. We will model our application state `todos` as a vector containing Clojure maps with the following form:
 
@@ -37,6 +36,8 @@ Create a function `add-todo!` which adds an item to the list and then returns th
 
 Create a function `remove-todo!` which takes an item id and removes the correct item from the list.
 
-Hint: use the https://clojure.org/api/cheatsheet to see what functions can be used for dealing with maps, vectors, and keywords!
+Hint: use the [Clojure Cheatsheet](https://clojure.org/api/cheatsheet) to see what functions can be used for dealing with maps, vectors, and keywords!
 
-The desired behavior of the domain model can be seen in the `domain_test` in the example-todo-app.
+You've hopefully either executed the `next` script or copied the `tests/02_tests.clj` file over to your project. Once these tests pass, move on to the next task!
+
+If you need some help, look at the `cheats/02/domain.clj` file.

tutorial/chapters/03_instructions.md

@@ -1,58 +1,63 @@
-# Chapter 03
-## Routing
+# Routing, Middleware, and Security
 
 We now have our HTML templates and our domain objects. Now we want to tie everything together. 
 
+## Routing
+
 The library we are using for routing in our application is [Compojure](https://github.com/weavejester/compojure).
 
 We've seen the most basic route definition already.
 
-`(GET "/" [] "HI!")`
+ (GET "/" [] "HI!")
 
 If we want to extract a parameter from the URI, Compojure gives us the opportunity to destructure it.
 
-`(GET "/:book" [book] (show book))`
+ (GET "/:book" [book] (show book))
 
 This also works for form parameters
 
-`(POST "/" [something] (dosth something))`
+ (POST "/" [something] (dosth something))
 
 More information about the destructuring syntax can be found [here](https://github.com/weavejester/compojure/wiki/Destructuring-Syntax).
 
 To generate redirects, the function `ring.util.response/redirect` can be used.
 
 To generate forms, use the functions available from `hiccup.form`
 
-## Middleware & CSRF
+## Middleware
 
 In Clojure, the requests and responses are translated into Clojure data structures which are modelled as Clojure maps. This according to the [Ring standard](https://github.com/ring-clojure/ring/wiki/Concepts), which is used in all major Clojure webservers. 
 
 This gives you complete control over the requests and responses. Once pattern is to write middleware which can modify a request going in or modify a request when going out.
 
-```
-(defn middleware [handler]
- (fn [request]
- ;; Do something to request
- (let [response (handler request)]
- ;; Do something to response
- response)))
-```
+ (defn middleware [handler]
+  (fn [request]
+  ;; Do something to request
+  (let [response (handler request)]
+  ;; Do something to response
+  response)))
 
 It is not necessary to write a lot of middleware when just getting started. The default template for Compojure uses the default middleware `site-defaults` which is available from the `ring.middleware.defaults`. 
 
+## CSRF
+
 Among other things, the middleware initializes the [CSRF Protection](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF\)) that is available in Clojure. Clojure protects against Anti-Forgery attacks by rendering a secret into the HTML of a web page. With requests which modify the application state (i.e. :post, :put, :delete, :patch), the client needs to send this secret back to the server so that the server knows that it comes from a valid user. This secret can be added into your application by generating a `ring.util.anti-forgery/anti-forgery-field` within all of the necessary forms in the application.
 
+## XSS
+
+In our application, we are rendering String that we receive from the user directly in our HTML document. This makes us vulnerable for [XSS Attacks](https://www.owasp.org/index.php/Cross-site_Scripting_(XSS\)). In order to protect us, we can use the `hiccup.util/escape-html` function to escape the html output when we are rendering it in the document.
+
 Task 03:
 
 Define the following routes for the application
 
 1. GET / -> returns a list of todos
 2. POST / -> adds a new todo, redirects to /
+ * If the todo string is blank, ignore the request and redirect to /
+ * We should automatically escape any HTML from the user so that we are not vulnerable for XSS attacks
 3. GET /:id -> shows a single todo
 4. DELETE /:id -> removes todo, redirects to /
 
-The tests can be seen in the `handler_test.clj` file
-
-Now you have a working web application!
+Once the `03_tests.clj` pass, you have a working web application and can move on to the next section!
 
-As a bonus task, you can make it pretty by adding CSS!
+If you need some help, look at the `cheats/03/handler.clj` file.

tutorial/chapters/04_instructions.md

@@ -1,4 +1,4 @@
-# Chapter 04
+# Further Resources
 ## That's it for now!
 
 This is obviously only a basic web application, but there are a lot of libraries available in the Clojure universe to allow you to configure your application as you want.
@@ -7,4 +7,4 @@ Some that might be of interest
 
 * [Buddy](https://github.com/funcool/buddy-auth) for Authorization
 * [Yesql](https://github.com/krisajenkins/yesql) for dealing with SQL databases in Clojure
-* [environ](https://github.com/weavejester/environ) for configuring the application over environment variables
+* [environ](https://github.com/weavejester/environ) for configuring the application over environment variables