Beginner's Introduction To CoffeeKup #46

Open
mark-hahn opened this Issue Jun 18, 2011 · 21 comments

Comments

Projects
None yet
5 participants
@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

This comment has been minimized.

Show comment Hide comment
@lorensr

lorensr Jun 27, 2011

I agree it would be useful.

lorensr commented Jun 27, 2011

I agree it would be useful.

@randallb

This comment has been minimized.

Show comment Hide comment
@randallb

randallb Jul 11, 2011

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

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

@mauricemach

This comment has been minimized.

Show comment Hide comment
@mauricemach

mauricemach Jul 12, 2011

Owner

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.

Owner

mauricemach commented Jul 12, 2011

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

This comment has been minimized.

Show comment Hide comment
@mark-hahn

mark-hahn Jul 12, 2011

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.

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

This comment has been minimized.

Show comment Hide comment
@mauricemach

mauricemach Jul 12, 2011

Owner

"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?
Owner

mauricemach commented Jul 12, 2011

"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

This comment has been minimized.

Show comment Hide comment
@mark-hahn

mark-hahn Jul 12, 2011

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.

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

This comment has been minimized.

Show comment Hide comment
@mauricemach

mauricemach Jul 12, 2011

Owner

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?

Owner

mauricemach commented Jul 12, 2011

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

This comment has been minimized.

Show comment Hide comment
@mark-hahn

mark-hahn Jul 13, 2011

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.

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

This comment has been minimized.

Show comment Hide comment
@mauricemach

mauricemach Jul 13, 2011

Owner

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

Owner

mauricemach commented Jul 13, 2011

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

@randallb

This comment has been minimized.

Show comment Hide comment
@randallb

randallb Jul 13, 2011

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.

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

This comment has been minimized.

Show comment Hide comment
@mauricemach

mauricemach Jul 25, 2011

Owner

@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.

Owner

mauricemach commented Jul 25, 2011

@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

This comment has been minimized.

Show comment Hide comment
@mark-hahn

mark-hahn Aug 13, 2011

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.

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

This comment has been minimized.

Show comment Hide comment
@mauricemach

mauricemach Aug 18, 2011

Owner

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.
Owner

mauricemach commented Aug 18, 2011

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

This comment has been minimized.

Show comment Hide comment
@mark-hahn

mark-hahn Aug 18, 2011

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?

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 mark-hahn closed this Aug 18, 2011

@mark-hahn mark-hahn reopened this Aug 18, 2011

@mark-hahn

This comment has been minimized.

Show comment Hide comment
@mark-hahn

mark-hahn Aug 18, 2011

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

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

@mauricemach

This comment has been minimized.

Show comment Hide comment
@mauricemach

mauricemach Aug 18, 2011

Owner

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)
Owner

mauricemach commented Aug 18, 2011

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

This comment has been minimized.

Show comment Hide comment
@mark-hahn

mark-hahn Aug 18, 2011

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.

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

This comment has been minimized.

Show comment Hide comment
@mauricemach

mauricemach Aug 18, 2011

Owner

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.

Owner

mauricemach commented Aug 18, 2011

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.

This comment has been minimized.

Show comment Hide comment
@ghost

ghost Sep 11, 2011

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)?

ghost commented Sep 11, 2011

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

This comment has been minimized.

Show comment Hide comment
@mauricemach

mauricemach Sep 13, 2011

Owner

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
Owner

mauricemach commented Sep 13, 2011

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

This comment has been minimized.

Show comment Hide comment
@balupton

balupton Sep 20, 2011

Awesome stuff and very well written.

How come it isn't a wiki page though?

Awesome stuff and very well written.

How come it isn't a wiki page though?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment