Merge PR #49: Compiler enhancements

- Compiler refactored so inserting HTML at a <!--{specialComment}--> is DRY and error-checked.
- Added documentation on the back button in the Doc template
- Project's template file can be declared {examples}/[template].html to use a built-in template.
- Fixed example project files to reference the basic template properly.

README.md

@@ -9,7 +9,7 @@ Once Node.js is installed, open a command line and install Fractive:
 Fractive is now globally available on the command line. Type:
 
 	fractive help
-	
+
 ...to launch the user guide and start learning how to use Fractive!
 
 ## Contributing

doc/build/index.html

@@ -1185,7 +1185,8 @@ <h1>Scripting</h1>
 
             <div id="__topNav">
                 <p>
-                    <a class="__topNav" href="javascript:;" onclick="Core.GotoPreviousSection();"><i class="fa fa-arrow-circle-left" aria-hidden="true"></i> Back</a>
+                    <!-- Don't use the default back button. Use this: -->
+                    <a class="__topNav" href="javascript:;" onclick="Core.GotoPreviousSection();"><i class="fa fa-arrow-circle-left" aria-hidden="true"></i>Back</a>
                 </p>
             </div>
             <div id="__currentSection"></div>

doc/fractive.json

@@ -40,6 +40,5 @@
             "prepend": false
         }
     },
-    "includeBackButton": true,
-    "backButtonHTML": "Back"
-}
+    "includeBackButton": false
+}

doc/template.html

@@ -191,7 +191,8 @@
 				<!--{story}-->
 				<div id="__topNav">
 					<p>
-						<a class="__topNav" href="javascript:;" onclick="Core.GotoPreviousSection();"><i class="fa fa-arrow-circle-left" aria-hidden="true"></i> Back</a>
+						<!-- Don't use the default back button. Use this: -->
+						<a class="__topNav" href="javascript:;" onclick="Core.GotoPreviousSection();"><i class="fa fa-arrow-circle-left" aria-hidden="true"></i>Back</a>
 					</p>
 				</div>
 				<div id="__currentSection"></div>

examples/basic/fractive.json

@@ -1,11 +1,11 @@
 {
 	"title": "basic",
-	"template": "../../templates/basic.html",
+	"template": "{examples}/basic.html",
 	"linkTooltips": true,
 	"linkTags": {
 		"external": {
 			"html": "&nbsp;<i class=\"fa fa-external-link\" aria-hidden=\"true\"></i>"
 		}
 	},
-	"backButtonHTML": "<i class=\"fa fa-arrow-left\" aria-hidden=\"true\"></i> Back"
+	"backButtonHtml": "<i class=\"fa fa-arrow-left\" aria-hidden=\"true\"></i> Back"
 }

examples/callbacks/fractive.json

@@ -1,4 +1,4 @@
 {
     "title": "callbacks",
-	"template": "../../templates/basic.html"
+	"template": "{examples}/basic.html"
 }

examples/macros/fractive.json

@@ -4,7 +4,7 @@
 		{ "alias": "TestAdjective", "replaceWith": "awesome" },
 		{ "alias": "red", "replaceWith": "<span style='color:#ff8888'>", "end": "</span>" }
 	],
-	"template": "../../templates/basic.html",
+	"template": "{examples}/basic.html",
 	"linkTooltips": true,
 	"linkTags": {
 		"external": {

examples/tags/fractive.json

@@ -1,6 +1,6 @@
 {
 	"title": "basic",
-	"template": "../../templates/basic.html",
+	"template": "{examples}/basic.html",
 	"linkTooltips": true,
 	"linkTags": {
 		"external": {

src/Compiler.ts

@@ -74,7 +74,7 @@ export let ProjectDefaults : FractiveProject = {
 		}
 	},
 	includeBackButton: true,
-	backButtonHTML: "Back"
+	backButtonHtml: "Back"
 };
 import * as globby from "globby";
 
@@ -103,6 +103,31 @@ export namespace Compiler
 	let nextInlineID : number = 0;
 	let sectionCount : number = 0;
 
+	/**
+	 * Inserts the given html snippet into the template HTML at EVERY point where
+	 * a specially formatted comment appears: <!--{mark}-->
+	 * @param snippet The html to insert
+	 * @param template The template in which to insert
+	 * @param mark The mark at which to insert Html
+	 * @param requiired Whether the mark is required or not. Default: true
+	 * @return The complete resulting html file contents
+	 */
+	function InsertHtmlAtMark(snippet : string, template : string, mark : string, required : boolean = true) : string
+	{
+		// The mark has to be placed inside an HTML comment formatted like so:
+		let markComment : string = `<!--{${mark}}-->`;
+
+		// Throw an error if the mark doesn't exist
+		if (template.indexOf(markComment) === -1 && required)
+		{
+			console.log(`Template file must contain mark: ${markComment}`);
+			process.exit(1);
+		}
+
+		// Insert the snippet
+		return template.split(markComment).join(snippet);
+	}
+
 	/**
 	 * Inserts the given story text (html) and scripts (javascript) into an html template, and returns the complete resulting html file contents
 	 * @param html The html-formatted story text to insert into the template
@@ -111,7 +136,19 @@ export namespace Compiler
 	 */
 	function ApplyTemplate(basePath : string, html : string, javascript : string) : string
 	{
-		let templatePath : string = path.resolve(basePath, project.template);
+		let templatePath : string = "";
+
+		// If project.template begins with the macro '{examples}/', resolve relative
+		// to the templates folder of the Fractive installation, not the build path
+		if (project.template.indexOf("{examples}") == 0) {
+			templatePath = project.template.replace("{examples}", `${__dirname}/../templates`);
+		}
+		// Otherwise, the path is relative to the story's root directory
+		else {
+			templatePath = path.resolve(basePath, project.template);
+		}
+
+		// Ensure that the template file exists
 		if(!fs.existsSync(templatePath))
 		{
 			console.log(`Template file not found: "${templatePath}"`);
@@ -136,16 +173,15 @@ export namespace Compiler
 		// Insert all bundled scripts, including Core.js
 		scriptSection += `${javascript}`;
 		scriptSection += "</script>";
-		template = template.split("<!--{script}-->").join(scriptSection);
+		template = InsertHtmlAtMark(scriptSection, template, 'script');
 
 		// Insert html-formatted story text
-		template = template.split("<!--{story}-->").join(html);
+		template = InsertHtmlAtMark(html, template, 'story');
 
-		// Insert the back button if specified to do so
-		if(project.includeBackButton)
-		{
-			let backButtonHTML = '<a href="javascript:Core.GotoPreviousSection();">' + project.backButtonHTML + '</a>';
-			template = template.split("<!--{backButton}-->").join(backButtonHTML);
+		// Insert the back button everywhere the template defines <!--{backButton}-->
+		if (project.includeBackButton) {
+			let backButtonHtml = '<a href="javascript:Core.GotoPreviousSection();">' + project.backButtonHtml + '</a>';
+			template = InsertHtmlAtMark(backButtonHtml, template, 'backButton');
 		}
 
 		// Auto-start at the "Start" section

src/ProjectSchema.json

@@ -84,7 +84,7 @@
 			}
 		},
 		"includeBackButton": { "type": "boolean", "description": "Whether to include a back button in your story." },
-		"backButtonHTML": { "type": "string", "description": "Raw HTML inserted in the place where the back button is defined to be." }
+		"backButtonHtml": { "type": "string", "description": "Raw HTML inserted in the place where the back button is defined to be." }
 	},
 	"additionalProperties": false
 }