Documentation

Theme
in package

SMF

Uses BackwardCompatibility

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

$agreement_actions : array<string|int, mixed>
$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>
$backcompat : array<string|int, mixed>

Methods

addInlineCss() : void|bool: Adds a block of inline CSS code to be executed later
addInlineJavaScript() : void|bool: Add a block of inline JavaScript code to be executed later.
addJavaScriptVar() : mixed: Add a JavaScript variable for output later (for feeding text strings and the like to JavaScript).
copyright() : mixed: Show the copyright.
createButton() : string: Creates an image/text button.
custMinify() : array<string|int, mixed>: Get an array of previously defined files and adds them to our main minified files.
deleteAllMinified() : mixed: Clears out old minimized CSS and JavaScript files and ensures Config::$modSettings['browser_cache'] is up to date
dispatch() : mixed: Redirects ?action=theme to the correct location.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
load() : mixed: Load a theme, by ID.
loadCSSFile() : mixed: Adds a CSS file for output later.
loadEssential() : mixed: This loads the bare minimum data to allow us to load language files!
loadJavaScriptFile() : mixed: Adds a JavaScript file for output later.
loadSubTemplate() : mixed: Loads a sub-template.
loadTemplate() : bool: Loads a template - if the theme doesn't include it, uses the default.
pickTheme() : mixed: Shows an interface to allow a member to choose a new theme.
setJavaScript() : mixed: Sets an option via JavaScript.
setupContext() : mixed: Sets up the basic theme context stuff.
setupMenuContext() : mixed: 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() : mixed: Output the CSS files
template_footer() : mixed: The template footer.
template_header() : mixed: The header template.
template_javascript() : mixed: Output the inline JavaScript and JavaScript files.
wrapAction() : mixed: 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().
canPickTheme() : bool: Determines if a user can change their theme to the one specified.
fixSmileySet() : mixed: Determine the current smiley set.
fixUrl() : mixed: If the user got here using an unexpected URL, fix it.
initialize() : mixed: 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.
loadCss() : mixed: Loads the main CSS files for this theme.
loadJavaScript() : mixed: Loads the boilerplate JavaScript variables and files for this theme.
loadTemplatesAndLangFiles() : mixed: Figure out which template layers and language files should be loaded.
loadVariant() : mixed: Loads the correct theme variant, if applicable.
requireAgreement() : mixed: If necessary, redirect to the agreement or privacy policy so that we can force the user to accept the current version.
setupLinktree() : mixed: Sets up the top level linktree.
sslRedirect() : mixed: Check to see if we're forcing SSL, and redirect if necessary.
templateInclude() : mixed: Load the template/language file using require - loads the template or language file specified by filename.

$agreement_actions


    public
        array<string|int, mixed>
    $agreement_actions
     = ['agreement' => true, 'acceptagreement' => true, 'login2' => true, 'logintfa' => true, 'logout' => true, 'pm' => ['sa' => ['popup']], 'profile' => ['area' => ['popup', 'alerts_popup']], 'xmlhttp' => true, '.xml' => true]

Actions that can be accessed without accepting to the registration agreement and privacy policy.

$current


    public
    static    object
    $current

Instance of this class for the current theme.

$extraParams


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

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
     = ['findmember', 'helpadmin', 'printpage']

Actions that do not require loading the index template.

$simpleAreas


    public
        array<string|int, mixed>
    $simpleAreas
     = ['profile' => ['popup', 'alerts_popup']]

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

$simpleSubActions


    public
        array<string|int, mixed>
    $simpleSubActions
     = ['pm' => ['popup'], 'signup' => ['usernamecheck']]

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

$xmlActions


    public
        array<string|int, mixed>
    $xmlActions
     = ['quotefast', 'jsmodify', 'xmlhttp', 'post2', 'suggest', 'stats', 'notifytopic', 'notifyboard']

Actions that specifically use XML output.

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = [
    // Public static methods not listed here will keep the same name when
    // exported to global namespace.
    'func_names' => ['load' => 'loadTheme', 'loadEssential' => 'loadEssentialThemeData', 'loadTemplate' => 'loadTemplate', 'loadSubTemplate' => 'loadSubTemplate', 'loadCSSFile' => 'loadCSSFile', 'addInlineCss' => 'addInlineCss', 'loadJavaScriptFile' => 'loadJavaScriptFile', 'addJavaScriptVar' => 'addJavaScriptVar', 'addInlineJavaScript' => 'addInlineJavaScript', 'setupContext' => 'setupThemeContext', 'setupMenuContext' => 'setupMenuContext', 'template_header' => 'template_header', 'copyright' => 'theme_copyright', 'template_footer' => 'template_footer', 'template_javascript' => 'template_javascript', 'template_css' => 'template_css', 'custMinify' => 'custMinify', 'deleteAllMinified' => 'deleteAllMinified', 'setJavaScript' => 'SetJavaScript', 'wrapAction' => 'WrapAction', 'dispatch' => 'dispatch', 'pickTheme' => 'PickTheme', 'createButton' => 'create_button'],
]

BackwardCompatibility settings for this class.

addInlineCss()

Adds a block of inline CSS code to be executed later


    public
            static        addInlineCss(string $css) : void|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

void|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 ]) : void|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

void|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, string $value[, bool $escape = false ]) : mixed

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

Parameters

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

copyright()

Show the copyright.


    public
            static        copyright() : mixed

createButton()

Creates an image/text button.


    public
            static        createButton(string $name, string $alt[, string $label = '' ][, string $custom = '' ][, bool $force_use = false ]) : string

Parameters

$name : string: The name of the button. Should be a main_icons class or the name of an image.
$alt : string: The alt text.
$label : string = '': The Lang::$txt string to use as the label.
$custom : string = '': Custom text/html to add to the img tag. Only when using an actual image.
$force_use : bool = false: Whether to override template_create_button and use this instead.

Return values

string —

The HTML to display the button.

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() : mixed

dispatch()

Redirects ?action=theme to the correct location.


    public
            static        dispatch() : mixed

exportStatic()

Provides a way to export a class's public static properties and methods to global namespace.


    public
            static        exportStatic() : void

To do so:

Use this trait in the class.
At the END of the class's file, call its exportStatic() method.

Although it might not seem that way at first glance, this approach conforms to section 2.3 of PSR 1, since executing this method is simply a dynamic means of declaring functions when the file is included; it has no other side effects.

Regarding the $backcompat items:

A class's static properties are not exported to global variables unless explicitly included in $backcompat['prop_names']. Likewise, a class's static methods are not exported as global functions unless explicitly included in $backcompat['func_names'].

$backcompat['prop_names'] is a simple array where the keys are the names of one or more of a class's static properties, and the values are the names of global variables. In each case, the global variable will be set to a reference to the static property. Static properties that are not named in this array will not be exported.

$backcompat['func_names'] is a simple array where the keys are the names of one or more of a class's static methods, and the values are the names that should be used for global functions that will encapsulate those methods. Methods that are not named in this array will not be exported.

Adding non-static properties or methods to the $backcompat arrays will produce runtime errors. It is the responsibility of the developer to make sure not to do this.

load()

Load a theme, by ID.


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

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.

loadCSSFile()

Adds a CSS file for output later.


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

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 a 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() : mixed

loadJavaScriptFile()

Adds a JavaScript file for output later.


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

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 a 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 $sub_template_name[, bool $fatal = false ]) : mixed

Loads the sub template specified by sub_template_name, which must be in an already-loaded template.
If ?debug is in the query string, shows administrators a marker after every sub template for debugging purposes.

Parameters

$sub_template_name : string: The name of the sub-template to load
$fatal : bool = false: Whether to die with an error if the sub-template can't be loaded

loadTemplate()

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


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

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: The name of the template to load
$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 —

Whether or not the template was loaded

pickTheme()

Shows an interface to allow a member to choose a new theme.


    public
            static        pickTheme() : mixed

uses the Themes template. (pick sub template.)
accessed with ?action=theme;sa=pick.

setJavaScript()

Sets an option via JavaScript.


    public
            static        setJavaScript() : mixed

sets a theme option without outputting anything.
can be used with JavaScript, via a dummy image... (which doesn't require the page to reload.)
requires someone who is logged in.
accessed via ?action=jsoption;var=variable;val=value;session_var=sess_id.
does not log access to the Who's Online log. (in index.php..)

setupContext()

Sets up the basic theme context stuff.


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

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() : mixed

template_css()

Output the CSS files


    public
            static        template_css() : mixed

template_footer()

The template footer.


    public
            static        template_footer() : mixed

template_header()

The header template.


    public
            static        template_header() : mixed

template_javascript()

Output the inline JavaScript and JavaScript files.


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

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() : mixed

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.

canPickTheme()

Determines if a user can change their theme to the one specified.


    protected
            static        canPickTheme(int $id_member, int $id_theme) : bool

Parameters

$id_member : int
$id_theme : int

Return values

bool

fixSmileySet()

Determine the current smiley set.


    protected
                    fixSmileySet() : mixed

fixUrl()

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


    protected
                    fixUrl() : mixed

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.


    protected
                    initialize() : mixed

loadCss()

Loads the main CSS files for this theme.


    protected
                    loadCss() : mixed

loadJavaScript()

Loads the boilerplate JavaScript variables and files for this theme.


    protected
                    loadJavaScript() : mixed

loadTemplatesAndLangFiles()

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


    protected
                    loadTemplatesAndLangFiles() : mixed

loadVariant()

Loads the correct theme variant, if applicable.


    protected
                    loadVariant() : mixed

requireAgreement()

If necessary, redirect to the agreement or privacy policy so that we can force the user to accept the current version.


    protected
                    requireAgreement() : mixed

setupLinktree()

Sets up the top level linktree.


    protected
                    setupLinktree() : mixed

sslRedirect()

Check to see if we're forcing SSL, and redirect if necessary.


    protected
                    sslRedirect() : mixed

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 ]) : mixed

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 Uses BackwardCompatibility

Table of Contents

Properties

Methods

Properties

$agreement_actions

$current

$extraParams

$id

$loaded

$options

$reservedVars

$settings

$simpleActions

$simpleAreas

$simpleSubActions

$xmlActions

$backcompat

Methods

addInlineCss()

Parameters

Return values

addInlineJavaScript()

Parameters

Return values

addJavaScriptVar()

Parameters

copyright()

createButton()

Parameters

Tags

Return values

custMinify()

Parameters

Return values

deleteAllMinified()

dispatch()

exportStatic()

load()

Parameters

loadCSSFile()

Parameters

loadEssential()

loadJavaScriptFile()

Parameters

loadSubTemplate()

Parameters

Tags

loadTemplate()

Parameters

Tags

Return values

pickTheme()

setJavaScript()

setupContext()

Parameters

setupMenuContext()

template_css()

template_footer()

template_header()

template_javascript()

Parameters

wrapAction()

__construct()

Parameters

canPickTheme()

Parameters

Return values

fixSmileySet()

fixUrl()

initialize()

loadCss()

loadJavaScript()

loadTemplatesAndLangFiles()

loadVariant()

requireAgreement()

setupLinktree()

sslRedirect()

templateInclude()

Parameters

Theme
in package

SMF

Uses BackwardCompatibility