Support Center

About Koken

This Help Center provides support for Koken, a free content management system designed for photographers, artists and designers.

Shortcodes

Shortcodes

Last Updated: Jul 25, 2013 04:49PM EDT
Developing a shortcode plugin begins like any other Koken plugin -- by creating a folder to contain your plugin in storage/plugins, then creating a plugin.json and plugin.php file inside. For more on that process, view the Getting started guide.

Standard shortcodes take a piece of content or collection from the user's library and format it for display within the essay or page they embed it inside. Shortcodes can use photos, videos or collections. To define a shortcode, add a shortcodes object to your plugin's plugin.json file:
{
    "name": "My fancy shortcode",
    "version": "1.0",
    "description": "What my fancy shortcode does.",
    "demo": "http://myhomepage.com",
    "author": {
        "name": "John Doe",
        "link": "http://johndoe.me"
    },

    "shortcodes": {

        "acme_photo": {

        }
    }
}
The name of your shortcode ("acme_photo" in the example above) must consist of only letters, numbers and underscores. It should be unique, following the [company]_[shortcode name] convention. The shortcode must define at least 4 pieces of data: title, description, media and icon:
"acme_photo": {

    "title": "Insert library photo",
    "description": "Display a library photo in your essay or page."
    "media": "photo",
    "icon": "data:image/png;base64,iVBOR..."

}
The title and description are used in Koken's Text interface when the user is interacting with your plugin, so be sure it accurately describes what your shortcode does. "media" defines what type of item the user should select to use with your shortcode. Koken will automatically create the necessary picker for the user to choose the media. Valid options are photo, video and collection. The icon should be a base64 encoded image that is 16x16. It is used when the shortcode media element is rendered in the text editor.

Translating your shortcode into HTML output

When your shortcode is used in a page or essay, your plugin's PHP class will be called upon to translate that shortcode into HTML. The first step is registering your shortcode and the function that should handle its translation in the class's constructor. Below, we are registering our acme_photo shortcode that was defined in plugin.json with our render class function.​
​<?php

class AcmeShortcodes extends KokenPlugin {

    function __construct()
    {
        $this->register_shortcode('acme_photo', 'render');
    }

}

​Now, we just need to create that render function:

​<?php

class AcmeShortcodes extends KokenPlugin {

    function __construct()
    {
        $this->register_shortcode('acme_photo', 'render');
    }

    function render($attributes)
    {
        return <<<HTML
<div class="k-content-embed">
    <koken:load source="content" filter:id="{$attributes['id']}">
        <div class="k-content">
            <koken:img />
        </div>
    </koken:load>
</div>
HTML;
    }

}

​Your function will be passed any attributes the shortcode has been assigned. In this simple example, it will pass the id of the selected photo. We can then use that id to create Lens template markup that will output the photo inside the rendered page or essay.

A note about HTML structure

To increase consistency across themes, we recommend wrapping your output in a parent div with the "k-content-embed" class. If your shortcode displays media, that media should be inside its own div with the "k-content" class. Any metadata that is displayed should be inside the parent ("k-content-embed") div, but not inside the "k-content" div. See the above render function for an example.

Advanced topics

Shortcodes can define additional options that are displayed to the user when they edit the shortcode. Options are defined in the shortcode's data object in the plugin.json file. Extending our existing example, we can add an option to show the title and caption for the photo:
"acme_photo": {

    "title": "Insert library photo",
    "description": "Display a library photo in your essay or page."
    "media": "photo",
    "icon": "data:image/png;base64,iVB...",

    "data": {

        "caption": {
            "label": "Caption",
            "type": "select",
            "options": [
                { "label": "Do not show", "value": "none" },
                { "label": "Show title only", "value": "title" },
                { "label": "Show caption only", "value": "caption" },
                { "label": "Show title and caption", "value": "both" }
            ]
        }

    }

}

​When the user edits the shortcode, they will be presented with an HTML form with the options specified. In the above example, the user will see a <select> element with the supplied options. The user's selection will then be passed to the shortcode's plugin.php file. Checking back in with our render function from above, you can see the additional options are passed along with the other attributes:

function render($attributes)
{
    $text = '';
    if (isset($attr['caption']) && $attr['caption'] !== 'none')
    {
        $text .= '<div class="k-content-text">';
        if ($attr['caption'] !== 'caption')
        {
            $text .= '<span class="k-content-title"><koken:print data="content.title" fallback="content.filename" /></span>';
        }
        if ($attr['caption'] !== 'title')
        {
            $text .= '<span class="k-content-caption"><koken:print data="content.caption" /></span>';
        }
        $text .= '</div>';
    }

    return <<<HTML
<div class="k-content-embed">
    <koken:load source="content" filter:id="{$attributes['id']}">
        <div class="k-content">
            <koken:img />
        </div>
    </koken:load>
    $text
</div>
HTML;
}
support@koken.me
http://assets2.desk.com/
false
koken
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete