LGBB - A JS Forumotion BB Parser.
(all boards)

Today I present you with a new LG Special, and what this means is, this is not just a once off tutorial but rather something that I will keep going back to and adding more and improving. This one will not have different versions, but rather will simply keep growing as a library of BBcodes for your FM boards.

I must state an important note first:
This WILL NOT add new buttons to your editors. The script will only parse the new BB codes, and replace them with their respective HTML. If you wish to add buttons to your editors for the supplied BB codes in LGBB, then you should seek out another tutorial about adding buttons. Feel free to make a thread here, or actually I think there may already be a tutorial for that on FMQuery, can't remember.

Okay so 3 parts to this thread:
1. i'll tell you how to install it
2. I am going to outline and explain the new BB codes that come with it.
3. I will explain how to use it and add your own BBcodes with great functionality.

1, Installation
Installation almost coudn't be simpler. All that is involved is adding the javascript to a JS file and specifying your forum version. Go to ACP > Modules > Javascript Management. Make a new code and put this in it, this is the LGBB core script which runs the parsing and things:

Code:

[codetitle=Javascript]
var LGBB_copyright = "LGBB, a Javascript BB Code parser for Forumotion Boards. Copyright by AvacWeb 2011-2012. All Rights Reserved. Use of this script is not allowed without this entire copyright notice in place. No Distribution without authors consent.";
var LGBB={bbcodes:{div:{tags:{open:/\[div(?:=['"]?(\w+)['"]?)?]/,close:/\[\/div]/},reps:{open:'<div class="$1">',close:"</div>"},test:!1},span:{tags:{open:/\[span(?:=['"]?(\w+)['"]?)?]/,close:/\[\/span]/},reps:{open:'<span class="$1">',close:"</span>"},test:!1},header:{tags:{open:/\[h([1-6])]/,close:/\[\/h([1-6])]/},reps:{open:"<h$1>",close:"</h$1>"},test:!1},codename:{tags:{open:/Code:([^\[]+)\<code\>(?:\<br\>)?\[codetitle=["']?(\w+)["']?]/},reps:{open:"$2:$1<code>"}}},add_bbcode:function(a){LGBB.bbcodes[a.tags.open]=a},finishers:[],afterposts:[],after_finished:function(a){LGBB.finishers.push(a)},after_post:function(a){LGBB.afterposts.push(a)},content_classnames:{phpbb3:"content",invision:"post-entry",punbb:"entry-content",phpbb2:"postbody"},version:"phpbb3",parse_posts:!0,parse:function(a,e){for(var g in LGBB.bbcodes){var b=LGBB.bbcodes[g];if(!b.test||b.test.test(a)){if(b.tags.close)for(var d=RegExp("string"==typeof b.tags.open?"\\["+b.tags.open+"]":b.tags.open.source,"g"),c=RegExp("string"==typeof b.tags.close?"\\[\\/"+b.tags.close+"]":b.tags.close.source,"g");d.test(a)&&c.test(a);){c.lastIndex<d.lastIndex&&(c.lastIndex=d.lastIndex);var f=a.substring(d.lastIndex,c.lastIndex),h=a.substring(0,d.lastIndex),i=a.substring(h.length+f.length);if(!b.before||b.before.call(e,f.replace(c,"")))h=h.replace(d,b.reps.open),f=f.replace(c,b.reps.close),a=h+f+i}else d=RegExp("string"==typeof b.tags.open?"\\["+b.tags.open+"]":b.tags.open.source,'g'),a=a.replace(d,b.reps.open);b.after&&b.after.call(e,e)}}return a}};$(function(){if(LGBB.parse_posts){for(var a=jQuery(".post"),e=a.length,g=0,b=LGBB.content_classnames[LGBB.version];g<e;g++){var d=a[g],c=jQuery("."+b,d);if(c.length&&(c=c[0],content=c.innerHTML,content=LGBB.parse(content,d),c.innerHTML=content,LGBB.afterposts.length))for(var c=0,f=LGBB.afterposts.length;c<f;c++)LGBB.afterposts[c].call(d,d)}if(LGBB.finishers.length){a=0;for(e=LGBB.finishers.length;a<e;a++)LGBB.finishers[a]()}}});


Do not put it in a jQuery function, by that I mean do not wrap it anywhere inbetween $(function(){ and }); or you risk breaking it completely

Okay, your not fully installed yet, because lastly, LGBB needs to know your forum version.
If you added it in your header via templates, then in a Javascript file you'll need to specify your forum version. If you added it in a Javascript file, then to specify your version, you just need to put the line of code coming up directly below the last chunk of code you put in.

Specify your version like so:

Code:

LGBB.version = 'invision';

(Those using phpbb3, don't need to do anything, LGBB will assume phpbb3 by default , the only values you should specify are either 'invision', 'punbb', 'phpbb3', or 'phpbb2' anything else will break it.)
Make sure you spell your version correctly or it will not work. No capitals, no spaces.

And thats it. Your good to go.

---

2. The Built-In BB Codes
Here is a list explaining the BBcodes that come with LGBB and how to use them. Over time I will be posting more BBcodes throughout this thread, so check through this thread too.

Note: I have to include spaces within the tags so they are not parsed in this post. But tags do not have space after the opening '[' or closing ']'.

- The div tag.
This tag allows you to put divs with a classname in your post without having HTML enabled. The tag is [ div="classname" ] (but with no spaces, I have to put spaces or it will be parsed here), and the closing tag is [/div]. This will be replaced with . You can specify 'classname' as any classname you want of course.
This tag can be very useful for you, because it can allow you to make complex html structures in your posts, and style them in the CSS. You can even make a very nice staff table maybe, or you can use class's already defined and styled in the CSS.

- The span tag
This tag is exactly the same as the DIV tag above, but for the span HTML element instead.

- The codetitle tag
This tag is just a nice tiny addition. This tag allows you to add a title to your code blocks.
After the opening code tag, use this tag to define the title of the codeblock, like so:
(again, no spaces)

Code:


[code][ codetitle=javascript ]
the code bla bla bla
[/code]


Which will result in this:
[Only admins are allowed to see this image]
The codetitle tag DOES NOT need a closing tag.

- The Header Tag
If you know anything about HTML you'll know of the header tags, im talking about

... and so on. This header tag simply allows you to use these header tags inside posts, just like this: [h1] or [h2], up to [h6]. These tags must be closed, and they will be swapped with the respective header tag in HTML, so [ h1 ]Header[/ h1 ] will be swapped for

Header

Thats it for the built-in ones I'm afraid, but check the topic below for any new ones provided as simple add-ons, or maybe ones other people have provided.

---

3. Using the API and adding your own BBcodes
LGBB provides a simple way of adding your own BBcodes. Its easy for those who don't know javascript, and for those that do know a little bit, it has some methods of making things a little more advanced too.

The function to use for adding new tags is 'LGBB.add_bbcode()', and it takes one parameter, and object literal containing the information needed. I'm going to explain it in this post, and then as a reply to this topic, I will provide some usable example such as a 'noguest' tag, and a new spoiler.

First of all, adding the BBcode into the LGBB store. Read the notes in the Javascript:

Code:

[panda=js]
//call the LGBB.add_bbcode function any time after the script in a JS file
LGBB.add_bbcode({
        //specify the opening and closing tags. Do not include [ or / symbols.
   tags: {
      open: 'example', //these can be a simple string or regExp if you know regex.
      close: 'example' //you can make codes without a close tag. Like the codetitle tag.
   },   
   reps: {
      open: '<div class="example">', //the content that the open tag will be replaced with.
      close: '</div>'  //the content the close tag will be replaced with.
   },      
   after: function(post) {
                //you can specify a function to execute after this tag has been parsed. This is optional
      //it takes one parameter, the current post it is parsing.
                jQuery(post).addClass('examplePost');
   },      
   before: function(content) {
                //you can also specify a function to run before this certain tag is parsed.
                //it takes one parameter the content in between the two tags.
                //this acts a filter function. Return false if you do not want this tag to be parsed.
      if(content == 'example please') alert('EXAMPLE!');
                return true;
   }   
});


And thats it for adding a BBcode. Now I'm just gonna go through that a bit, explaining each bit in more detail.
tags - First off are the tags. You must specify an open tag, but a close tag is not necessarily needed if you want it to be a BBcode with no close tag, such as the codetitle tag above. The tags can be a simple string, and it must not include the '[' and slashes, but simply be the word of the tag. So if you put 'hello' the tag is then [hello] and the close tag will be [/hello]. The tags can also be a regular expression if you know how to use Javascript regular expressions. Adding regex modifiers is not necessary.

reps - These are the replacements. These are what the tags will be replaced with, you can have this as anything you want, but if you use HTML, make sure the HTML is valid. If you used regex in the tags, you can use back referencing in the reps strings.

before - You can specify a function to be executed before parsing the tag, this allows you to do things such as check the content, check the post to see if the user is allowed to use the tag. (In a later update you'll be able to modify the content) The function receieves one parameter the content inbetween the opening and closing tag, the context is the current post (that means that 'this' refers to the current post that is being parsed). This function can be used to prevent parsing at certain points, you should return false if you do not wish for the parsing of that tag to continue, or true if its okay. Here's a real life example of using this function; say you make a nice staff box by adding a new BBcode [staffbox], and you don't want people who aren't staff to use it, then this function you could check the post, to see if it is a staff member, if it isn't return false, so the staffbox isn't parsed. You don't have to specify this function, you can leave it out, in which case parsing will always take place of the code.

after - You can also specify a function to run after that tag has been parsed. The function receives one parameter, the current post being parsed, the keyword 'this' also refers to the current post. You can use this function for performing anything on the post as a result of the parsing. Here's a quick example, say you add a new bbcode [username], which will display the user who is viewing the pages name (same as the {USERNAME*} variable), this function could be used for checking the navigation bar and getting the user name from the logout link, then adding it into this tag.

If this stuff doesn't completely make sense just yet, it may make sense after you look at the usable add-on's I'll be providing.

Last of all are a few functions you can add to run at other times.

You can add a function which will be executed everytime a post has been finished parsing. The function receives one parameter and 'this' refers to the current post. Example:

Code:


LGBB.after_post(function() {
  if($(this).find('.staffpost')[0]) {
      this.backgroundColor = '#fff';
  }
});


And lastly, you can add functions to run after LGBB has completely finished parsing all posts:

Code:


LGBB.after_finished(function() {
  alert('All posts have been parsed!');
});


And the last thing to know for making add-on's, and extra's is that the function which performs the parsing can be called on any text on any element. You may need this at points, you can also use it for parsing things like widgets and stuff. The function takes one parameter, the text to parse, and an optional second parameter, the element which it is parsing. It can be important passing an element into it, for stuff like the after and before functions. The function returns the parsed text, which you can then insert into an element or anything.

Code:

LGBB.parse(text_to_parse, element_being_parsed);

Why you you need to perform this parse? well a real example, is when you use the preview feature on the AvacWeb Editor, your content gets parsed.

Now for those of you interested in adding your own BBcodes, or developing BBcodes for others to use, check out my addon's in the replies below.
You can copy and paste the example above as a sort of template.

---

The Limitations and things to note
- The tags that need a closing tag will only work with a closing tag, without one they will not be parsed.
- These tags are not immune in code blocks, and so WILL still be parsed inside code blocks. Sorry, no can do here.
- Please feel free to offer any improvements or suggestions for new BB tags below.
- It would be great if you have a good idea for a new BBcode and successfully implement it on your board, to consider sharing it with others below. I hope people can see the potential this can bring to your boards.

And Enjoy