Documentation

Theme
in package

SMF

Represents a loaded theme. Also provides many theme-related static methods.

The most recently loaded theme is always available as SMF\Theme::$current. All loaded themes are available as SMF\Theme::$loaded[$id], where $id is the ID number of a theme.

The data previously available via the deprecated global $settings array is now available via SMF\Theme::$current->settings.

The data previously available via the deprecated global $options array is now available via SMF\Theme::$current->options.

Properties

$current : object
$extraParams : array<string|int, mixed>
$id : int
$loaded : array<string|int, mixed>
$options : array<string|int, mixed>
$reservedVars : array<string|int, mixed>
$settings : array<string|int, mixed>
$simpleActions : array<string|int, mixed>
$simpleAreas : array<string|int, mixed>
$simpleSubActions : array<string|int, mixed>
$xmlActions : array<string|int, mixed>

Methods

addInlineCss() : bool: Adds a block of inline CSS code to be executed later
addInlineJavaScript() : bool: Add a block of inline JavaScript code to be executed later.
addJavaScriptVar() : void: Add a JavaScript variable for output later (for feeding text strings and the like to JavaScript).
copyright() : void: Show the copyright.
custMinify() : array<string|int, mixed>: Get an array of previously defined files and adds them to our main minified files.
deleteAllMinified() : void: Clears out old minimized CSS and JavaScript files and ensures Config::$modSettings['browser_cache'] is up to date
initialize() : void: Sets a bunch of Utils::$context variables, loads templates and language files, and does other stuff that is required to use the theme for output.
load() : self: Load a theme, by ID.
loadCSSFile() : void: Adds a CSS file for output later.
loadEssential() : void: This loads the bare minimum data to allow us to load language files!
loadJavaScriptFile() : void: Adds a JavaScript file for output later.
loadSubTemplate() : void: Loads a sub-template.
loadSubTemplates() : void: Loads sub-templates into the current theme context.
loadTemplate() : bool|null: Loads a template - if the theme doesn't include it, uses the default.
setupContext() : void: Sets up the basic theme context stuff.
setupMenuContext() : void: Sets up all of the top menu buttons Saves them in the cache if it is available and on Places the results in Utils::$context
template_css() : void: Output the CSS files
template_footer() : void: The template footer.
template_header() : void: The header template.
template_javascript() : void: Output the inline JavaScript and JavaScript files.
wrapAction() : void: Possibly the simplest and best example of how to use the template system.
__construct() : mixed: Constructor. Protected in order to force instantiation via Theme::load().
fixSmileySet() : void: Determine the current smiley set.
fixUrl() : void: If the user got here using an unexpected URL, fix it.
loadCss() : void: Loads the main CSS files for this theme.
loadJavaScript() : void: Loads the boilerplate JavaScript variables and files for this theme.
loadTemplatesAndLangFiles() : void: Figure out which template layers and language files should be loaded.
loadVariant() : void: Loads the correct theme variant, if applicable.
setupLinktree() : void: Sets up the top level linktree.
templateInclude() : void: Load the template/language file using require - loads the template or language file specified by filename.

$current


    public
    static    object
    $current

Instance of this class for the current theme.

$extraParams


    public
        array<string|int, mixed>
    $extraParams
     = []

Extra URL params that ask for XML output instead of HTML.

$id


    public
        int
    $id

This theme's ID number.

$loaded


    public
    static    array<string|int, mixed>
    $loaded
     = []

All loaded instances of this class.

$options


    public
        array<string|int, mixed>
    $options
     = []

This theme's user-configurable settings.

$reservedVars


    public
    static    array<string|int, mixed>
    $reservedVars
     = ['actual_theme_url', 'actual_images_url', 'base_theme_dir', 'base_theme_url', 'default_images_url', 'default_theme_dir', 'default_theme_url', 'default_template', 'images_url', 'number_recent_posts', 'smiley_sets_default', 'theme_dir', 'theme_id', 'theme_layers', 'theme_templates', 'theme_url', 'name']

Theme variables that cannot be changed by users.

$settings


    public
        array<string|int, mixed>
    $settings
     = []

This theme's admin-configurable settings.

$simpleActions


    public
        array<string|int, mixed>
    $simpleActions
     = []

Actions that do not require loading the index template.

$simpleAreas


    public
        array<string|int, mixed>
    $simpleAreas
     = []

Areas that do not require loading the index template. Parent action => array of areas

$simpleSubActions


    public
        array<string|int, mixed>
    $simpleSubActions
     = []

Subactions that do not require loading the index template. Parent action => array of subactions

$xmlActions


    public
        array<string|int, mixed>
    $xmlActions
     = []

Actions that specifically use XML output.

addInlineCss()

Adds a block of inline CSS code to be executed later


    public
            static        addInlineCss(string $css) : bool

Only use this if you have to. Generally external CSS files are better, but for very small changes or for scripts that require help from PHP/whatever, this can be useful.
All code added with this function is added to the same <style> tag, so do make sure your css is valid!

Parameters

$css : string: Some css code

Return values

bool —

Adds the CSS to the Utils::$context['css_header'] array or returns if no CSS is specified

addInlineJavaScript()

Add a block of inline JavaScript code to be executed later.


    public
            static        addInlineJavaScript(string $javascript[, bool $defer = false ]) : bool

Only use this if you have to. Generally external JS files are better, but for very small scripts or for scripts that require help from PHP/whatever, this can be useful.
All code added with this function is added to the same <script> tag, so do make sure your JS is clean!

Parameters

$javascript : string: Some JS code
$defer : bool = false: Whether the script should load in or before the closing tag.

Return values

bool —

Adds the code to one of the Utils::$context['javascript_inline'] arrays, or returns false if no JS was specified.

addJavaScriptVar()

Add a JavaScript variable for output later (for feeding text strings and the like to JavaScript).


    public
            static        addJavaScriptVar(string $key, mixed $value[, bool $escape = false ]) : void

This is cleaner and easier for modders than Theme::addInlineJavaScript().

Parameters

$key : string: The key for this variable
$value : mixed: The value
$escape : bool = false: Whether or not to escape the value

copyright()

Show the copyright.


    public
            static        copyright() : void

custMinify()

Get an array of previously defined files and adds them to our main minified files.


    public
            static        custMinify(array<string|int, mixed> $data, string $type) : array<string|int, mixed>

Sets a one day cache to avoid re-creating a file on every request.

Parameters

$data : array<string|int, mixed>: The files to minify.
$type : string: either css or js.

Return values

array<string|int, mixed> —

Info about the minified file, or about the original files if the minify process failed.

deleteAllMinified()

Clears out old minimized CSS and JavaScript files and ensures Config::$modSettings['browser_cache'] is up to date


    public
            static        deleteAllMinified() : void

initialize()

Sets a bunch of Utils::$context variables, loads templates and language files, and does other stuff that is required to use the theme for output.


    public
                    initialize() : void

load()

Load a theme, by ID.


    public
            static        load([int $id = 0 ][, bool $initialize = true ]) : self

Parameters

$id : int = 0: The ID of the theme to load.
$initialize : bool = true: Whether or not to initialize a bunch of theme-related variables/settings.

Return values

self —

An instance of this class

loadCSSFile()

Adds a CSS file for output later.


    public
            static        loadCSSFile(string $fileName[, array<string|int, mixed> $params = [] ][, string $id = '' ]) : void

Parameters

$fileName : string

The name of the file to load.

$params : array<string|int, mixed> = []

An array of parameters. Keys are the following:

['external'] (true/false): Whether the file is an externally located file. Needs to be set to true if you are loading an external file.
['default_theme'] (true/false): Force use of default theme URL.
['force_current'] (true/false): If this is false, we will attempt to load the file from the default theme if not found in the current theme.
['validate'] (true/false): If true, we will validate that the local file exists.
['rtl'] (string): Additional file to load in RTL mode.
['seed'] (true/false/string): If true or null, use cache stale, false do not, or used a supplied string.
['minimize'] (true/false): Whether to add your file to the main minimized file. Useful when you have a file that is loaded everywhere and for everyone.
['order_pos'] (int): Defines the relative load order of this file. Default value: 3000. FYI, the positions of some of SMF's standard CSS files are as follows: index.css = 1, attachments.css = 450, rtl.css = 4000, responsive.css = 9000.
['attributes']: An array extra attributes to add to the element.

$id : string = ''

An ID to stick on the end of the filename for caching purposes

loadEssential()

This loads the bare minimum data to allow us to load language files!


    public
            static        loadEssential() : void

loadJavaScriptFile()

Adds a JavaScript file for output later.


    public
            static        loadJavaScriptFile(string $fileName[, array<string|int, mixed> $params = [] ][, string $id = '' ]) : void

Parameters

$fileName : string

The name of the file to load

$params : array<string|int, mixed> = []

An array of parameters. Keys are the following:

['external'] (true/false): Whether the file is an externally located file. Needs to be set to true if you are loading an external file.
['default_theme'] (true/false): Force use of default theme URL.
['defer'] (true/false): Whether the file should load in or before the closing tag.
['force_current'] (true/false): If this is false, we will attempt to load the file from the default theme if not found in the current theme.
['async'] (true/false): Whether this script should be loaded asynchronously.
['validate'] (true/false): If true, we will validate that the local file exists.
['seed'] (true/false/string): If true or null, use cache stale, false do not, or used a supplied string.
['minimize'] (true/false): Whether to add your file to the main minimized file. Useful when you have a file that is loaded everywhere and for everyone.
['attributes']: An array of extra attributes to add to the element.

$id : string = ''

An ID to append to the filename.

loadSubTemplate()

Loads a sub-template.


    public
            static        loadSubTemplate(string|array<string|int, mixed> $sub_template_name[, bool|string $fatal = false ]) : void

This function attempts to load and execute a sub-template by constructing its function name and calling it dynamically. If the sub-template cannot be loaded, it handles errors based on the $fatal parameter.

Sub-template function names must follow the format template_{name}.
When debugging is enabled, administrators can see markers after each loaded sub-template.

Parameters

$sub_template_name : string|array<string|int, mixed>

The name of the sub-template to load. If an array is provided, the first element is the name, and the second element is an array of parameters to pass to the sub-template.

$fatal : bool|string = false

Specifies error handling behavior:

false (default): Logs and handles the error.
true: Dies with an error message.
'ignore': Silently ignore any errors.

loadSubTemplates()

Loads sub-templates into the current theme context.


    public
            static        loadSubTemplates() : void

This method loads each sub-template in the sub_templates array. If it is not defined, loads a single sub-template specified by sub_template or falls back to loading the main template.

loadTemplate()

Loads a template - if the theme doesn't include it, uses the default.


    public
            static        loadTemplate(string|bool $template_name[, array<string|int, mixed>|string $style_sheets = [] ][, bool $fatal = true ]) : bool|null

Loads a template file with the name template_name from the current, default, or base theme.
Detects a wrong default theme directory and tries to work around it.

Parameters

$template_name : string|bool: The name of the template to load. If false, only style sheets are loaded.
$style_sheets : array<string|int, mixed>|string = []: The name of a single stylesheet or an array of names of stylesheets to load
$fatal : bool = true: If true, dies with an error message if the template cannot be found

Return values

bool|null —

Whether or not the template was loaded

setupContext()

Sets up the basic theme context stuff.


    public
            static        setupContext([bool $forceload = false ]) : void

Parameters

$forceload : bool = false: Whether to load the theme even if it's already loaded

setupMenuContext()

Sets up all of the top menu buttons Saves them in the cache if it is available and on Places the results in Utils::$context


    public
            static        setupMenuContext() : void

template_css()

Output the CSS files


    public
            static        template_css() : void

template_footer()

The template footer.


    public
            static        template_footer() : void

template_header()

The header template.


    public
            static        template_header() : void

template_javascript()

Output the inline JavaScript and JavaScript files.


    public
            static        template_javascript([bool $do_deferred = false ]) : void

Parameters

$do_deferred : bool = false: If true will only output the deferred JS (the stuff that goes right before the closing body tag)

wrapAction()

Possibly the simplest and best example of how to use the template system.


    public
            static        wrapAction() : void

Allows the theme to take care of actions.
Called if Theme::$current->settings['catch_action'] is set and action isn't found in the action array.
Can use a template, layers, sub_template, filename, and/or function.

__construct()

Constructor. Protected in order to force instantiation via Theme::load().


    protected
                    __construct([int $id = 0 ][, int $member = -1 ]) : mixed

Parameters

$id : int = 0: The ID of the theme to load.
$member : int = -1: The ID of the member whose theme preferences we want.

fixSmileySet()

Determine the current smiley set.


    protected
                    fixSmileySet() : void

fixUrl()

If the user got here using an unexpected URL, fix it.


    protected
                    fixUrl() : void

loadCss()

Loads the main CSS files for this theme.


    protected
                    loadCss() : void

loadJavaScript()

Loads the boilerplate JavaScript variables and files for this theme.


    protected
                    loadJavaScript() : void

loadTemplatesAndLangFiles()

Figure out which template layers and language files should be loaded.


    protected
                    loadTemplatesAndLangFiles() : void

loadVariant()

Loads the correct theme variant, if applicable.


    protected
                    loadVariant() : void

setupLinktree()

Sets up the top level linktree.


    protected
                    setupLinktree() : void

templateInclude()

Load the template/language file using require - loads the template or language file specified by filename.


    protected
            static        templateInclude(string $filename[, bool $once = false ]) : void

uses eval unless disableTemplateEval is enabled.
outputs a parse error if the file did not exist or contained errors.
attempts to detect the error and line, and show detailed information.

Parameters

$filename : string: The name of the file to include
$once : bool = false: If true only includes the file once (like include_once)

Theme in package SMF

Table of Contents

Properties

Methods

Properties

$current

$extraParams

$id

$loaded

$options

$reservedVars

$settings

$simpleActions

$simpleAreas

$simpleSubActions

$xmlActions

Methods

addInlineCss()

Parameters

Return values

addInlineJavaScript()

Parameters

Return values

addJavaScriptVar()

Parameters

copyright()

custMinify()

Parameters

Return values

deleteAllMinified()

initialize()

load()

Parameters

Return values

loadCSSFile()

Parameters

loadEssential()

loadJavaScriptFile()

Parameters

loadSubTemplate()

Parameters

loadSubTemplates()

loadTemplate()

Parameters

Tags

Return values

setupContext()

Parameters

setupMenuContext()

template_css()

template_footer()

template_header()

template_javascript()

Parameters

wrapAction()

__construct()

Parameters

fixSmileySet()

fixUrl()

loadCss()

loadJavaScript()

loadTemplatesAndLangFiles()

loadVariant()

setupLinktree()

templateInclude()

Parameters

Theme
in package

SMF