npm package: @mrpierrot/cardmaker
Description: A tool to create cards games
Author: Pierre Chabiland
Latest version: 5.0.0

= Cardmaker

Cardmaker 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.

= UPDATE : DECKCARDS IS NOW CARDMAKER

Cardmaker is more simple to tape than Deckcards :-)

== For non-developers

Cardmaker 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/cardmaker/issues[an issue] or propose a https://github.com/mrpierrot/cardmaker/pulls[pull request]

== Install

https://nodejs.org[NodeJS] is required to install Cardmaker. You must install it.

Install with npm:
------
npm install @mrpierrot/cardmaker -g
------

== Get started

=== Create a project

First, use this command to create a project with default content in the directory *"project_name"*:

------
cardmaker setup <project_name>
------

Next, go to the directory *"project_name"*

------
cd ./<project_name>
------

The project contains the following files :

[options="header,footer"]
|===========================================
| File                       | Description
| cardmaker.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.
|===========================================  


=== cardmaker.json

The default cardmaker.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 cardmaker.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 Cardmaker 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 : 

-------
cardmaker build
-------

=== Watch 

-------
cardmaker watch
-------

You can watch templates and data files : when there are modified, the watcher build the cards

=== Export

-------
cardmaker export
-------

You can export to pdf files

== Reference

=== Setup command

-------
cardmaker setup <project_name> <options>
-------

[options="header,footer"]
|============================================================
| Option                     | Alias | Description
| --template <name\|path>    | -t    | Use a specific template
|============================================================

=== Build command

-------
cardmaker build <options>
-------

[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

-------
cardmaker fetch
-------

=== Watch command

-------
cardmaker watch <options>
-------

[options="header,footer"]
|============================================================
| Option                    | Alias | Description
| --layout                  | -l    | The chosen layout to use
| --nobrowser               | -n    | Skip opening generated of files in the browser
|============================================================

=== Export command

-------
cardmaker export <options>
-------

[options="header,footer"]
|============================================================
| Option                    | Alias | Description
| --layout                  | -l    | The chosen layout to use
|============================================================

=== Template/Layout management

Cardmaker 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]
------
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{title}}</title>
  <link rel="stylesheet" href="{{base}}/styles.css">
</head>
<body>
    <div class="card-list">
        {{#each cards}}
            <div class="card">
                <div class="card-title">{{NAME}}</div>
                {{#if DESC }}<div class="card-desc">{{DESC}}</div>{{/if}}
            </div>
        {{/each}}
    </div>
</body>
</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]
------
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{title}}</title>
  <link rel="stylesheet" href="{{base}}/styles.css">
</head>
<body>
    <div class="card-list">
        {{#each cards}}
            {{>card card=.}}
        {{/each}}
    </div>
</body>
</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]
------
<div class="card">
    <div class="card-title">{{NAME}}</div>
    {{#if DESC }}<div class="card-desc">{{DESC}}</div>{{/if}}
</div>
------

==== Layout in cardmaker.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]
------
cardmaker build -l pro
------

or

[source]
------
cardmaker build --layout pro
------

To watch : 

[source]
------
cardmaker watch -l pro
------

or 

[source]
------
cardmaker watch --layout pro
------

=== License

Licensed under the link:LICENSE[MIT]