Permalink
Browse files

added two new sections

  • Loading branch information...
1 parent 4d6690b commit dc786e940cbee92ed61687a6a0619071502e6246 @mark-hahn committed Jul 12, 2011
Showing with 40 additions and 2 deletions.
  1. +40 −2 README.md
View
@@ -3,7 +3,7 @@ A Beginners's Intoduction to CoffeeKup
This is a work in progress for a mini-book. It started out to be a one-page introduction but I found it was easier to write something longer. It takes less thinking.
-This is meant to be a collaborative effort and I will gladly give credit to anyone who helps, even to just point out typos. To contribute please submit issues to this project.
+This is meant to be a collaborative effort and I will gladly give credit to anyone who helps, even to just point out typos. To contribute please submit issues or pull requests to this project.
I am not kidding when I say in the book that I am also a beginner, learning CoffeeKup as I write this. I don't yet understand CoffeeKup very well, especially in the sections that are unwritten. So please let me know when I am passing along false information or when I am missing something that I've left out that should be said.
@@ -42,7 +42,7 @@ So how did `head ->` become `<head>`? And where does the output come from? Ther
The top part of the added code defines a lot of things, the most important of which are the functions who share their names with all the possible HTML tags. These functions, when executed, generate the associated HTML code and append it to a buffer, also defined in the invisible code, that accumulates all of the output HTML. When all of your template code has been executed, the buffer containing the complete HTML is then returned as output by an invisible `return buffer` statement added to the bottom of the template.
-Let's walk through the execution of the Hello World template code. First the `head` function is called with the `title` function as an argument. The `head` function adds the `<head>` text to the buffer, then calls the `title` function and adds it's return value to the buffer, and finally adds the closing `</head>`.
+Let's walk through the execution of the Hello World template code. First the `head` function is called with the `title` function as an argument. The `head` function adds the `<head>` text to the buffer, then calls the `title` function which adds it's own html to the buffer, and finally adds the closing `</head>`.
The `title` function was called with `"Hello World"` as its only argument. In a case like this, the function only had to wrap `<title>` and `</title>` around the string it was passed and add the whole thing to the buffer. The `body` function did the same thing as the `head` function except that the function passed to it returned nothing.
@@ -53,6 +53,44 @@ If this was all there was to KoffeeKup then it would already be quite useful as
Adding Attributes
---
+We know how to put anything we want for the inner html for a tag. You just include an arbitrary string as an argument to the tag function. But how do you put attributes inside the tag itself? Luckily that is very easy. Check this out ...
+
+ div id:"ugly-box", style:"width:90px, height:90px, background-color: purple, border: 5px green"
+
+ <div id="ugly-box"
+ style="width:100px, height:100px, background-color: purple, border: 5px green">
+ </div>
+
+Any `object` (aka `hash`) used as an argument to a tag function is interpreted as a set of attributes. The hash keys are the attribute names and the hash values are the attribute values. In coffescript hashes are created easily and they are perfect for KoffeeKup's attributes.
+
+Let's look at this more complicated example which ties everything we know together ...
+
+ div id:"another-ugly-box", style:"background-color: purple, border: 5px yellow", ->
+ span (color:"green"), "And I'm ugly text"
+
+ <div id="another-ugly-box" style="background-color: purple, border: 5px yellow">
+ <span color="green">And I'm ugly text</span>
+ </div>
+
+Now it is starting to look like real html you'd find on an ugly web page. Did you notice the parentheses around `color:"green"`? In older versions of coffeescript this is needed so that the string after it is not treated as part of the hash. The newest versions of CoffeeScript have changed the rules so this isn't needed. I'm going to assume the latest version of CoffeeScript in the following examples to keep them prettier. As of this writing the KoffeeKup online trial page uses an older version of CoffeeScript. So add the parentheses before trying them out there.
+
+Lonely Text
+---
+
+At this point in my use of KoffeeKup I was starting to think I knew how to generate any html, but then I ran into a stumbling block. I needed to put some text between tags and not inside a tag. This is a hole in the KoffeeKup logic described so far, but the hole has been filled with a fake tag named `text` ...
+
+ span color:"red", "I'm bright red!"
+ text "I'm boring black"
+ span color:"blue", "I'm feeling blue"
+
+ <span color="red">I'm bright red!</span>
+ I'm boring black
+ <span color="blue">I'm feeling blue</span>
+
+The text tag (function) just adds whatever text is in its string argument to the output buffer. If the `text` function was missing, it would still be legal CoffeeScript, and the template would execute without error, but the text would be lost because nothing added it to the output buffer.
+
+Before we leave the discussion of general text I'd like to point something out. Whether it is a string argument to a real tag like `div`, or a string argument to the fake `text` tag, a string can contain any text, even html. We will learn how to do this properly in the section _The Great Escape_.
+
Variables, Conditionals, Loops, And Functions Galore
---

0 comments on commit dc786e9

Please sign in to comment.