Cardery

democratizing the means of game design

Make cards with HTML, CSS, JS, and CSV.

GitHub repo · Download · License (MIT)

Cardery requires Chrome 55+ or Firefox 52+.
See guide for more notes on compatibility.

Cardery.js is a script that uses dom-to-image to render PNG images from card data in CSV format and card template written in HTML, CSS, and JavaScript. Work in your favorite text editor or spreadsheet editor, while refreshing your browser for instant WYSIWYG feedback.

A complete example is shown below. Click here to run the example project.

The above example project is public domain. Use it freely, with or without attribution, even for commercial purposes.

Intro & Demo | Reference Guide

Cardery works best with Chrome, but it does work in Firefox. There are four considerations:

Cardery uses async functions, which are supported as of Chrome 55 and Firefox 52.
Chrome forbids scripts from making requests to file:///. To use Cardery with Chrome, you must serve your files from http://localhost/. See this tutorial. If you're on Windows like I am, Microsoft's IIS may or may not be easier to install than Apache; here's how it went for me.
Like web pages, the rendered cards will look different depending on your browser, your operating system, and their settings. If you run the demo, your Shifty Elf might not look identical to mine at the top of this page, but I tried to write the demo template so that it would look reasonable in most any environment. But one thing I couldn't figure out with Firefox is subpixel antialiasing, which looks good on-screen, but doesn't make sense on an image you want to print. In my experience, Chrome automagically stops using subpixel antialiasing when you use dom-to-image to generate images. On the other hand, I couldn't find a way to make Firefox not use it, short of disabling it at the OS level. After all, it is an OS feature; it's called "ClearType" in Windows. I don't know how Chrome is smart enough not to do it when I don't want it to, but that's why I said Cardery works best with Chrome for me. Your mileage may vary, especially on a different OS.
dom-to-image runs faster in Chrome than in Firefox.

The chassis of a Cardery project is a HTML file that contains or links everything else, such as the above demo.html. Notice that it doesn't have a <body>; Cardery.js will generate the page when you load the file in your browser. The card template is written in JS and CSS, and in your script you need to invoke Cardery with the name(s) of your CSV files and with a specifically-formatted JavaScript object representing your template, which I call the "template object".

Cardery's functions and the template object are described below.

Cardery(csvOrList, template) is how you invoke Cardery, once Cardery.js has been loaded.

   csvOrList is the path to your CSV, or an array of paths. The top row of each CSV must be your column names.

   template is an object whose properties will be made available in the data objects Cardery will create to represent each card. template's property names share the same namespace as your column names, so make sure the names don't conflict. Some special properties are as follows:
   template.main must be a function that constructs a HTML representation of the card in Cardery.mainDiv, which is a jQuery object, and for convenience is passed as the first and only argument to main. In main and in any method it calls, the pronoun this will contain the card data, with the column names as keys. For example, main might refer to this.cardname if you have a column named cardname. main can be async, and must return the jQuery object or DOM object of the root element of the card.
   this.csv and this.i will be added to the card data by Cardery, where csv is the path of the CSV it's from, and i is its index within its CSV, which starts at 0 for the first card in each CSV.

   template.options may optionally be an object specifying certain options.
   template.options.scale (default: 1) multiplies the dimensions of the generated image. Internally, Cardery uses CSS scale().
   template.options.ppi (default: 96) is an option I recommend using instead of scale. In CSS, 1in equals 96px. ppi lets you represent actual inches using CSS inches while specifying the actual pixels-per-inch you want. (Most print-on-demand services ask for 300ppi.) Internally, scale is multiplied by ppi/96.
   You can also specify options for dom-to-image in template.options.

Cardery.waitImgLoad(img) waits for image(s) to load, useful if you want to measure some element's height or width.
img is optionally a HTMLImageElement. If img is not specified, waitImgLoad waits for all images on the page.

Cardery.showError(obj) displays the contents of obj in red at the top of the page.

Cardery.parsed[csv] contains the full result object generated when Cardery calls Papa Parse.

When you load your HTML file in your browser, a sample of up to six card images will be previewed. "Save all" generates all images in order to save them in a ZIP; "Save these N" saves the previewed images without waiting to generate more. "Toggle zoom" attempts to resize the preview images to their natural pixel resolution; you should verify whether it works in your browser.

Cardery uses localStorage to try to keep track of which cards were recently edited in your CSV(s) in order to preview those first. "Search" lets you preview a different sample; you can enclose your search string in slashes to have it interpreted as a regular expression. To reprioritize a card on next refresh as though you had edited it, prefix a search with "\pin ".

If you don't have a favorite text editor, try Notepad++.
To save all the versions of your files, use version control software, such as git (tutorial).

Questions, suggestions, rants, raves? Creations to share? Tweet me!

Cardery can be downloaded at https://github.com/Xom/Cardery/releases