Support overriding the built-in render function

... and therefore drop explicit support for rendering with Handlebars templates.

Author: cmrd-senya

Changelog.md

@@ -1,3 +1,8 @@
+## Next release
+
+- Drop explicit support for Handlebars
+- Instead support overriding of a built-in render function
+
 ## 0.5.0
 
 - Don't depend on lodash anymore (#6)

README.md

@@ -1,5 +1,5 @@
 # markdown-it-html5-embed
-This is a plugin for markdown-it which adds support for embedding audio/video in the HTML5 way, by using <video>/<audio> tags.
+This is a plugin for markdown-it which adds support for embedding audio/video in the HTML5 way, by using `<video>`/`<audio>` tags.
 
 ## Install
 
@@ -153,22 +153,48 @@ Here is a description of the content: test link
 </video>
 ```
 
-### Handlebars templates
+### Alternative render functions
 
 Options:
 ```js
-templateName: "media-embed_tpl"
+renderFn: function(properties, attributes) {/* ... */}
 ```
 
-If you want to render media embed using Handlebars template, you can set `templateName` option and the plugin will try to find
-the template using global `HandlebarsTemplates` array and render using this template.    
+By default the plugin renders media with just plain html media tags. However you may want to customize media rendering appropriate for your front-end framework or approach.
+
+You can do this by defining a custom rendering function.
+
+For example, here is a function you can use to render a media embed with Handlebars:
+
+```js
+function handleBarsRenderFn(properties, attributes) {
+    return HandlebarsTemplates[this]({
+    media_type: properties.mediaType,
+    attributes: attributes,
+    mimetype: properties.mimeType,
+    source_url: properties.url,
+    title: properties.title,
+    fallback: properties.fallback,
+    needs_cover: properties.mediaType === "video"
+  });
+}
+```
 
 You can access the descriptive content (e.g., "test link" above) via the
 `{{title}}` variable. It will be set to "Untitled video" or "Untitled audio"
 if no title was set. You can access the fallback text ("Your browser does not
 support ...")  via the `{{fallback}}` variable. See below for how to
 customize/translate the text.
 
+Then you can just set this function as a `renderFn` option on the plugin initialization:
+
+```js
+// ... options setting code ...
+renderFn: handleBarsRenderFn.bind("templateName"),
+```
+
+More on render function arguments see at the [`renderFn`](#renderFn) option description.
+
 ## Options reference
 
 #### attributes
@@ -232,13 +258,27 @@ The argument is a result of regexp match, and has a structure similar to that on
 
 Default: `undefined`, allow everything.
 
-#### templateName
+#### renderFn
+
+Function. Override the built-in render function. The function accepts exactly 2 arguments.
+
+```js
+function customRenderFn(properties, attributes) { /* ... */ }
+```
+
+`properties` is an `Object` which contains properties of a detected and parsed media reference. `properties` `Object` contains following keys:
 
-String. If the plugin is used in a Rails asset pipeline along with the handlebars_assets gem, then you can use a Handlebars template to control the output of the plugin. This option specifies the name of the template to use, which will be picked from the HandlebarsTemplates array.
+key|type|meaning
+-|-
+fallback|String|Fallback text for the case when the client (e.g. browser) doesn't support HTML5 `<audio>`/`<video>`
+mediaType|String|`"video"` or `"audio"`
+mimeType|String|Media mime type resolved by a URL ending (media file extension)
+title|String|Title for the media (which could be optionally provided in the markup)
+url|String|Media URL
 
-If HandlebarsTemplates is undefined, this option is ignored.
+`attributes` is the attributes passed from the plugin options, see [`attributes`](#attributes) option description.
 
-Default: `undefined`, don't use Handlebars.
+A custom render function must return a `String` value which contains HTML for embedding at the appropriate place.
 
 #### useImageSyntax
 

lib/index.js

@@ -15,7 +15,7 @@ var Mimoza = require('mimoza');
 // you have to provide a translation function via options.translateFn.
 //
 // The "untitled video" / "untitled audio" messages are only relevant to usage
-// inside Handlebars templates, where you can access the title between [] as
+// inside alternative render functions, where you can access the title between [] as
 // {{title}}, and this text is used if no title is provided.
 var messages = {
   en: {
@@ -69,7 +69,7 @@ function parseToken(tokens, idx, env) {
   }
 
   if (parsed.mediaType !== null) {
-    // For use as titles in handlebars templates, we store the description
+    // For use as titles in alternative render functions, we store the description
     // in parsed.title. For use as fallback text, we store it in parsed.fallback
     // alongside the standard fallback text.
     parsed.fallback = translate({
@@ -99,35 +99,14 @@ function isAllowedMimeType(parsed, options) {
     (!options.isAllowedMimeType || options.isAllowedMimeType([parsed.mimeType, parsed.mediaType]));
 }
 
-function renderMediaEmbed(parsed, options) {
-  var attributes = options.attributes[parsed.mediaType];
-  var useHandlebars = false;
+function renderMediaEmbed(parsed, mediaAttributes) {
+  var attributes = mediaAttributes[parsed.mediaType];
 
-  if (options.templateName) {
-    if (typeof HandlebarsTemplates === "undefined") {
-      console.log("handlebars_assets is not on the assets pipeline; fall back to the usual mode");
-    } else {
-      useHandlebars = true;
-    }
-  }
-
-  if (useHandlebars) {
-    return HandlebarsTemplates[options.templateName]({
-      media_type: parsed.mediaType,
-      attributes: attributes,
-      mimetype: parsed.mimeType,
-      source_url: parsed.url,
-      title: parsed.title,
-      fallback: parsed.fallback,
-      needs_cover: parsed.mediaType === "video"
-    });
-  } else {
-    return ['<' + parsed.mediaType + ' ' + attributes + '>',
-      '<source type="' + parsed.mimeType + '" src="' + parsed.url + '"></source>',
-      parsed.fallback,
-      '</' + parsed.mediaType + '>'
-    ].join('\n');
-  }
+  return ['<' + parsed.mediaType + ' ' + attributes + '>',
+    '<source type="' + parsed.mimeType + '" src="' + parsed.url + '"></source>',
+    parsed.fallback,
+    '</' + parsed.mediaType + '>'
+  ].join('\n');
 }
 
 function html5EmbedRenderer(tokens, idx, options, env, renderer, defaultRender) {
@@ -141,7 +120,7 @@ function html5EmbedRenderer(tokens, idx, options, env, renderer, defaultRender)
     clearTokens(tokens, idx + 1);
   }
 
-  return renderMediaEmbed(parsed, options.html5embed);
+  return renderMediaEmbed(parsed, options.html5embed.attributes);
 }
 
 function forEachLinkOpen(state, action) {
@@ -244,7 +223,7 @@ module.exports = function html5_embed_plugin(md, options) {
           return;
         }
 
-        result += renderMediaEmbed(parsed, options);
+        result += renderMediaEmbed(parsed, options.attributes);
       });
       if (result.length) {
         result += "\n";
@@ -290,4 +269,8 @@ module.exports = function html5_embed_plugin(md, options) {
   translate = typeof options.translateFn == 'function' ?
     options.translateFn.bind(options.messages) :
     translate.bind(options.messages);
+
+  if (typeof options.renderFn == 'function') {
+    renderMediaEmbed = options.renderFn;
+  }
 };

test/test.js

@@ -3,6 +3,11 @@
 var path = require('path');
 var generate = require('markdown-it-testgen');
 
+function clearBindings() {
+  // Don't re-use cached function with old bindings
+  delete require.cache[require.resolve('../lib')];
+}
+
 // For testing custom messages and translations
 var customMessages = {
   en: {
@@ -58,15 +63,28 @@ describe('markdown-it-html5-embed mime type filtering', function() {
 });
 
 describe('markdown-it-html5-embed with handlebars', function() {
-  before(function() {
-    var Handlebars = require("handlebars");
-    global.HandlebarsTemplates = { "template": Handlebars.compile("<h1>{{title}}</h1><div class=\"body\"><{{media_type}} {{attributes}}><source type=\"{{mimetype}}\" src=\"{{source_url}}\"/></{{media_type}}></div>") };
-  });
+  clearBindings();
+
+  var Handlebars = require("handlebars");
+  global.HandlebarsTemplates = { "template": Handlebars.compile("<h1>{{title}}</h1><div class=\"body\"><{{media_type}} {{attributes}}><source type=\"{{mimetype}}\" src=\"{{source_url}}\"/></{{media_type}}></div>") };
+
+  function handleBarsRenderFn(parsed, mediaAttributes) {
+    var attributes = mediaAttributes[parsed.mediaType];
+      return HandlebarsTemplates[this]({
+      media_type: parsed.mediaType,
+      attributes: attributes,
+      mimetype: parsed.mimeType,
+      source_url: parsed.url,
+      title: parsed.title,
+      fallback: parsed.fallback,
+      needs_cover: parsed.mediaType === "video"
+    });
+  }
 
   var option = {
     html5embed: {
       useLinkSyntax: true,
-      templateName: "template",
+      renderFn: handleBarsRenderFn.bind("template"),
       attributes: {
         "video": "",
         "audio": ""
@@ -77,6 +95,8 @@ describe('markdown-it-html5-embed with handlebars', function() {
   var md = require('markdown-it')().use(require('../lib'), option);
 
   generate(path.join(__dirname, 'fixtures/with-handlebars.txt'), md);
+
+  clearBindings();
 });
 
 describe("embedding with [[html5embed]] clause", function() {
@@ -115,8 +135,8 @@ describe('markdown-it-html5-embed with image syntax + custom messages', function
       messages: customMessages
     }
   };
-  // Don't re-use cached function with old bindings
-  delete require.cache[require.resolve('../lib')];
+
+  clearBindings();
 
   var md = require('markdown-it')().use(require('../lib'), option);
   generate(path.join(__dirname, 'fixtures/image-syntax-custom-messages.txt'), md);
@@ -145,8 +165,7 @@ describe('markdown-it-html5-embed with image syntax + custom translation fn', fu
     }
   };
 
-  // Don't re-use cached function with old bindings
-  delete require.cache[require.resolve('../lib')];
+  clearBindings();
 
   var md = require('markdown-it')().use(require('../lib'), option);
   var env = { language: 'de' };