@eit6609/storyteller 1.0.6 → 2.0.0

package/.eslintrc

@@ -79,7 +79,7 @@ rules:
   # Custom rules
   no-warning-comments: 1
   max-depth: [1, 3]
-  max-statements: [1, 15]
+  max-statements: [1, 20]
   camelcase: [2, {properties: "never"}]
   brace-style: [2, "1tbs", {allowSingleLine: true}]
   block-scoped-var: 2

package/README.md

@@ -116,12 +116,13 @@ The methods `reset()` and `move()` are modifiers, and will be used with the `got
 
 The pages of the ebook are generated by a set of XHTML templates, one for every location of the game.
 
-After many experiments with the most popular templating engines for Node.js, I have chosen
-[Pug](https://pugjs.org/api/getting-started.html) because it gives you enough freedom to call JavaScript code inside
-the template. This is vital, but many engines (the very popular [Handlebars](https://handlebarsjs.com) among others)
-make the call of methods on a class instance a nightmare.
+After many experiments with the most popular templating engines for Node.js, I have chosen:
 
-Of course [EJS](https://ejs.co) gives you *complete* freedom, but I prefer higher level engines like Pug.
+* [EJS](https://ejs.co)
+* [Pug](https://pugjs.org/api/getting-started.html)
+
+There are many engines (the very popular [Handlebars](https://handlebarsjs.com) among others) but most
+of them make the call of methods on a class instance a nightmare.
 
 I have added **experimental** support for markdown templating by means of my
 [Markdown Templates](https://github.com/eit6609/markdown-templates) engine.
@@ -129,7 +130,7 @@ I have added **experimental** support for markdown templating by means of my
 Let's see an example of template:
 
 ```pug
-doctype strict
+doctype 1.1
 html(xmlns='http://www.w3.org/1999/xhtml', xml:lang='en')
     head
         link(href="style-epub.css", rel="stylesheet", type="text/css")
@@ -144,7 +145,7 @@ html(xmlns='http://www.w3.org/1999/xhtml', xml:lang='en')
             li Peg 2: #{state.pegs[1]}
             li Peg 3: #{state.pegs[2]}
         if state.isFinished()
-            h1 YOU’VE WON!
+            h1 YOU WIN!
             br
             p.first Want to #[a(href=goto((state) => state.reset())) play again]?
         else
@@ -235,16 +236,26 @@ These are the supported options:
   as input for the [ePUB creator](https://github.com/eit6609/epub-creator), so you can put in this directory any extra
   file (images, stylesheets) that you need in the ePUB.
 * `metadata`, object, required, the options for the ePUB creator, with these properties:
-    * `title`, string, optional, default `untitled`: the title of the ePUB
+    * `title`, string, optional, default `Untitled`: the title of the ePUB
     * `author`, string, optional, default no author: the author of the ePUB
     * `language`, string, optional, default `en`: the language of the ePUB
+    * `description`, string, optional, default no description: the description of the ePUB
+    * `isbn`, string, optional, default no ISBN: the ISBN of the ePUB
+    * `tags`, array of string, optional, default no subjects: the subjects of the ePUB
     * `cover`, string, optional, default no cover: a path relative to `outputDir` of an image that will become the cover
       of the ePUB
     * `filename`, string, required: the path of the generated ePUB
-* `markdown`, boolean, optional, default `false`: if `false` the template engine is Pug, otherwise it is Markdown
-  Templates
+* `templateEngine`, string, required, possible values: `ejs`, `pug`, `mt`: the template engine used to
+   generate the pages.
 * `debug`, boolean, optional, default `false`: if `true` the `debug()` function called in the templates will return the
    page key, otherwise the empty string.
+* `contentBefore`, array, optional, default `[]`. Extra, static pages to insert into the generated ePUB before the
+   generated pages. The items of the array are objects with these properties:
+  * `fileName`, string, required. The path of the file relative to `outputDir`.
+  * `tocLabel`, string, optional. The label to use in the TOC. Leave it out if you don't want the page to be added to
+    the TOC.
+* `contentAfter`, array, optional, default `[]`. Extra, static pages to insert into the generated ePUB after the
+  generated pages. The items of the array are the same as `contentBefore`.
 
 #### `generate(initialTemplateName: string, initialState: object): promise`
 
@@ -280,15 +291,15 @@ The parameters are:
 
 * `templateName`: the path of a template file, without the extension, relative to the `templatesDir`. It defaults to
 the current template's name.
-* `action`: a function that receives a state as its only parameter and modifies it. It should return a falsy
+* `action`: a function that receives a clone of the state as its only parameter and modifies it. It should return a falsy
 value unless it wants to replace the received state with a new one: in this case it should return the new state. This is
 handy for complex games because it enables you to move through independent stages of the game. More about this later,
 in the *Tips & Tricks* section.
 
 With this function you actually trigger the generation of the pages, because, if the requested page does not exist,
-the generator creates an empty page and enqueues it for the build, that is the execution of the template with the state
-of the page. That execution could find and execute some `goto()` that could trigger the creation of new pages, and so
-on.
+the generator creates an empty page and enqueues it for the build, that is the execution of the template with a clone
+of the state of the page. That execution could find and execute some `goto()` that could trigger the creation of new
+pages, and so on.
 
 ## Examples
 
@@ -306,14 +317,19 @@ But if you are lazy you can just download the generated ePUBs.
 
 A classic puzzle!
 
-There are two scripts:
+There are three scripts:
 
-* `main-xhtml.js`, that uses the Pug (.pug) templates
+* `main-pug.js`, that uses the Pug (.pug) templates
+* `main-ejs.js`, that uses the EJS (.html) templates
 * `main-markdown.js`, that uses the experimental Markdown Templates (.md) templates
 
 The generated ePUBs should be the same.
 
-You can download the generated ePUB [here](examples/goat-cabbage-wolf/code/goat-cabbage-wolf-xhtml.epub).
+You can download the generated ePUBs here:
+
+* [pug](examples/goat-cabbage-wolf/code/goat-cabbage-wolf-pug.epub)
+* [ejs](examples/goat-cabbage-wolf/code/goat-cabbage-wolf-ejs.epub)
+* [markdown](examples/goat-cabbage-wolf/code/goat-cabbage-wolf-markdown.epub)
 
 ### Desert Traversal
 
@@ -358,7 +374,7 @@ class Safe {
     }
 
     choose (digit) {
-        this.ok = String(digit) === this.combination.charAt(this.index);
+        this.ok = this.ok && String(digit) === this.combination.charAt(this.index);
         this.index++;
     }
 
@@ -375,7 +391,7 @@ class Safe {
 with this template:
 
 ```pug
-doctype strict
+doctype 1.1
 html(xmlns='http://www.w3.org/1999/xhtml', xml:lang='en')
     head
         link(href="style-epub.css", rel="stylesheet", type="text/css")
@@ -384,9 +400,9 @@ html(xmlns='http://www.w3.org/1999/xhtml', xml:lang='en')
         h3 Open the Safe
         hr
         if state.isRight()
-            h1 YOU’VE WON!
+            h1 YOU WIN!
         else if state.isWrong()
-            h1 YOU’VE LOST!
+            h1 YOU LOSE!
         else
             p.first Choose digit ##{state.index + 1}:
             ul

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@eit6609/storyteller",
-    "version": "1.0.6",
+    "version": "2.0.0",
     "description": "An interactive ebooks generator",
     "keywords": [
         "epub",
@@ -38,11 +38,12 @@
         "jasmine-spec-reporter": "^3.2.0"
     },
     "dependencies": {
-        "@eit6609/epub-creator": "^1.0.0",
+        "@eit6609/epub-creator": "^1.1.0",
         "@eit6609/markdown-templates": "^1.0.0",
         "@hapi/joi": "^16.1.7",
+        "ejs": "^3.1.8",
         "lodash": "^4.17.10",
-        "marked": "^0.8.2",
-        "pug": "^2.0.4"
+        "marked": "^4.0.10",
+        "pug": "^3.0.1"
     }
 }

package/src/generator.js

@@ -2,12 +2,17 @@
 
 const
     { inspect } = require('util'),
-    { filter, forEach, get, isUndefined, pick, sortBy } = require('lodash'),
+    { filter, forEach, get, isUndefined, omit, sortBy } = require('lodash'),
     Joi = require('@hapi/joi'),
     { EPUBCreator } = require('@eit6609/epub-creator'),
     Page = require('./page.js'),
     Template = require('./template.js');
 
+const extraContentSchema = Joi.object({
+    fileName: Joi.string().required(),
+    tocLabel: Joi.string()
+});
+
 const optionsSchema = Joi.object({
     templatesDir: Joi.string().required(),
     outputDir: Joi.string().required(),
@@ -15,16 +20,22 @@ const optionsSchema = Joi.object({
         title: Joi.string(),
         author: Joi.string(),
         language: Joi.string(),
+        isbn: Joi.string(),
+        description: Joi.string(),
+        tags: Joi.array().items(Joi.string()),
         cover: Joi.string(),
-        filename: Joi.string().required()
+        filename: Joi.string().required(),
     }).required(),
-    markdown: Joi.boolean(),
+    advancedMetadata: Joi.array(),
+    templateEngine: Joi.string().valid('pug', 'ejs', 'mt').required(),
     debug: Joi.boolean(),
+    contentBefore: Joi.array().items(extraContentSchema),
+    contentAfter: Joi.array().items(extraContentSchema),
     factory: Joi.object({
         createPage: Joi.function(),
         createTemplate: Joi.function(),
         createEPUBCreator: Joi.function()
-    })
+    }),
 });
 
 class Generator {
@@ -34,8 +45,11 @@ class Generator {
         this.templatesDir = options.templatesDir;
         this.outputDir = options.outputDir;
         this.metadata = options.metadata;
-        this.markdown = options.markdown === true;
+        this.advancedMetadata = options.advancedMetadata || [];
+        this.templateEngine = options.templateEngine;
         this.debug = options.debug === true;
+        this.contentBefore = options.contentBefore || [];
+        this.contentAfter = options.contentAfter || [];
         this.createPage = get(options, 'factory.createPage', (...params) => new Page(...params));
         this.createTemplate = get(options, 'factory.createTemplate', (...params) => new Template(...params));
         this.createEPUBCreator = get(options, 'factory.createEPUBCreator', (...params) => new EPUBCreator(...params));
@@ -86,24 +100,41 @@ class Generator {
 
     createEpub () {
         const spine = [];
+        const toc = [];
+        if (this.metadata.cover) {
+            toc.push([{ label: 'Cover', href: 'cover-page.html' }]);
+        }
+        for (const { tocLabel, fileName } of this.contentBefore) {
+            spine.push(fileName);
+            if (tocLabel) {
+                toc.push([{ label: tocLabel, href: fileName }]);
+            }
+        }
         for (let i = 0; i < this.numberOfPages; i++) {
             spine.push(`${Page.numberFormat.format(i)}.html`);
         }
-        const toc = [[{ label: 'Start', href: `${Page.numberFormat.format(0)}.html` }]];
+        toc.push([{ label: 'Game Start', href: `${Page.numberFormat.format(0)}.html` }]);
+        for (const { tocLabel, fileName } of this.contentAfter) {
+            spine.push(fileName);
+            if (tocLabel) {
+                toc.push([{ label: tocLabel, href: fileName }]);
+            }
+        }
         const { cover } = this.metadata;
         const epubCreator = this.createEPUBCreator({
             contentDir: this.outputDir,
             spine,
             toc,
             cover,
-            simpleMetadata: pick(this.metadata, ['author', 'title', 'language'])
+            simpleMetadata: omit(this.metadata, ['cover', 'filename']),
+            metadata: this.advancedMetadata,
         });
         return epubCreator.create(this.metadata.filename);
     }
 
     printReport () {
         function makeFilterByTemplateName (templateName) {
-            return (pageKey) => pageKey.substring(0, pageKey.lastIndexOf('/')) === templateName;
+            return (pageKey) => pageKey.substring(0, pageKey.indexOf('{') - 1) === templateName;
         }
 
         const templateNames = sortBy(Array.from(this.templates.keys()));

package/src/page.js

@@ -15,7 +15,7 @@ const {
         toPairsIn
     } = require('lodash'),
     fs = require('fs'),
-    marked = require('marked');
+    { marked } = require('marked');
 
 function wrapBody (body) {
     return `<?xml version="1.0" encoding="utf-8"?>
@@ -98,8 +98,8 @@ class Page {
     followLink (templateName, action) {
         templateName = templateName || this.template.name;
         let { state } = this;
+        state = cloneDeep(state);
         if (action) {
-            state = cloneDeep(state);
             const newState = action.call(null, state);
             // this way the action can create a new state and initialize a new stage of the game:
             if (newState) {
@@ -110,7 +110,7 @@ class Page {
     }
 
     build () {
-        if (this.builder.markdown) {
+        if (this.builder.templateEngine === 'mt') {
             const text = this.template.build(this);
             const markedOptions = {
                 smartypants: true,

package/src/template.js

@@ -1,28 +1,73 @@
 'use strict';
 
 const
+    fs = require('fs'),
     pug = require('pug'),
-    mt = require('@eit6609/markdown-templates');
+    mt = require('@eit6609/markdown-templates'),
+    ejs = require('ejs');
+
+class Pug {
+    getFileExtension () {
+        return 'pug';
+    }
+
+    loadTemplate (fileName, { mockPug }) {
+        return (mockPug || pug).compileFile(fileName, { pretty: true });
+    }
+}
+
+class EJS {
+    getFileExtension () {
+        return 'ejs';
+    }
+
+    loadTemplate (fileName, { mockEJS }) {
+        if (mockEJS) {
+            return mockEJS.compile(mockEJS.getFileContent());
+        }
+        const src = fs.readFileSync(fileName, 'utf-8');
+        return ejs.compile(src);
+    }
+}
+
+class MarkdownTemplates {
+    getFileExtension () {
+        return 'md';
+    }
+
+    loadTemplate (fileName, { mockMT }) {
+        return (mockMT || mt).compileFile(fileName);
+    }
+}
 
 class Template {
 
-    constructor (name, builder, mockMT, mockPug) {
+    static createTemplateEngineAdapter (name) {
+        switch (name) {
+            case 'pug':
+                return new Pug();
+            case 'ejs':
+                return new EJS();
+            case 'mt':
+                return new MarkdownTemplates();
+            default:
+                throw new Error(`Unknown template engine: "${name}"`);
+        }
+    }
+
+    constructor (name, builder, { mockMT, mockPug, mockEJS } = {}) {
         this.name = name;
         this.templatesDir = builder.templatesDir;
-        this.markdown = builder.markdown;
-        this.load(mockMT, mockPug);
+        this.adapter = Template.createTemplateEngineAdapter(builder.templateEngine || 'ejs');
+        this.load({ mockMT, mockPug, mockEJS });
     }
 
-    load (mockMT, mockPug) {
-        if (this.markdown) {
-            this.template = (mockMT || mt).compileFile(this.getFileName());
-        } else {
-            this.template = (mockPug || pug).compileFile(this.getFileName(), { pretty: true });
-        }
+    load ({ mockMT, mockPug, mockEJS }) {
+        this.template = this.adapter.loadTemplate(this.getFileName(), { mockMT, mockPug, mockEJS });
     }
 
     getFileName () {
-        return `${this.templatesDir}/${this.name}.${this.markdown ? 'md' : 'pug'}`;
+        return `${this.templatesDir}/${this.name}.${this.adapter.getFileExtension()}`;
     }
 
     build (page) {
@@ -31,5 +76,4 @@ class Template {
 
 }
 
-
 module.exports = Template;