• Overview

    The |jrCore_format_string variable modifier allows modules to register string formatters that can be used in templates.

    Here's the basic idea:
  • The jrCore_format_string can be applied to a template variable with the quota_id as the first parameter.

    This will handle running all string formatters that have been registered.

    - i.e. "allowed html", "embed", "bbcode", "convert_at_tags", etc.

    The jrCore_format_string modifier will apply all the types of formatting the site might be using, and makes it so you don't have to apply each modifier individually which would call for template modification.

    Here is an example of many modifiers being applied to a variable:

  • Because the previous method shown above requires template modification by each module to add the modifier to the variable, some of these could be from modules that are not even installed if they needed to be added to a skin by default.

    If a module you are creating wants to add a modifier to be included when jrCore_format_string is run, your module should register that it has a string format function in it's init like this:
    $_tmp = array(
        'wl'    => 'click_urls',
        'label' => 'Make URLs Clickable',
        'help'  => 'If active, URLs entered into the text will be hyperlinked so they are clickable.'
    jrCore_register_module_feature('jrCore', 'format_string', 'jrCore', 'jrCore_format_string_clickable_urls', $_tmp);
  • wl - this is the "whitelist/blacklist" name (more on this below)
    label - what it is called in the Core Quota Config
    help - help text for quota config field

    the 4th parameter to the register function is the actual function that is going to be run - i.e.
     * Registered core string formatter - Clickable URLs
     * @param string $string String to format
     * @param int $quota_id Quota ID for Profile ID
     * @return string
    function jrCore_format_string_clickable_urls($string, $quota_id = 0)
        // Convert URL strings
        return jrCore_string_to_url($string);
  • So all it does is run the jrCore_string_to_url on the string, and return it.

    Each formatter is called in order to get the final result.
  • Limit what is run

    If it turns out you only want to run specific formatters on a variable, you can define them in the whitelist - i.e.
  • Would only run the bbcode formatter on the variable.

    If you wanted to exclude just the bbcode formatter, you could add it to the black list:

  • The idea is that template designers should not have to worry about the format of the text that is going to be displayed.

    This opens the possibility to where there could be modules offering Wiki syntax, markdown, spam checking, whatever.

    The creators of theses future modules don't want to have to add variable modifiers to each variable to the templates for any of these options, so now they have a way.
  • Passing in Args

    If you find that what your modifier wants to do requires an argument, like an optional 'size of an image' or something; what you want to can do is to make a global config option instead.

    Args can not be passed in via the template to a specific modifier.

    To set a global option for your module into the config system, you can use your modules config.php file to define options that will later appear in the global $_conf variable.

    Here is an example of that from the jrSmiley module:
     * jrSmiley_config
    function jrSmiley_config()
        // Set smiley size
        $_sz = array(
            '10'  => '10px',
            '12'  => '12px',
            '14'  => '14px',
            '16'  => '16px',
            '18'  => '18px',
            '20'  => '20px',
            '24'  => '24px',
            '28'  => '28px',
            '32'  => '32px',
            '36'  => '36px',
            '40'  => '40px',
            '48'  => '48px',
            '56'  => '56px',
            '64'  => '64px',
        $_tmp = array(
            'name'     => 'size',
            'type'     => 'select',
            'default'  => '14',
            'options'    => $_sz,
            'validate' => 'printable',
            'label'    => 'Smiley Size',
            'help'     => 'Select smiley size'
        return true;
  • The jrSmiley module is allowing the admin user to define the size of the smileys for their system.
  • Activating / Deactivating a text formatter

    After the module has designed the feature and the template has decided to use allow the formatters to be used on a variable, the last decision is made by the admin user.

    The admin user has the option of enabling / disabling all the formatters on a per-quota basis.

    The admin user from the ACP can set whether each text formatter is used on any particular group of users output from the setting in the admin control panel.

    That setting is done from:
    ACP - MODULES - SYSTEM CORE - QUOTA CONFIG - "Active Text Formatters"
  • screenshot of the "Active Text Formatters" option in the ACP
  • By adding a check to the checkbox, the admin is allowing that text formatter to be active for members in that particular quota.

    Each quota can have different text formatters active.