ThunderBoard documentation

10 Apr Edited
#1

ThunderBoard is in beta stages, and something may not work as intended. Please open a new thread describing your issue thoroughly and help me to improve the plugin!


Installation


KEYCAP 1 upload all the files to your root folder making sure every file is in the correct folder. Proceed to install & activate the plugin from the plugins page in your Admin Control Panel.

KEYCAP 2 open your theme's templates. An editor such as FASTyle 2.2 is recommended.

KEYCAP 3 open your header template and look for:

<div id="container">
Replace it with:

<div id="container" data-thunderboard-context>
You are now all set up to enjoy quick page loads!

Set up preview templates


With ThunderBoard you can define custom preview templates displayed before browsing towards a particular page, which is loaded in the background using AJAX. For example, you can display a spinner within a certain page section while keeping the rest of the page as-is. Since there isn't a precise and fixed element to hook onto, ThunderBoard dynamically detects the target container to replace with each template.

KEYCAP 1 Open ThunderBoard's module within the Configuration panel in your ACP and create a new template.

The page field accepts a list of pages to bind the template to. When users browse to these pages, the template is displayed before displaying the actual content. This field accepts partial URLs. For example, if you add member.php, ThunderBoard binds the template to every URL containing "member.php". If you want to use the same template for different URLs, separate them with a coma.

Use the special "global" keyword to bind your template to all pages.

WARNING SIGN MyBB SEO URLs are not supported at present times.

KEYCAP 2 open your theme's templates and add the data-thunderboard attribute to every container element you want to replace with ThunderBoard's template you have just created in step KEYCAP 1 For example, if you create a ThunderBoard template valid for "usercp.php", you will want to keep the header, the footer and the sidebar visible, and only change the actual UCP content. To so do, you will need to add the data-thunderboard attribute to every <tr> element after the {$usercpnav} variable in all usercp* templates.

If you want you can add the data-thunderboard attribute to the <div id="content"> element found in the header template, which will apply to all pages at once.

You can add as many data-thunderboard attributes as you like even in the same page. ThunderBoard will replace just the deepest DOM element it can find. This is useful if you want to have a "general" anchor in the header while having a specific, "deeper" anchor for pages such as the UserCP.


The following information is outdated. It should still apply, but I'd advise you to take it with a grain of salt until it is updated.


ThunderBoard can grab data from the current page and adds it to the preview template before displaying it. In order to do so, ThunderBoard must find an anchor, an element which contains the data to gather, starting from the element you have clicked on and traversing up to the body. For example:

@Shade <-- this is the target element
This post <-- this is the anchor
This post's avatar <-- this is the data point ThunderBoard will gather

You must define an anchor and a data point in your theme's regular templates. The data point will be then available to be referenced into ThunderBoard's templates.

An anchor is defined using the data-tb-item attribute. When you click on a link, ThunderBoard will traverse up in the document until an element with the data-tb-item is found.

<div class="example" data-tb-item>CONTENT</div
A data point is defined using the data-tb-FIELD attribute. Replace FIELD with an unique string which you will use to reference to it.

<div class="example" data-tb-item>
    <
img src="{$avatar}data-tb-avatar />
</
div
You can now reference the avatar data point in ThunderBoard's template using the following syntax:

{avatar}
// ThunderBoard will look for elements with the data-tb-avatar attribute within the anchor element 
To improve extensibility, ThunderBoard can recognize CSS ids and classes as well. All you have to do is add the corresponding prefix before the syntax (# for ids, . for classes):

<div>{.avatar}</div>
// ThunderBoard will look for elements with the "avatar" class or ID or with the data-tb-avatar attribute within the anchor element. If found, it will replace {.avatar} with its content, typically <img src="avatar.png" /> 
Classes and ids extend the syntax, so data-tb-FIELD will be available as well. This gives you many customization chances.

If ThunderBoard finds the target FIELD within the anchor element, it collects its inner HTML and replaces the {FIELD} defined into the target template. Sometimes you may want to grab a specific attribute instead of the inner HTML. You can define it by using a slightly modified syntax:

<img src="{.avatar|src}" />
// ThunderBoard will look for elements with the "avatar" class or with the data-tb-avatar attribute within the anchor element, AND will grab the src attribute if found, replacing {.avatar|src} with it 
So to summarize:

In a regular template, eg.: forumdisplay_thread:

<div class="thread" data-tb-item>
    <
img src="{$useravatar}class="avatar" />
    <
span class="title"><a href="{$thread['url']}">{$thread['title']}</a></span>
</
div
In ThunderBoard's template with showthread.php as page field:

<div class="post">
    <
img src="{.avatar|src}" class="avatar" />
    <
span class="fakeText"></span>
</
div
When you click on a thread's title, ThunderBoard will traverse up to the first data-tb-item element (.thread in the example above), then traverse down inside it to find for elements with the "avatar" class or with the "data-tb-avatar" attribute. The former is found; a custom attribute is defined (src), so it grabs the src attribute (the user's avatar image) and replaces {.avatar|src} with it. The final result will be:

<div class="post">
    <
img src="http://avatarurl.png" class="avatar" />
    <
span class="fakeText"></span>
</
div
ThunderBoard will now use this template as a preview.

You can define multiple FIELDs and reference them as you may like. You can define multiple anchors as well; just bare in mind that ThunderBoard stops once it finds the very first parent with the data-tb-item attribute.

Custom script reloading


ThunderBoard loads JavaScript resources upon the very first visit; as you browse to another page, some functionalities might break because MyBB standard JS lacks idempotence (in other words, it's not designed for single-page AJAX navigation).

ThunderBoard can reload custom scripts to ensure they can work continuously when navigating through pages.

Most scripts do not need to be reloaded entirely; they usually contain a function which is used to initialize the script's content. To reload a custom script you will need to gather:
  • The file: for example, jscripts/thread.js;
  • The function to be executed: for example, Thread.init()

Custom rules can be defined using the apposite tool in ThunderBoard's module. Separate multiple rules with a newline. The syntax is very straightforward:
  • FILE=FUNCTION

Using the aforementioned examples:
  • thread=Thread.init()

Here are some recommendations:
  1. the jscripts prefix and the file extensions are NOT needed, but can be added anyway. If you add the jscripts/ folder prefix or the .js extension, ThunderBoard will not be able to confirm if the function is present in your file; however, it will execute the function anyway whenever a file matching your pattern is found in a page. For example, jscripts/thread.js=Thread.init() would also work;
  2. the function MUST be on one line. Semicolons are also stripped out from them upon submitting;
  3. ThunderBoard performs an automated check to see if the function is present within the corresponding file. If it can't find it, it will output a notice; this does not mean your function will not work, as it's executed anyway. Some scripts may contain an object-oriented structure, like:
    Foo {
       
    bar: function() {
       }

    If you want to execute bar(), your function would look like Foo.bar(). However, this pattern cannot be find anywhere in the code above, and ThunderBoard would mark this as "not found"; the function is still calling bar() correctly though.

I acknowledge this might be a little bit difficult for those who don't know a word of web developing. If you are unsure, feel free to open a new support thread.
iDeath98 likes this post