CardKit 2
A simple, powerful and fully configurable image editor for web browers and servers. Optional UI included.
51 | CardKit 2 has three main parts:
52 |
53 | CardKit: The core library, that manages and maintains the configuration object which defines the structure and options of a cardCardKitDOM: A DOM renderer, that takes an instance of CardKit and renders either a standalone image, or a pre-packaged UI for editing the imageCardKitServer: A server renderer, that allows you to take an instance of CardKit and render it into an image on a Node.js server
57 | Additionally, a base class allows you to create your own renderers. See more in the Custom Renderers section.
58 | Installation
$ npm install cardkit --save
59 | Running locally
To run a sample UI locally, run: $ npm start
60 | You can optionally pass a port like so: $ npm start -- --port=8080
61 | Configuring
See the Wiki for all the available options for your configuration.
62 | Usage
Browser with Webpack / Browserify usage
// Load CardKit and CardKit DOM
63 | const CardKit = require('cardkit');
64 | const CardKitDOM = require('cardkit/dom');
65 |
66 | // Base configuration object - see `./examples/configurations` for examples
67 | var configuration = {};
68 |
69 | // Optional themes object - see `./examples/configurations` for examples
70 | var themes = {};
71 |
72 | // Optional layouts object - see `./examples/configurations` for examples
73 | var layouts = {};
74 |
75 | // Initialise CardKit
76 | var cardkit = new CardKit(configuration, {
77 | themes: themes,
78 | layouts: layouts
79 | });
80 |
81 | // Initialise Renderer
82 | var renderer = new CardKitDOM(cardkit);
83 |
84 | // To render the card only (with optional theme / layout overrides)
85 | renderer.renderCard('card', {
86 | theme: 'Alt',
87 | layout: 'Square'
88 | });
89 |
90 | // OR To render the editing UI
91 | renderer.renderUI('card');
Browser with <script> tag usage
<!-- Load in React from a CDN (or similar) -->
92 | <script src="https://cdnjs.cloudflare.com/ajax/libs/react/15.3.2/react.min.js"></script>
93 | <script src="https://cdnjs.cloudflare.com/ajax/libs/react/15.3.2/react-dom.min.js"></script>
94 |
95 | <!-- Load in the CardKit and CardKitDOM Libraries -->
96 | <script type="text/javascript" src="url/to/cardkit.js"></script>
97 | <script type="text/javascript" src="url/to/cardkit-dom.js"></script>
98 |
99 | <!-- Your container element to render into -->
100 | <div id="card"></div>
101 |
102 | <script type="text/javascript">
103 | // Base configuration object - see `./examples/configurations` for examples
104 | var configuration = {};
105 |
106 | // Optional themes object - see `./examples/configurations` for examples
107 | var themes = {};
108 |
109 | // Optional layouts object - see `./examples/configurations` for examples
110 | var layouts = {};
111 |
112 | // Initialise CardKit
113 | var cardkit = new CardKit(configuration, {
114 | themes: themes,
115 | layouts: layouts
116 | });
117 |
118 | // Initialise Renderer
119 | var renderer = new CardKitDOM(cardkit);
120 |
121 | // To render the card only (with optional theme / layout overrides)
122 | renderer.renderCard('card', {
123 | theme: 'Alt',
124 | layout: 'Square'
125 | });
126 |
127 | // OR To render the editing UI
128 | renderer.renderUI('card');
129 | </script>
Server usage
// Require CardKit and CardKitServer
130 | const CardKit = require('cardkit');
131 | const CardKitServer = require('cardkit/server');
132 |
133 | // Base configuration object - see `./examples/configurations` for examples
134 | const configuration = {};
135 |
136 | // Initialise CardKit
137 | const cardkit = new CardKit(configuration);
138 |
139 | // Initialise Renderer
140 | var renderer = new CardKitServer(cardkit);
141 |
142 | // Render to image
143 | renderer.renderToImage(2)
144 | .then((image) => {
145 | // Do what you want with the image here...
146 | console.log('<img src="data:image/png;base64,' + image + '" />');
147 | process.exit();
148 | })
149 | .catch((e) => {
150 | console.log('[ERR]', e);
151 | process.exit();
152 | });
APIs
CardKit
new CardKit(configuration, options)
153 | Initialisation. Pass in a required configuration object, and optional themes, templates and layouts
154 |
155 | cardkit.updateConfiguration(configuration, options, rerender)
156 | Updates the configuration in your instance of CardKit. Can optionally rerender with a flag if previously rendered (supported in CardKitDOM).
157 |
158 | cardkit.computeConfiguration(options)
159 | Computes a configuaration object, optionally accepting a named template, theme and layout. These get merged into the base configuration and returned.
160 |
161 | CardKitDOM
new CardKitDOM(cardkit)
162 | Accepts an instance of CardKit and initialises the renderer
163 |
164 | cardkit.renderUI(id, overrides)
165 | Renders the include user interface to the specified DOM element
166 |
167 | cardkit.renderCard(id)
168 | Renders just the card in it's SVG form to the specified DOM element
169 |
170 | cardkit.rerender()
171 | Will re-render the existing UI or card
172 |
173 | cardkit.download(scale, element)
174 | Downloads the image to your local machine. Accepts a scale (default=2), and an element to grab from. If not provided it will fall back to the existing card being rendererd (if renderCard() was used).
175 |
176 | CardKitServer
new CardKitDOM(cardkit)
177 | Accepts an instance of CardKit and initialises the renderer
178 |
179 | cardkit.renderToString()
180 | Renders the card to a HTML string (e.g. <svg...></svg>)
181 |
182 | cardkit.renderToImage(scale)
183 | Renders the card to an image returning a Promise containing the image as a base64 string
184 |
185 | Custom Renderers
A base class CardKitRenderer allows you to create your own renderer for CardKit. For example, CardKitDOM currently uses SVG to create the card, and React to render the UI. You may, however, wish to render your card using HTML canvas, or build a UI using Vue.js. Creating a custom renderer is a good way to achieve this. Below is a brief example of how you might achieve this:
186 | class CardKitCanvas extends CardKitRenderer {
187 |
188 | renderCard () {
189 | // Canvas-specific code here
190 | }
191 |
192 | rerender () { // A method that `CardKit` calls if the base configuration object is updated
193 | // Handle an update to the base configuration, e.g. you may want to re-render the canvas element here
194 | }
195 |
196 | yourCustomMethod () {
197 | // You can implement any custom methods here, for example you may wish to expose or manipulate the <canvas> element for other users to take advantage of
198 | }
199 |
200 | }
201 |
202 | const cardkit = new CardKit(configuration);
203 |
204 | const renderer = new CardKitCanvas(cardkit);
205 |
206 | renderer.yourCustomMethod();
Custom Fonts
CardKit allows you to load in custom fonts for use on your cards, see the Wiki for details. These need to be encoded into base64 format. If you wish to use a Google font, you can use the googlefontcss64 library to generate a base64 version of any Google font.
207 | Upgrading from v1.x
Upgrading from v1.x to v2 should be a fairly straightforward process if you haven't made any major modifications to the v1.x user interface. Your configuration object from v1.x should be compatible with v2 with a few minor tweaks. Specific variations are available in the Wiki.
208 | Tests
To trigger the test suite, run $ npm run test
209 | 
');
26 | process.exit();
27 | })
28 | .catch((e) => {
29 | console.log('[ERR]', e);
30 | process.exit();
31 | });
32 |
--------------------------------------------------------------------------------
/favicon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/times/cardkit/f74d73c31c1c6414cdde5c5b031b287843202efd/favicon.png
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "cardkit",
3 | "version": "2.0.6",
4 | "description": "A simple, powerful and fully configurable image editor for web browsers and servers. Optional UI included.",
5 | "main": "cardkit.js",
6 | "homepage": "https://times.github.io/cardkit",
7 | "bugs": {
8 | "url": "https://github.com/times/cardkit/issues"
9 | },
10 | "repository": {
11 | "type": "git",
12 | "url": "https://github.com/times/cardkit.git"
13 | },
14 | "scripts": {
15 | "test": "./node_modules/.bin/istanbul cover --dir test/coverage ./node_modules/.bin/_mocha -- --compilers js:babel-core/register --require ignore-styles",
16 | "jsdoc": "./node_modules/.bin/jsdoc -c ./jsdoc.config.json -d ./docs/code -t ./node_modules/minami --verbose -R ./README.md",
17 | "demo": "./node_modules/webpack/bin/webpack.js --env=dist-docs",
18 | "docs": "npm run jsdoc; npm run demo",
19 | "start": "./node_modules/webpack-dev-server/bin/webpack-dev-server.js -d --content-base ./src --hot --open",
20 | "dist": "npm run build",
21 | "build": "echo \"[NOTICE] This task will build ALL CardKit versions\"; echo \"[LOG] Building DOM library\"; npm run build-dom; echo \"[LOG] Building server library\"; npm run build-server; echo \"[LOG] Building core library\"; npm run build-core; echo \"[LOG] Building DOM
19 |