leonidas/transparency — Issue #26: New syntax for directives (API break: Attribute assignment)
Author: pyykkis
Created: 2012-03-02 16:11:38+00:00
State: open
Labels: Feature

I'm planning to implement a new API for directives. Main motivation is to clarify and harmonize the functionality. This issue invalidates the issues
https://github.com/leonidas/transparency/issues/21
https://github.com/leonidas/transparency/issues/22

New API extends functionality by providing `append` and `prepend`, while `replace` remains as a default. Additionally, `index` is added as a new parameter for directives, which makes adding line counts or `even` and `odd` classes a breeze.

Principles:

1. Keys are used to select elements. No more weird `@` symbols and semantic confusion due to mixing element selection and attribute assignment.

2. If the return value of a directive is type of `string`, it get assigned to the matching elements as text content. This provides backward compatibility and simplicity for the most common scenario.

3. Optionally, directive can return an `object`, i.e., key-value pairs. Keys can be either `text`, `html` or any attribute name, e.g., `class`, `src` or `href`. Values can be either type of `string`, or objects. If the value is an object, it's expected to be either `{append: "value"}` or `{prepend: "value"}`, providing the obvious functionality.

Examples:

```coffeescript
data =
firstname: "John"
lastname: "Wayne"
friends: [
name: "Uncle Bob"
, name: "Jeff Buckley"
, name: "Matt Hughes"
]

directives =
# Render text content
name1: ->
"#{@firstname} #{@lastname}"

# Render html content
name2: ->
html: "#{@firstname} #{@lastname}" # Render html content

# Render text content and append class
name3: ->
text: "#{@firstname}"
class: append: " even"

friends:
name: (element, i) ->
text: @name
class: append: if i % 2 then " odd" else " even"

$('#template').render data, directives
```

```html

John Wayne

John Wayne

John

Uncle Bob

Jeff Buckley

Matt Hughes

```

Waiting for comments until Monday.