Beginner's Introduction To CoffeeKup

[mark-hahn]

I bitched in an earlier thread that I couldn't find any docs to learn CoffeeKup. I offered to write some docs if anyone helped. Well I've decided to go ahead and write something and hope some of you help as I go along.

I've finished the first section. Please check it out at https://github.com/mark-hahn/coffeekup-intro. I am writing this as I figure out CoffeeKup so what you see is what I've learned so far. I will announce here when each section is finished unless someone objects. I will probably have a new section every couple of days

Please post your comments as issues on that project or as replies here and I will copy the reply comment over. Please be brutal in your comments. If you think it is boring, wrong, etc. just say so. Compliments will also be accepted.

[lorensr]

I agree it would be useful.

[randallb]

I'm willing to help you document this stuff. Will put it on my todos for this week.

[mauricemach]

Can't thank you enough for stepping up to this. Nice intro! Looking forward to see it complete.

I added a link to it on the readme. I'm going to revamp the website soon too, when I do I'll make sure we have a link to it there featuring prominently.

[mark-hahn]

Since you are all watching me now, I felt pressured to put in more work. I've added four or five new sections tonight. Unfortunately the number of sections remaining to be done only shrunk by one or two. That is because I keep adding more sections as I write. This thing is going to be long.

Please read and comment. If you say nothing then I will assume it is perfect. :-)

@randallb Pick any of the topics near the bottom, like helpers. I am hoping that you know ck better than I. I have no idea what a helper is.

[mauricemach]

"Helpers" are nothing special, I just borrowed the terminology from rails/sinatra for when you pass a utility function to your template, such as rails' mail_to.

What I find interesting is that while in ERB these functions are relegated to extraneous <%%> blocks, in CoffeeKup they share the same "namespace" as "normal tags/elements", so it feels like you can extend the language's vocabulary to deal with your domain model.

Notes about the text:

• I'm finding it fun to read and true to the way things work in CK.
• Thanks for the note on arrays, actually I hadn't thought about it till now.
• There's a typo on the the title: "int_r_oduction".
• You spell it _K_offeeKup in some places. Is this on purpose?

[mark-hahn]

Fixed typo and CoffeeKup spelling. it figures that I would misspell the name of the entire subject I am documenting.

P.S. Someone needs to update the version of CS used in the CK trial page. I found several things that makes CK look better in the latest versions. I want the docs to match the trial page, although I realize the docs will need to be updated as CS and CK change.

[mauricemach]

I intend to publish 0.2.4 to npm ASAP, then update the website. I just want to make sure nobody has major issues with it, especially packaging issues. Do you?

[mark-hahn]

I thought I responded to this but I don't see the response here.

I'm not going to be able to look at 0.2.4 until next week so I'm not going to be able to help.

[mauricemach]

No problem. Actually, I'll just publish it on npm as 0.2.4beta.

[randallb]

I think it's best if i write what I know, which is maybe a guide to coffeekup w/ express. Maybe a "hello world" and the sort. I'll fork your docs repo and write something up.

[mauricemach]

@mark-hahn merged 0.2.4beta back into master and renamed it to 0.3.0beta. Updated the website with this version. It's still not on npm, I want to do some more checks before publishing.

[mark-hahn]

I think I've finished my document at https://github.com/mark-hahn/coffeekup-intro. Send me corrections, comments, and hate-mail.

I'm a little concerned that my doc may already be out of date. I'm still using the same CK I was using when I started. Let me know where it is outdated.

[mauricemach]

Finally got the time to read it thoroughly. Nice job! I'm really thankful you took the time to write such a nice article.

My only notes:

• The code block at "Cool formatting" has extra indentation.
• At "Homemade HTML": "CoffeeCup". :)
• "The coffeekup namespace object" - I'd just call it "the coffeekup object", since it's not an empty object used just for namespacing, it's the templating engine itself.
• Why coffeekup = window.CoffeeKup? You can just use it directly (ex.: CoffeeKup.render).
• Perhaps the 2nd part of "Cool Running" (from "You might wonder though" on) could be a separate section called something like "how it works".
• The only sections that need updating are "Keeping things in context" and "The option to use options". Take a look at the new reference. Essentially the new input format is ck.render tpl, {foo: 'bar', locals: {ping: 'pong'}, hardcode: {zig: 'zag'}}, where foo will be available as @foo, ping will be a dynamic_locals-style local, and zig will be a "baked" local.

[mark-hahn]

Thanks for reading.

I suspected my fork was getting old. I need to update my fork and also make the changes you list. I'll also study up on helpers.

BTW: Any thoughts about how to do plug-ins?

[mark-hahn]

Oops. Didn't mean to close it. Close Issue should have an undo.

[mauricemach]

By the way, Express is the most popular web framework for node. Zappa is a CoffeeScript syntactic sugar layer I wrote for Express (named after the Zappa you know), and Meryl is another node web framework by a friend.

"Helpers" are nothing special like I said above, it's just when you write functions that generate HTML and pass them as locals to your template. They feel like "custom tags". Ex.:

template = ->
  h1 @title
  form method: 'post', action: 'login', ->
    textbox id: 'username'
    textbox id: 'password'
    button @title

helpers =
  textbox: (attrs) ->
    attrs.type = 'text'
    attrs.name = attrs.id
    input attrs

ck.render(template, title: 'Log In', hardcode: helpers)

[mark-hahn]

Thanks. I was already using helpers and I didn't know it. I'll do a section on helpers.

I'll just remove any mention of the frameworks.

I noticed you changed the default for locals to be dynamic (I wonder if that will break my code). I assume you disagree about the disadvantage of dynamic locals using "with". I'll rethink that comment.

[mauricemach]

It's not actually a default, the option controlling that is gone, now each type of locals go in a differently named object. You can even use both types together.

But I named the "dynamic" type as locals because that's the behaviour most people expect, and it's also how most templating engines work. The "hardcoded" method AFAIK is a crazy invention of mine, and now you can't use it unknowingly.

[ghost]

I just finished reading this guide - it's really excellent! Thank you!

Re: the fact that arrays are not used - could they perhaps be useful for specifying HTML attributes that don't take a value, e.g., <form autofocus></form> (http://diveintohtml5.org/forms.html#autofocus)?

[mauricemach]

The problem is that they wouldn't mix with the other attributes:

form action: '/', method: 'post', ['autofocus']

The current way reads better and doesn't require extra implementation:

form action: '/', method: 'post', autofocus: on

[balupton]

Awesome stuff and very well written.

How come it isn't a wiki page though?