Merge pull request #289 from ZogStriP/bbcode-component

added more tests & documentation to the BBCode component

app/assets/javascripts/discourse/components/bbcode.js

@@ -45,9 +45,7 @@ Discourse.BBCode = {
         "spoiler": function(_, content) { return "<span style='background-color: #000'>" + content + "</span>"; }
       },
       withArgs: {
-        "size": function(_, size, content) {
+        "size": function(_, size, content) { return "<span style=\"font-size: " + size + "px\">" + content + "</span>"; }
-          return "<span style=\"font-size: " + size + "px\">" + content + "</span>";
-        }
       }
     },
 
@@ -62,49 +60,62 @@ Discourse.BBCode = {
         }
       },
       withArgs: {
-        "size": function(_, size, content) {
+        "size": function(_, size, content) { return "<span class=\"bbcode-size-" + size + "\">" + content + "</span>"; }
-          return "<span class=\"bbcode-size-" + size + "\">" + content + "</span>";
-        }
       }
     }
   },
 
-  // Apply a particular set of replacers
+  /**
-  apply: function(text, environment) {
+    Apply a particular set of replacers
-    var replacer;
-    replacer = Discourse.BBCode.parsedReplacers()[environment];
 
+    @method apply
+    @param {String} text The text we want to format
+    @param {String} environment The environment in which this
+  **/
+  apply: function(text, environment) {
+    var replacer = Discourse.BBCode.parsedReplacers()[environment];
+    // apply all available replacers
     replacer.forEach(function(r) {
       text = text.replace(r.regexp, r.fn);
     });
     return text;
   },
 
+  /**
+    Lazy parse replacers
+
+    @property parsedReplacers
+  **/
   parsedReplacers: function() {
-    var result;
     if (this.parsed) return this.parsed;
 
-    result = {};
+    var result = {};
+
     Object.keys(Discourse.BBCode.replacers, function(name, rules) {
-      var parsed;
+
-      parsed = result[name] = [];
+      var parsed = result[name] = [];
+
       Object.keys(Object.merge(Discourse.BBCode.replacers.base.withoutArgs, rules.withoutArgs), function(tag, val) {
-        return parsed.push({
+        parsed.push({ regexp: new RegExp("\\[" + tag + "\\]([\\s\\S]*?)\\[\\/" + tag + "\\]", "igm"), fn: val });
-          regexp: new RegExp("\\[" + tag + "\\]([\\s\\S]*?)\\[\\/" + tag + "\\]", "igm"),
-          fn: val
-        });
-      });
-      return Object.keys(Object.merge(Discourse.BBCode.replacers.base.withArgs, rules.withArgs), function(tag, val) {
-        return parsed.push({
-          regexp: new RegExp("\\[" + tag + "=?(.+?)\\]([\\s\\S]*?)\\[\\/" + tag + "\\]", "igm"),
-          fn: val
       });
+
+      Object.keys(Object.merge(Discourse.BBCode.replacers.base.withArgs, rules.withArgs), function(tag, val) {
+        parsed.push({ regexp: new RegExp("\\[" + tag + "=?(.+?)\\]([\\s\\S]*?)\\[\\/" + tag + "\\]", "igm"), fn: val });
       });
+
     });
+
     this.parsed = result;
     return this.parsed;
   },
 
+  /**
+    Build the BBCode quote around the selected text
+
+    @method buildQuoteBBCode
+    @param {Discourse.Post} post The post we are quoting
+    @param {String} contents The text selected
+  **/
   buildQuoteBBCode: function(post, contents) {
     var contents_hashed, result, sansQuotes, stripped, stripped_hashed, tmp;
     if (!contents) contents = "";
@@ -112,6 +123,8 @@ Discourse.BBCode = {
     sansQuotes = contents.replace(this.QUOTE_REGEXP, '').trim();
     if (sansQuotes.length === 0) return "";
 
+    result = "[quote=\"" + (post.get('username')) + ", post:" + (post.get('post_number')) + ", topic:" + (post.get('topic_id'));
+
     /* Strip the HTML from cooked */
     tmp = document.createElement('div');
     tmp.innerHTML = post.get('cooked');
@@ -124,29 +137,30 @@ Discourse.BBCode = {
     */
     stripped_hashed = stripped.replace(/[^a-zA-Z0-9]/g, '');
     contents_hashed = contents.replace(/[^a-zA-Z0-9]/g, '');
-    result = "[quote=\"" + (post.get('username')) + ", post:" + (post.get('post_number')) + ", topic:" + (post.get('topic_id'));
 
     /* If the quote is the full message, attribute it as such */
-    if (stripped_hashed === contents_hashed) {
+    if (stripped_hashed === contents_hashed) result += ", full:true";
-      result += ", full:true";
-    }
     result += "\"]\n" + sansQuotes + "\n[/quote]\n\n";
+
     return result;
   },
 
-  formatQuote: function(text, opts) {
+  /**
+    Replace quotes with appropriate markup
 
-    /* Replace quotes with appropriate markup */
+    @method formatQuote
+    @param {String} text The text inside which we want to replace quotes
+    @param {Object} opts Rendering options
+  **/
+  formatQuote: function(text, opts) {
     var args, matches, params, paramsSplit, paramsString, templateName, username;
     while (matches = this.QUOTE_REGEXP.exec(text)) {
-      paramsString = matches[1];
+      paramsString = matches[1].replace(/\"/g, '');
-      paramsString = paramsString.replace(/\"/g, '');
       paramsSplit = paramsString.split(/\, */);
       params = [];
       paramsSplit.each(function(p, i) {
-        var assignment;
         if (i > 0) {
-          assignment = p.split(':');
+          var assignment = p.split(':');
           if (assignment[0] && assignment[1]) {
             return params.push({
               key: assignment[0],
@@ -157,17 +171,17 @@ Discourse.BBCode = {
       });
       username = paramsSplit[0];
 
-      /* Arguments for formatting */
+      // Arguments for formatting
       args = {
         username: username,
         params: params,
         quote: matches[2].trim(),
         avatarImg: opts.lookupAvatar ? opts.lookupAvatar(username) : void 0
       };
+      // Name of the template
       templateName = 'quote';
-      if (opts && opts.environment) {
+      if (opts && opts.environment) templateName = "quote_" + opts.environment;
-        templateName = "quote_" + opts.environment;
+      // Apply the template
-      }
       text = text.replace(matches[0], "</p>" + HANDLEBARS_TEMPLATES[templateName](args) + "<p>");
     }
     return text;
@@ -181,12 +195,10 @@ Discourse.BBCode = {
     @param {Object} opts Rendering options
   **/
   format: function(text, opts) {
-    var environment;
+    var environment = opts && opts.environment ? opts.environment : 'default';
-    if (opts && opts.environment) environment = opts.environment;
+    // Apply replacers for basic tags
-    if (!environment) environment = 'default';
-
     text = Discourse.BBCode.apply(text, environment);
-    // Add quotes
+    // Format
     text = Discourse.BBCode.formatQuote(text, opts);
     return text;
   }

spec/javascripts/bbcode_spec.js

@@ -1,6 +1,7 @@
 /*global waitsFor:true expect:true describe:true beforeEach:true it:true */
 
 describe("Discourse.BBCode", function() {
+
   var format = Discourse.BBCode.format;
 
   describe('default replacer', function() {
@@ -105,35 +106,6 @@ describe("Discourse.BBCode", function() {
 
     });
 
-    describe("quoting", function() {
-
-      it("can quote", function() {
-        expect(format("[quote=\"eviltrout, post:1, topic:1\"]abc[/quote]",
-                      { lookupAvatar: false })
-                     ).toBe("</p><aside class='quote' data-post=\"1\" data-topic=\"1\" >\n  <div class='title'>\n    " +
-                            "<div class='quote-controls'></div>\n  \n  eviltrout\n  said:\n  </div>\n  <blockquote>abc</blockquote>\n</aside>\n<p>");
-      });
-
-      it("can nest quotes", function() {
-        expect(format("[quote=\"eviltrout, post:1, topic:1\"]abc[quote=\"eviltrout, post:2, topic:2\"]nested[/quote][/quote]",
-                      { lookupAvatar: false })
-                     ).toBe("</p><aside class='quote' data-post=\"1\" data-topic=\"1\" >\n  <div class='title'>\n    <div " +
-                            "class='quote-controls'></div>\n  \n  eviltrout\n  said:\n  </div>\n  <blockquote>abc</p><aside " +
-                            "class='quote' data-post=\"2\" data-topic=\"2\" >\n  <div class='title'>\n    <div class='quote-" +
-                            "controls'></div>\n  \n  eviltrout\n  said:\n  </div>\n  <blockquote>nested</blockquote>\n</aside>\n<p></blockquote>\n</aside>\n<p>");
-      });
-
-      it("can handle more than one quote", function() {
-        expect(format("before[quote=\"eviltrout, post:1, topic:1\"]first[/quote]middle[quote=\"eviltrout, post:2, topic:2\"]second[/quote]after",
-                      { lookupAvatar: false })
-                     ).toBe("before</p><aside class='quote' data-post=\"1\" data-topic=\"1\" >\n  <div class='title'>\n    <div class='quote-cont" +
-                            "rols'></div>\n  \n  eviltrout\n  said:\n  </div>\n  <blockquote>first</blockquote>\n</aside>\n<p>middle</p><aside cla" +
-                            "ss='quote' data-post=\"2\" data-topic=\"2\" >\n  <div class='title'>\n    <div class='quote-controls'></div>\n  \n  " +
-                            "eviltrout\n  said:\n  </div>\n  <blockquote>second</blockquote>\n</aside>\n<p>after");
-      });
-
-    });
-
   });
 
   describe('email environment', function() {
@@ -228,4 +200,65 @@ describe("Discourse.BBCode", function() {
 
   });
 
+  describe("quoting", function() {
+
+    it("can quote", function() {
+      expect(format("[quote=\"eviltrout, post:1, topic:1\"]abc[/quote]", { lookupAvatar: false })).
+        toBe("</p><aside class='quote' data-post=\"1\" data-topic=\"1\" >\n  <div class='title'>\n    " +
+             "<div class='quote-controls'></div>\n  \n  eviltrout\n  said:\n  </div>\n  <blockquote>abc</blockquote>\n</aside>\n<p>");
+    });
+
+    it("can nest quotes", function() {
+      expect(format("[quote=\"eviltrout, post:1, topic:1\"]abc[quote=\"eviltrout, post:2, topic:2\"]nested[/quote][/quote]", { lookupAvatar: false })).
+        toBe("</p><aside class='quote' data-post=\"1\" data-topic=\"1\" >\n  <div class='title'>\n    <div " +
+             "class='quote-controls'></div>\n  \n  eviltrout\n  said:\n  </div>\n  <blockquote>abc</p><aside " +
+             "class='quote' data-post=\"2\" data-topic=\"2\" >\n  <div class='title'>\n    <div class='quote-" +
+             "controls'></div>\n  \n  eviltrout\n  said:\n  </div>\n  <blockquote>nested</blockquote>\n</aside>\n<p></blockquote>\n</aside>\n<p>");
+    });
+
+    it("can handle more than one quote", function() {
+      expect(format("before[quote=\"eviltrout, post:1, topic:1\"]first[/quote]middle[quote=\"eviltrout, post:2, topic:2\"]second[/quote]after", { lookupAvatar: false })).
+        toBe("before</p><aside class='quote' data-post=\"1\" data-topic=\"1\" >\n  <div class='title'>\n    <div class='quote-cont" +
+             "rols'></div>\n  \n  eviltrout\n  said:\n  </div>\n  <blockquote>first</blockquote>\n</aside>\n<p>middle</p><aside cla" +
+             "ss='quote' data-post=\"2\" data-topic=\"2\" >\n  <div class='title'>\n    <div class='quote-controls'></div>\n  \n  " +
+             "eviltrout\n  said:\n  </div>\n  <blockquote>second</blockquote>\n</aside>\n<p>after");
+    });
+
+    describe("buildQuoteBBCode", function() {
+
+      var build = Discourse.BBCode.buildQuoteBBCode;
+
+      var post = Discourse.Post.create({
+        cooked: "<p><b>lorem</b> ipsum</p>",
+        username: "eviltrout",
+        post_number: 1,
+        topic_id: 2,
+      });
+
+      it("returns an empty string when contents is undefined", function() {
+        expect(build(post, undefined)).toBe("");
+        expect(build(post, null)).toBe("");
+        expect(build(post, "")).toBe("");
+      });
+
+      it("returns the quoted contents", function() {
+        expect(build(post, "lorem")).toBe("[quote=\"eviltrout, post:1, topic:2\"]\nlorem\n[/quote]\n\n");
+      });
+
+      it("trims white spaces before & after the quoted contents", function() {
+        expect(build(post, " lorem ")).toBe("[quote=\"eviltrout, post:1, topic:2\"]\nlorem\n[/quote]\n\n");
+      });
+
+      it("marks quotes as full when the quote is the full message", function() {
+        expect(build(post, "lorem ipsum")).toBe("[quote=\"eviltrout, post:1, topic:2, full:true\"]\nlorem ipsum\n[/quote]\n\n");
+      });
+
+      it("keeps BBCode formatting", function() {
+        expect(build(post, "**lorem** ipsum")).toBe("[quote=\"eviltrout, post:1, topic:2, full:true\"]\n**lorem** ipsum\n[/quote]\n\n");
+      });
+
+    });
+
+  });
+
 });