Skip to content

Commit

Permalink
Got everything up until a lot of filters
Browse files Browse the repository at this point in the history
  • Loading branch information
@jeremyruppel
jeremyruppel committed Feb 10, 2012
1 parent 58b8d8c commit 86dad8c
Showing 1 changed file with 194 additions and 68 deletions.
262 changes: 194 additions & 68 deletions README.md
View file
Expand Up @@ -22,31 +22,54 @@ but with a couple of important differences in philosophy and style:
- **Keep the core library light.**
While **walrus** ships with a bunch of filters and helpers you can use out-of-the-box, only the essentials
are included in the core. This keeps client-side code as small as it can be, letting you opt-in to extras
only as often as you need them.
only as often as you need them. To extend **walrus** with new filters and helpers, just include the
javascript you want and you're done, son.

- **Stop hashing and slashing.**
Maybe it's just me, but opening and closing blocks with "hash-something" "slash-something" feels super redundant.
Walrus uses do/end for its blocks, which should look a lot more familiar to ruby types.

The **walrus** parser is written in [jison][jison] and the rest in [coffeescript][coffeescript], and everything is tested with [mocha][mocha].
The **walrus** parser is written in [jison][jison] and the rest in [coffeescript][coffeescript], and everything
is tested with [mocha][mocha].

Since **walrus** is still pretty young, expect changes in the API, especially for filters and helpers.

The `/test/examples` directory is filled with plenty of self-documenting examples that comprise over half of
the test suite, so give those a once-over if you have a question that isn't answered in the readme.

## Core

The **walrus** core contains the walrus parser/compiler, several common helpers and filters, and a few internal utility methods.

### Usage in JavaScript

Like other [jison][jison]-based parsers, templating with **walrus** is a two-step process.

First, grab your template and compile it:

``` js
var compiledTemplate = Walrus.Parser.parse( $( '#my-template' ).html( ) );
```

`compiledTemplate` is a JavaScript object ready to accept a view object and kick out some text.

``` js
var htmlGoodness = compiledTemplate.compile( { data : 'foo bar baz' } );
```

### Paths

Like some of the other templating solutions out there, Walrus will let you reference members using object paths.

If your view object is:

``` json
{
"hello" :
{
"walrus" : "sweeet."
"hello" :
{
"walrus" : "sweeet."
}
}
}
```

Then `{{hello.walrus}}` will resolve to `sweeet.`.
Expand All @@ -59,31 +82,31 @@ Use this even if you're dereferenced, iterating, or even within the arguments to
So if you've got a view object like:

``` json
{
"team" : "Detroit Red Wings",
"players" :
[
{
"name" : "Pavel Datsyuk"
},
{
"name" : "Nicklas Lidström"
},
{
"name" : "Darren Helm"
}
]
}
{
"team" : "Detroit Red Wings",
"players" :
[
{
"name" : "Pavel Datsyuk"
},
{
"name" : "Nicklas Lidström"
},
{
"name" : "Darren Helm"
}
]
}
```

You can create your badass hockey roster like:

``` html
<ul>
{{:each players do}}
<li>{{name}} plays for the {{@team}}</li>
{{end}}
</ul>
<ul>
{{:each players do}}
<li>{{name}} plays for the {{@team}}</li>
{{end}}
</ul>
```

### Methods
Expand All @@ -94,116 +117,219 @@ call your methods with any number of arguments from the view object or (most) ja
With a view object like:

``` js
{
"captitalize" : function( str ){ return str.charAt( 0 ).toUpperCase( ) + str.slice( 1 ); },
"city" : "detroit"
}
{
"captitalize" : function( str ){ return str.charAt( 0 ).toUpperCase( ) + str.slice( 1 ); },
"city" : "detroit"
}
```

It's as easy as `{{capitalize( city )}}`.

> Note that since both of these members are at the root of the view object, you could also reference them like
> `{{@capitalize( @city )}}`, or any combination of local or root references.
### Blocks/Helpers
## Core Blocks/Helpers

In Walrus, blocks don't look like the `#member`/`/member` hash/slash pairs we've seen elsewhere. Walrus looks
a lot more like ruby and uses a simpler `do`/`end` idiom.

Each block has a helper, preceded by `:`, that tells you what the block does. Walrus ships with a basic set of
these built in.

#### :if and :unless
### :if and :unless

Conditionals can be represented by `:if` and `:unless` blocks. Both of these test the expression for truthiness
or falsiness respectively.

``` html
{{:if @loggedIn do}}
<p>Welcome back, {{@username}}!</p>
{{end}}
{{:if @loggedIn do}}
<p>Welcome back, {{@username}}!</p>
{{end}}

{{:unless @loggedIn do}}
<p>I don't believe we've met!</p>
{{end}}
{{:unless @loggedIn do}}
<p>I don't believe we've met!</p>
{{end}}
```

#### :each
### :each

`:each` can be used to iterate over a collection.

``` html
{{:each @player do}}
<li>{{name}}</li>
{{end}}
{{:each @player do}}
<li>{{name}}</li>
{{end}}
```

> Like several other templating solutions, you can implicitly iterate over a collection of values, like strings, and template in the current value with `{{.}}`.
#### :with
### :with

`:with` can be used to force a change in context if you don't want to use tons of object paths.

``` html
{{:with @team.captain do}}
<p>Captain: {{name}}</p>
{{end}}
{{:with @team.captain do}}
<p>Captain: {{name}}</p>
{{end}}
```

### Filters
## Core Filters

Walrus also supports the concept of filters, which look a lot like filters you might have used in [liquid][liquid] or [ejs][ejs] templates.

Filters also are preceded by `:`, but come after the main expression separated by a pipe, like `{{name | :upcase}}`.

Filters can be chained together, separated by whitespace. Filters can be used with block helpers or in a standalone expression.

#### :equals
### :equals

`:equals` tests the expression for strict equality. This is most useful with the conditional block helpers.

``` html
{{:if status | :equals( 'pending' ) do}}
<p>We're still working on it.</p>
{{end}}
{{:if status | :equals( 'pending' ) do}}
<p>We're still working on it.</p>
{{end}}
```

#### :or
### :or

`:or` can be used to provide a default or fallback value if a member doesn't exist on your view object.

``` html
<h2>{{price | :or( 'N/A' )}}</h2>
<h2>{{price | :or( 'N/A' )}}</h2>
```

#### :log
### :log

`:log` is a helper method for developers that simply passes its argument to the console.

``` html
You can log a {{@member | :log}} of the view object,
while {{. | :log}} will log the whole thing,
and {{"arbitrary literals" | :log}} can be logged, too!
You can log a {{@member | :log}} of the view object,
while {{. | :log}} will log the whole thing,
and {{"arbitrary literals" | :log}} can be logged, too!
```

## Walrus.Collections

`walrus.collections` contains helpers and filters that are useful when working with arrays.

### :first

Selects the first _count_ items of the array. Defaults to only the first item.

Parameters:

count - Optional: how many items to include

Usage:

``` html
{{ :each numbers | :first do}}
// 1
{{ end }}

{{ :each numbers | :first( 5 ) do }}
// 1 2 3 4 5
{{ end }}
```

### :last

Selects the last _count_ items of the array. Defaults to only the last item.

Parameters:

count - Optional: how many items to include

Usage:

``` html
{{ :each numbers | :last do}}
// 10
{{ end }}

{{ :each numbers | :last( 5 ) do }}
// 6 7 8 9 10
{{ end }}
```

### :count

Returns the length of the given array.

Parameters: none

Usage:

``` html
var numbers = [ 1, 2, 3, 4, 5 ];

{{ numbers | :count }} // => 5
```

### :any

Returns true if the array is not empty. Opposite of `:empty`.

Parameters: none

Usage:

``` html
var numbers = [ 1, 2, 3, 4, 5 ];

{{ numbers | :any }} // => true
```

### :empty

Returns true of the array is empty. Opposite of `:any`.

Parameters: none

Usage:

``` html
var numbers = [ 1, 2, 3, 4, 5 ];

{{ numbers | :empty }} // => false
```

Inspiration
-----------
## Walrus.Dates

TODO

## Walrus.Domain

TODO

Walrus was directly inspired by templating solutions like handlebars, but seeks to position itself a little differently. Handlebars' position is to [not fully support functions in templates](https://github.com/wycats/handlebars.js/pull/143). I rather like them myself, so I made Walrus.
## Walrus.Inflections

I also really liked the filter behavior included in ejs and company, but I didn't like how the filters were all built-in when I'd probably never use half of them. That may be fine for the server-side, but not for the client-side, and that's where I make my dough.
TODO

If Walrus isn't quite your style...
-----------------------------------
## Walrus.Math

One of these fine other looks might suit you:
TODO

## Walrus.Strings

TODO

In any case, Walrus borrows ideas from each of them, so they're all worth checking out!
## Mad Props

License
-------
If Walrus isn't quite your style, one of these other fine looks might suit you:

- [mustache][mustache]
- [handlebars][handlebars]
- [ejs][ejs]
- [liquid][liquid]

In any case, walrus borrows ideas from each of them, so they're all worth checking out!

Many of the filters in walrus are inspired or borrowed from [ActiveSupport][activesupport]. If walrus can
be half as helpful to developers as ActiveSupport has been, it'll be a great success.

## License

Walrus is released under the MIT license.

Expand All @@ -214,4 +340,4 @@ Walrus is released under the MIT license.
[jison]: http://zaach.github.com/jison/
[coffeescript]: http://coffeescript.org/
[mocha]: http://visionmedia.github.com/mocha/

[activesupport]: http://as.rubyonrails.org/

0 comments on commit 86dad8c

Please sign in to comment.