Hello world.
# Configuration Dapper allows you to create static websites in just about any way that you want to. The project configuration file (`_config.yml`) allows you to specify special instructions to Dapper and also to guide the process of rendering the site using the source files (`_source/`) and the layout templates (`_layout/`). Variables specified in `_config.yml` are done using YAML. Here is the default configuration file created after a `dapper init` command: # Dapper configuration file. --- name: My Site Note that lines beginning with `#` are comments. Lines with `---` mark the beginning/end of a YAML "document". What follows are `{{ 'foo' | append:'bar' }} #=> 'foobar'
`capitalize` | Capitalize words in the input sentence
`date_to_xmlschema` | [DSF] Convert a date to an XML-formatted version of the date that also includes the timezone
`date` | Reformat a date ([syntax reference](http://search.cpan.org/~sanko/Template-Liquid-v1.0.2/lib/Template/Liquid/Filters.pm))
`divided_by` | Division *e.g.* {{ 10 | divided_by:2 }} #=> 5
`downcase` | Convert an input string to lowercase
`first` | Get the first element of the passed in array
`join` | Join elements of the array with certain character between them
`json` | [DSF] Convert an object or string to a JSON representation
`last` | Get the last element of the passed in array
`minus` | Subtraction *e.g.* {{ 4 | minus:2 }} #=> 2
`modulo` | Remainder, *e.g.* {{ 3 | modulo:2 }} #=> 1
`newline_to_br` | Replace each newline (\n) with html break
`plus` | Addition *e.g.* {{ '1' | plus:'1' }} #=> '11', {{ 1 | plus:1 }} #=> 2
`prepend` | Prepend a string *e.g.* {{ 'bar' | prepend:'foo' }} #=> 'foobar'
`remove_first` | Remove the first occurrence *e.g.* {{ 'barbar' | remove_first:'bar' }} #=> 'bar'
`remove` | Remove each occurrence *e.g.* {{ 'foobarfoobar' | remove:'foo' }} #=> 'barbar'
`replace_first` | Replace the first occurrence *e.g.* {{ 'barbar' | replace_first:'bar','foo' }} #=> 'foobar'
`replace_last` | [DSF] Replace the last occurrance of a string with another string
`replace` | Replace each occurrence *e.g.* {{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar'
`size` | Return the size of an array or string
`smart` | [DSF] Replace dashes with mdashes and ndashes
`sort` | Sort elements of the array
`split` | Split a string on a matching pattern *e.g.* {{ "a~b" | split:"~" }} #=> ['a','b']
`strip_html` | Strip html from string
`strip_newlines` | Strip all newlines (\n) from string
`times` | Multiplication *e.g* {{ 5 | times:4 }} #=> 20
`truncate` | Truncate a string down to x characters
`truncatewords` | Truncate a string down to x words
`upcase` | Convert an input string to uppercase
`xml_escape` | [DSF] Escape strings that may contain XML so the string can be included in XML files such as ATOM or RSS feeds
## Logic Tags
Logic Tags are used for controlling the procedural flow through a template.
Here is a list of supported tags:
* **assign** - Assigns some value to a variable
* **capture** - Block tag that captures text into a variable
* **case** - Block tag, its the standard case...when block
* **comment** - Block tag, comments out the text in the block
* **cycle** - Cycle is usually used within a loop to alternate between values, like colors or DOM classes.
* **for** - For loop
* **if** - Standard if/else block
* **include** - Includes another template; useful for partials
* **raw** - temporarily disable tag processing to avoid syntax conflicts.
* **unless** - Mirror of if statement
### Assign
In Liquid templates, data can be stored in variables. These variables
can then be used in output or other tags as appropriate. The simplest way to create a variable is with the `assign` tag. Example:
```liquid
{% assign category = 'featured' %}
{% for t in page.categories %}{% if t == category %}
{{ page.title }} is a featured article.
{% endif %}{% endfor %} ``` Another way of doing this would be to assign `true / false` values to the variable: ```liquid {% assign flagged = false %} {% for t in page.categories %}{% if t == 'featured' %} {% assign flagged = true %} {% endif %}{% endfor %} {% if flagged %}{{ page.title }} is a featured article.
{% endif %} ``` ### Capture If you want to combine a number of strings into a single string and save it to a variable, you can do that with the `capture` tag. This tag is a block which "captures" whatever is rendered inside it, then assigns the captured value to the given variable instead of rendering it to the screen. ```liquid {% capture date_string %}Article published {{ page.date | date: "%d %B %Y" }}{% endcapture %}{{ date_string }}
``` ### Case Liquid has a built-in `case` construct, which can be used as follows: ```liquid {% case template %} {% when 'preface' %} Preface: {{ page.title }} {% when 'product' %} {{ page.product_name }} {% else %} No template given {% endcase %} ``` ### Comments Comments in Liquid are also possible. Example: ```liquid {% comment %}Here is a comment{% endcomment %} A regular sentence that will be rendered in the final output. ``` ### Cycle Often you have to alternate between different colors or similar tasks such as when coloring all even rows in a table. Liquid has built-in support for cycles. Example: ```liquid {% cycle 'flip', 'flop' %} {% cycle 'flip', 'flop' %} {% cycle 'flip', 'flop' %} {% cycle 'flip', 'flop' %} ``` ... which will result in: ``` flip flop flip flop ``` If no name is supplied for the cycle group, then it's assumed that multiple calls with the same parameters are one group. If you want to have total control over cycle groups, you can optionally specify the name of the group. This can even be a variable. ```liquid {% cycle 'group 1': 'one', 'two', 'three' %} {% cycle 'group 1': 'one', 'two', 'three' %} {% cycle 'group 2': 'one', 'two', 'three' %} {% cycle 'group 2': 'one', 'two', 'three' %} ``` ... which will result in: ``` one two one two ``` ### For Liquid allows `for` loops over collections. Example: ```liquid {% for item in array %} {{ item }} {% endfor %} ``` When iterating a hash, `item[0]` contains the key, and `item[1]` contains the value: ```liquid {% for item in hash %} {{ item[0] }}: {{ item[1] }} {% endfor %} ``` During every `for` loop, the following helper variables are available for extra styling needs: ```liquid forloop.length # => length of the entire for loop forloop.index # => index of the current iteration forloop.index0 # => index of the current iteration (zero based) forloop.rindex # => how many items are still left? forloop.rindex0 # => how many items are still left? (zero based) forloop.first # => is this the first iteration? forloop.last # => is this the last iteration? ``` There are several attributes you can use to influence which items you receive in your loop: * `limit:int` lets you restrict how many items you get. * `offset:int` lets you start the collection with the nth item. Example: ```liquid # array = [1,2,3,4,5,6] {% for item in array limit:2 offset:2 %} {{ item }} {% endfor %} # results in 3,4 ``` It's also possible to reverse the order of how you iterate through a loop: ```liquid {% for item in collection reversed %} {{item}} {% endfor %} ``` Instead of looping over an existing collection, you can define a range of numbers to loop through. The range can be defined by both literal and variable numbers: ```liquid # if item.quantity is 4... {% for i in (1..item.quantity) %} {{ i }} {% endfor %} # results in 1,2,3,4 ``` ### If/Else Liquid also supports a standard `if / else` construct. Liquid allows you to write simple expressions in the `if` or `unless` (and optionally, `elsif` and `else`) clause. Example: ```liquid {% if site.author %} Author: {{ site.author }} {% endif %} ``` Here is the same thing, but done with a `!=`: ``` # Same as above {% if site.author != null %} Author: {{ site.author }} {% endif %} ``` Example if/else format: ```liquid {% if site.author == 'markbenson' %} Author: MDB {% elsif site.author == 'loomisbuschwa' %} Author: Loomis Buschwa {% endif %} ``` Complex or/and logic: ```liquid {% if site.author == 'markbenson' or site.author == 'loomisbuschwa' %} Author: Mark or Loomis {% endif %} ``` ```liquid {% if site.author == 'markbenson' and site.author == 'loomisbuschwa' %} Author: Mark and Loomis {% endif %} ``` Not equal: ```liquid {% if site.author != 'markbenson' %} Author: not MDB {% endif %} ``` Same as above: ```liquid {% unless site.author == 'markbenson' %} Author: not MDB {% endunless %} ``` Check the size of an array: ```liquid {% if site.links == empty %} No links defined. {% endif %} {% if site.links.size > 1 %} Multiple links defined. {% endif %} ``` ```liquid {% if site.authors contains 'markbenson' %} MDB in the house. {% endif %} ``` ```liquid {% if site.author contains 'mark' %} One of the author's name is Mark. {% endif %} ``` ### Raw Raw temporarily disables tag processing. This is useful for generating content (eg, Mustache, Handlebars) which uses conflicting syntax. ```liquid {% raw %} In Handlebars, {{ this }} will be HTML-escaped, but {{{ that }}} will not. {% endraw %} ``` ### Unless Mirror of [If](#if-else) statement. Example: ``` {% unless some.value == 3 %} Well, the value sure ain't three. {% elseif some.value > 1 %} It's greater than one. {% else %} Well, is greater than one but not equal to three. Psst! It's {{some.value}}. {% endunless %} ``` # Deployment To deploy your content, you have a number of options. This section outlines a few of them. ## Amazon S3 It's possible to serve a static website using Amazon S3. Here's how. 1. Go to Amazon's AWS Console and create 2 buckets: 'www.mydomain.com' and 'mydomain.com'. Content will be loaded into the 'mydomain.com' bucket and 'www.mydomain.com' will just point to it. 2. Under the properties for the 'www.mydomain.com' bucket, choose 'redirect all requests to another host name' under 'Static Web Hosting'. 3. Under properties for 'mysite.com', choose 'enable website hosting' under 'Static Web Hosting', and set 'Index Document' to 'index.html'. 4. Install [s3cmd](http://s3tools.org/s3cmd). On Mac OSX, using [Homebrew](http://brew.sh/), install like this: $ pip install s3cmd 5. Configure `s3cmd` with your Amazon credentials (AWS access key, secret key): $ s3cmd --configure 6. Now any time you want to rebuild your content and push it to s3, it's a simple call to: $ s3cmd sync _output/ s3://mydomain.com --reduced-redundancy --acl-public --delete-removed A few notes about the options. First, `--reduced-redundancy` tells Amazon that your website content is non-critical and easily reproducible if there is a problem. It means your charges from Amazon will be less and is a good option for most static sites. Second, the `--acl-public` option makes everything in the bucket public, which is what we want for a static website. We want the world to have read access to the contents of the bucket, and `--acl-public` accomplishes this. Third, the `--delete-removed` option tells `s3cmd` to delete files in the bucket that are not stored locally. This cleans things up so that you don't have lots of extra crap sitting in your bucket that isn't being used, but is costing you money. If you upload image files independently of Dapper or `s3cmd`, you may want to not use this option. An optional step is to route traffic to your website through Amazon's Route 53. To do this, follow these steps: 1. Create 2 A records, one for 'mydomain.com' and one for 'www.mydomain. com'. 2. For each A record, set 'Alias' to yes, and set 'Alias Target' to the S3 bucket with the same name. To make it easy to publish to Amazon S3, one option is to create a Makefile that encodes the publishing instructions. Here is a Makefile that I use for [Vanilla Draft](http://vanilladraft.com/): BASEDIR=$(CURDIR) INPUTDIR=$(BASEDIR)/_source OUTPUTDIR=$(BASEDIR)/_output S3_BUCKET=vanilladraft.com build: dapper build serve: build dapper serve publish: build s3cmd sync $(OUTPUTDIR)/ s3://$(S3_BUCKET) --reduced-redundancy --acl-public --delete-removed watch: dapper watch .PHONY: build serve publish watch ## FTP FTP is perhaps the most simple option. Just upload the contents of your `_output` directory to the directory on your server that is served by your webserver application. # Further Reading You can look for more information here: * [CPAN](http://search.cpan.org/dist/App-Dapper/) * [Github](https://github.com/markdbenson/dapper) * [Issues](https://github.com/markdbenson/dapper/issues) * [Historical Releases on BackPAN](http://backpan.perl.org/authors/id/M/MD/MDB/) * [Continuous Integration Status](https://travis-ci.org/markdbenson/dapper) # Appendix B: Extending Dapper may be used as a perl module directly from a script. Examples: use App::Dapper; # Create a Dapper object my $d = App::Dapper->new(); # Initialize a new website in the current directory $d->init(); # Build the site $d->build(); # Serve the site locally at http://localhost:8000 $d->serve(); After installing Dapper, you can find documentation for this module with the perldoc command. perldoc App::Dapper # Appendix B: Debugging With templating, it's easy to outsmart yourself and forget what variables are assigned to which collection and how that collection should be used in a template. Here is a way to debug that makes use of the `json` template filter built in to Dapper. The resulting page that we'll create displays all of the Liquid tags that are available for you to use. First, create a debug page in your `_source` directory: $ echo "" > _source/debug/index.html Then, edit the file and fill it with this content: ```html --- name: Debug layout: plain ---