= Deckcards

Deckcards is a command line tool used to generate game's cards from a template and a Google Spreadsheet. It is currently operational for card prototyping.

== For non-developers

Deckcards needs somes basics knowledges in HTML/CSS and the use of command lines.

== Disclaimer

It's an early version that barely comes out of the furnace. If you want to improve this project you can contribute by submitting https://github.com/mrpierrot/deckcards/issues[an issue] or propose a https://github.com/mrpierrot/deckcards/pulls[pull request]

Currently, works fine with nodeJS 6.9.1 and should work fine with nodeJS 6.4.0 and above.

PS: My English can be poor. If you see an incorrect sentence, please report it to me, I won't take it the wrong way :-)

== Install

https://nodejs.org[NodeJS] is required to install Deckcards. You must install it.

Install with npm:

npm install deckcards -g

== Get started

=== Create a project

First, use this command to create a project with default content in the directory "project_name":

deckcards setup <project_name>

Next, go to the directory "project_name"

cd ./<project_name>

The project contains the following files :

[options="header,footer"] |=========================================== | File | Description | deckcards.json | The configuration files | templates/default.hbs | The Handlebars template file. Look at http://handlebarsjs.com/[Handlebars.js] to edit. | layouts/basic.hbs | The Handlebars layout file. Look at http://handlebarsjs.com/[Handlebars.js] to edit. | styles.css | The template's styles. |===========================================

=== deckcards.json

The default deckcards.json

[source, json]

{ "templates": { "default": "templates/default.hbs" }, "layouts": { "basic": "layouts/basic.hbs" }, "gsheet":{ "sheetId":"1QJm95kTdpR9XT6fC7sirsPRVFjOOri74-jH3mSd1gf8", "credentials":null } }

==== Description

[options="header,footer"] |============================================ | Name | Description | templates | The HTML templates path. It's a dictionnary with sheet name as key | layouts | Layout system : usefull to manage differents printers | output | The directory where final HTML files are generated | gsheet.sheetId | The Google Spreadsheet's ID. It can be found here: docs.google.com/spreadsheets/d/1QJm95kTdpR9XT6fC7sirsPRVFjOOri74-jH3mSd1gf8/edit?usp=sharing | gsheet.credentials | The credentials file path (i.e. "./credentials.json"). Set it to null if you use a public Google Spreadsheet. |============================================

=== Configure Google authentication

For private and public Google Spreadsheets, follow the instructions from https://github.com/theoephraim/node-google-spreadsheet#authentication[node-google-spreadsheet]

If you use private Google Spreadsheet, you get a JSON file with credentials. Copy this file into the project directory and rename it credentials.json

In deckcards.json, define the credentials.json path like this:

[source, json]

{ ... "gsheet":{ ... "credentials":"./credentials.json" } }

=== Google Spreadsheet Format

You can find an example https://docs.google.com/spreadsheets/d/1QJm95kTdpR9XT6fC7sirsPRVFjOOri74-jH3mSd1gf8/edit#gid=2092230795[here]

The first line contains the variable names (here: NAME and DESC) and the next lines store the values.

You can define several sheets, each of them generating its own HTML page.

==== Meta Variables

In the first line, you can define Meta variables used by the Deckcards engine

[options="header,footer"] |========================================================================== | Variable | Description | _COUNT | Repeat a card N times ( N is defined in a card line ) | _SKIP | if equal to 1 or TRUE, skip the line |==========================================================================

=== Build

Finally, to generate cards use this :

deckcards build

=== Watch

deckcards watch

You can watch templates and data files : when there are modified, the watcher build the cards

== Reference

=== Setup command

deckcards setup <project_name>

[options="header,footer"] |============================================================ | Option | Alias | Description | --template <name|path> | -t | Use a specific template |============================================================

=== Build command

deckcards build

[options="header,footer"] |============================================================ | Option | Alias | Description | --layout | -l | The chosen layout to use | --nobrowser | -n | Skip opening generated of files in the browser |============================================================

=== Fetch command

deckcards fetch

=== Watch command

deckcards watch

[options="header,footer"] |============================================================ | Option | Alias | Description | --layout | -l | The chosen layout to use | --nobrowser | -n | Skip opening generated of files in the browser |============================================================

=== Template/Layout management

Deckcards can manage template with ou without layout

==== Work without layouts

This is a example of template without layouts : All the content are in an unique template

[source, html]

==== Work with layouts

If you want to print with a basic printer machine for prototyping, you want a différent format for printing house. Layout help to work with differents this print format.

This is a basic layout :

[source, html]

You can note the

[source, html]

{{>card card=.}}

This is a basic Handlebars partial name card The current card data is pass to this partial

And your template look like this now :

[source, html]

==== Layout in deckcards.json

Basic configuration :

[source, json]

{ "templates": { "default": "templates/default.hbs" }, "layouts": { "basic": "layouts/basic.hbs" }, "gsheet":{ "sheetId":"1QJm95kTdpR9XT6fC7sirsPRVFjOOri74-jH3mSd1gf8", "credentials":null } }

Advanced configuration with layout overrides :

[source, json]

{ "templates": { "default": { "template : "templates/default.hbs", "layouts" : { "basic" : "layouts/basic-overridden.hbs" } } }, "layouts": { "basic": "layouts/basic.hbs" }, "gsheet":{ "sheetId":"1QJm95kTdpR9XT6fC7sirsPRVFjOOri74-jH3mSd1gf8", "credentials":null } }

==== Build and watch with layouts.

To buid : [source]

deckcards build -l pro

or

[source]

deckcards build --layout pro

To watch :

[source]

deckcards watch -l pro

or

[source]

deckcards watch --layout pro

=== License

Licensed under the link:LICENSE[MIT]