Content module tutorial

Folder

Like with Link Modules you must create a subfolder for your module in the module folder. Your folder name will be your module name, which must match in all other places where your module name is needed.

/module/your_module_name

JavaScript file.

Just like with Link Modules, you must also create a JavaScript file inside this folder with the name your_module_name.js. For example, let us create a module to display cats in the contentArea:

/module/cat/cat.js

Functions

There are certain standard functions all content modules are expected to support, and they must follow the BlockPress naming convention. These are:

Menu Item Function

Just like with Link Modules, Content modules must support the your_module_name_menuitem function. Unlike link modules, a Content module will likely return a javascript:your_module_name_load() function. Our demo page will ignore any arguments.

function cat_menuitem(args) {
    return "javascript:cat_load('');";
}

Load Function

The load function is called when the menu item is selected. If it doesn't need to retrieve content via ajax it can simply display it right away, but as most modules will need to retrieve the content from some API, a callback back function will actually handle displaying the content. In our demo we will use random.cat to get a random cat image.

function cat_load() {
    pushStateWithoutDuplicate('CATS!', './?p=cat/');
    $.ajax({
        type: 'GET',
        url: "http://aws.random.cat/meow"
    }).done(cat_display);
}

Display Function

As the load function will often request data asynchronously, a display function is often used as a callback function to handle the content actually getting displayed.

function cat_display(cat) {
    var cat_img_src = cat.file;

    var content="<h1>CATS!</h1>";
    content+="<img src='"+cat_img_src+"' style='max-width:100%;'>";
    $('#contentArea').html(content);
}

Permlink Function

You may have noticed in the Load function that we called a function called pushStateWithoutDuplicate. This updates the browser history and url bar to create permanent link urls for dynamically loaded content. We need to create a function that interprets any permanent links that refer to our module...

function cat_permlink(permlink) {
    permlink = permlink.join("/"); // permlink is always an array. Turn into string.
    cat_load(permlink);
}