Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/lib/ -> outputlib.php (source)

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

Functions for generating the HTML that Moodle should output. Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML for an overview.

Copyright: 2009 Tim Hunt
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 2742 lines (99 kb)
Included or required:0 times
Referenced: 1 time
Includes or requires: 0 files

Defines 2 classes

Defines 7 functions


Class: theme_config  - X-Ref

This class represents the configuration variables of a Moodle theme.

All the variables with access: public below (with a few exceptions that are marked)
are the properties you can set in your themes config.php file.

There are also some methods and protected variables that are part of the inner
workings of Moodle's themes system. If you are just editing a themes config.php
file, you can just ignore those, and the following information for developers.

Normally, to create an instance of this class, you should use the
{@link theme_config::load()} factory method to load a themes config.php file.
However, normally you don't need to bother, because moodle_page (that is, $PAGE)
will create one for you, accessible as $PAGE->theme.

load($themename)   X-Ref
Load the config.php file for a particular theme, and return an instance
of this class. (That is, this is a factory method.)

param: string $themename the name of the theme.
return: theme_config an instance of this class.

diagnose($themename)   X-Ref
Theme diagnostic code. It is very problematic to send debug output
to the actual CSS file, instead this functions is supposed to
diagnose given theme and highlights all potential problems.
This information should be available from the theme selection page
or some other debug page for theme designers.

param: string $themename
return: array description of problems

__construct($config)   X-Ref
Private constructor, can be called only from the factory method.

param: stdClass $config

init_page(moodle_page $page)   X-Ref
Let the theme initialise the page object (usually $PAGE).

This may be used for example to request jQuery in add-ons.

param: moodle_page $page

check_theme_arrows()   X-Ref
Checks if arrows $THEME->rarrow, $THEME->larrow, $THEME->uarrow, $THEME->darrow have been set (theme/-/config.php).
If not it applies sensible defaults.

Accessibility: right and left arrow Unicode characters for breadcrumb, calendar,
search forum block, etc. Important: these are 'silent' in a screen-reader
(unlike > »), and must be accompanied by text.

renderer_prefixes()   X-Ref
Returns output renderer prefixes, these are used when looking
for the overridden renderers in themes.

return: array

editor_css_url($encoded=true)   X-Ref
Returns the stylesheet URL of this editor content

param: bool $encoded false means use & and true use & in URLs
return: moodle_url

editor_css_files()   X-Ref
Returns the content of the CSS to be used in editor content

return: array

editor_scss_to_css()   X-Ref
Compiles and returns the content of the SCSS to be used in editor content

return: string Compiled CSS from the editor SCSS

css_urls(moodle_page $page)   X-Ref
Get the stylesheet URL of this theme.

param: moodle_page $page Not used... deprecated?
return: moodle_url[]

get_css_content()   X-Ref
Get the whole css stylesheet for production mode.

NOTE: this method is not expected to be used from any addons.

return: string CSS markup compressed

set_css_content_cache($csscontent)   X-Ref
Set post processed CSS content cache.

param: string $csscontent The post processed CSS content.
return: bool True if the content was successfully cached.

has_css_cached_content()   X-Ref
Return whether the post processed CSS content has been cached.

return: bool Whether the post-processed CSS is available in the cache.

get_css_cached_content()   X-Ref
Return cached post processed CSS content.

return: bool|string The cached css content or false if not found.

get_css_cache_key()   X-Ref
Generate the css content cache key.

return: string The post processed css cache key.

get_css_content_debug($type, $subtype, $sheet)   X-Ref
Get the theme designer css markup,
the parameters are coming from css_urls().

NOTE: this method is not expected to be used from any addons.

param: string $type
param: string $subtype
param: string $sheet
return: string CSS markup

get_css_content_editor()   X-Ref
Get the whole css stylesheet for editor iframe.

NOTE: this method is not expected to be used from any addons.

return: string CSS markup

get_css_files($themedesigner)   X-Ref
Returns an array of organised CSS files required for this output.

param: bool $themedesigner
return: array nested array of file paths

get_css_content_from_scss($themedesigner)   X-Ref
Return the CSS content generated from the SCSS file.

param: bool $themedesigner True if theme designer is enabled.
return: bool|string Return false when the compilation failed. Else the compiled string.

get_precompiled_css_content()   X-Ref
Return the precompiled CSS if the precompiledcsscallback exists.

return: string Return compiled css.

get_icon_system()   X-Ref
Get the icon system to use.

return: string

get_extra_scss_code()   X-Ref
Return extra SCSS code to add when compiling.

This is intended to be used by themes to inject some SCSS code
before it gets compiled. If you want to inject variables you
should use {@link self::get_scss_variables()}.

return: string The SCSS code to inject.

get_pre_scss_code()   X-Ref
SCSS code to prepend when compiling.

This is intended to be used by themes to inject SCSS code before it gets compiled.

return: string The SCSS code to inject.

get_scss_property()   X-Ref
Get the SCSS property.

This resolves whether a SCSS file (or content) has to be used when generating
the stylesheet for the theme. It will look at parents themes and check the
SCSS properties there.

return: False when SCSS is not used.

javascript_url($inhead)   X-Ref
Generate a URL to the file that serves theme JavaScript files.

If we determine that the theme has no relevant files, then we return
early with a null value.

param: bool $inhead true means head url, false means footer
return: moodle_url|null

javascript_files($type)   X-Ref
Get the URL's for the JavaScript files used by this theme.
They won't be served directly, instead they'll be mediated through
theme/javascript.php.

param: string $type Either javascripts_footer, or javascripts
return: array

resolve_excludes($variable, $default = null)   X-Ref
Resolves an exclude setting to the themes setting is applicable or the
setting of its closest parent.

param: string $variable The name of the setting the exclude setting to resolve
param: string $default
return: mixed

javascript_content($type)   X-Ref
Returns the content of the one huge javascript file merged from all theme javascript files.

param: bool $type
return: string

post_process($css)   X-Ref
Post processes CSS.

This method post processes all of the CSS before it is served for this theme.
This is done so that things such as image URL's can be swapped in and to
run any specific CSS post process method the theme has requested.
This allows themes to use CSS settings.

param: string $css The CSS to process.
return: string The processed CSS.

rtlize($csstree)   X-Ref
Flip a stylesheet to RTL.

param: Object $csstree The parsed CSS tree structure to flip.
return: void

pix_url($imagename, $component)   X-Ref
Return the direct URL for an image from the pix folder.

Use this function sparingly and never for icons. For icons use pix_icon or the pix helper in a mustache template.

param: string $imagename the name of the icon.
param: string $component specification of one plugin like in get_string()
return: moodle_url

image_url($imagename, $component)   X-Ref
Return the direct URL for an image from the pix folder.

Use this function sparingly and never for icons. For icons use pix_icon or the pix helper in a mustache template.

param: string $imagename the name of the icon.
param: string $component specification of one plugin like in get_string()
return: moodle_url

font_url($font, $component)   X-Ref
Return the URL for a font

param: string $font the name of the font (including extension).
param: string $component specification of one plugin like in get_string()
return: moodle_url

setting_file_url($setting, $filearea)   X-Ref
Returns URL to the stored file via pluginfile.php.

Note the theme must also implement pluginfile.php handler,
theme revision is used instead of the itemid.

param: string $setting
param: string $filearea
return: string protocol relative URL or null if not present

setting_file_serve($filearea, $args, $forcedownload, $options)   X-Ref
Serve the theme setting file.

param: string $filearea
param: array $args
param: bool $forcedownload
param: array $options
return: bool may terminate if file not found or donotdie not specified

resolve_image_location($image, $component, $svg = false)   X-Ref
Resolves the real image location.

$svg was introduced as an arg in 2.4. It is important because not all supported browsers support the use of SVG
and we need a way in which to turn it off.
By default SVG won't be used unless asked for. This is done for two reasons:
1. It ensures that we don't serve svg images unless we really want to. The admin has selected to force them, of the users
browser supports SVG.
2. We only serve SVG images from locations we trust. This must NOT include any areas where the image may have been uploaded
by the user due to security concerns.

param: string $image name of image, may contain relative path
param: string $component
param: bool $svg|null Should SVG images also be looked for? If null, resorts to $CFG->svgicons if that is set; falls back to
return: string full file path

resolve_font_location($font, $component)   X-Ref
Resolves the real font location.

param: string $font name of font file
param: string $component
return: string full file path

use_svg_icons()   X-Ref
Return true if we should look for SVG images as well.

return: bool

force_svg_use($setting)   X-Ref
Forces the usesvg setting to either true or false, avoiding any decision making.

This function should only ever be used when absolutely required, and before any generation of image URL's has occurred.
DO NOT ABUSE THIS FUNCTION... not that you'd want to right ;)

param: bool $setting True to force the use of svg when available, null otherwise.

set_rtl_mode($inrtl = true)   X-Ref
Set to be in RTL mode.

This will likely be used when post processing the CSS before serving it.

param: bool $inrtl True when in RTL mode.

supports_source_maps($themedesigner)   X-Ref
Checks if source maps are supported

param: bool $themedesigner True if theme designer is enabled.
return: boolean True if source maps are supported.

get_rtl_mode()   X-Ref
Whether the theme is being served in RTL mode.

return: bool True when in RTL mode.

image_exists($filepath, $svg = false)   X-Ref
Checks if file with any image extension exists.

The order to these images was adjusted prior to the release of 2.4
At that point the were the following image counts in Moodle core:

- png = 667 in pix dirs (1499 total)
- gif = 385 in pix dirs (606 total)
- jpg = 62  in pix dirs (74 total)
- jpeg = 0  in pix dirs (1 total)

There is work in progress to move towards SVG presently hence that has been prioritiesed.

param: string $filepath
param: bool $svg If set to true SVG images will also be looked for.
return: string image name with extension

find_theme_config($themename, $settings, $parentscheck = true)   X-Ref
Loads the theme config from config.php file.

param: string $themename
param: stdClass $settings from config_plugins table
param: boolean $parentscheck true to also check the parents.    .
return: stdClass The theme configuration

find_theme_location($themename)   X-Ref
Finds the theme location and verifies the theme has all needed files
and is not obsoleted.

param: string $themename
return: string full dir path or null if not found

get_renderer(moodle_page $page, $component, $subtype = null, $target = null)   X-Ref
Get the renderer for a part of Moodle for this theme.

param: moodle_page $page the page we are rendering
param: string $component the name of part of moodle. E.g. 'core', 'quiz', 'qtype_multichoice'.
param: string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
param: string $target one of rendering target constants
return: renderer_base the requested renderer.

layout_info_for_page($pagelayout)   X-Ref
Get the information from {@link $layouts} for this type of page.

param: string $pagelayout the the page layout name.
return: array the appropriate part of {@link $layouts}.

layout_file($pagelayout)   X-Ref
Given the settings of this theme, and the page pagelayout, return the
full path of the page layout file to use.

Used by {@link core_renderer::header()}.

param: string $pagelayout the the page layout name.
return: string Full path to the lyout file to use

pagelayout_options($pagelayout)   X-Ref
Returns auxiliary page layout options specified in layout configuration array.

param: string $pagelayout
return: array

setup_blocks($pagelayout, $blockmanager)   X-Ref
Inform a block_manager about the block regions this theme wants on this
page layout.

param: string $pagelayout the general type of the page.
param: block_manager $blockmanager the block_manger to set up.

get_region_name($region, $theme)   X-Ref
Gets the visible name for the requested block region.

param: string $region The region name to get
param: string $theme The theme the region belongs to (may come from the parent theme)
return: string

get_all_block_regions()   X-Ref
Get the list of all block regions known to this theme in all templates.

return: array internal region name => human readable name.

get_theme_name()   X-Ref
Returns the human readable name of the theme

return: string

get_block_render_method()   X-Ref
Returns the block render method.

It is set by the theme via:
$THEME->blockrendermethod = '...';

It can be one of two values, blocks or blocks_for_region.
It should be set to the method being used by the theme layouts.

return: string

get_css_tree_post_processor()   X-Ref
Get the callable for CSS tree post processing.

return: string|null

Class: xhtml_container_stack  - X-Ref

This class keeps track of which HTML tags are currently open.

This makes it much easier to always generate well formed XHTML output, even
if execution terminates abruptly. Any time you output some opening HTML
without the matching closing HTML, you should push the necessary close tags
onto the stack.

__construct()   X-Ref
Constructor


push($type, $closehtml)   X-Ref
Push the close HTML for a recently opened container onto the stack.

param: string $type The type of container. This is checked when {@link pop()}
param: string $closehtml The HTML required to close the container.

pop($type)   X-Ref
Pop the HTML for the next closing container from the stack. The $type
must match the type passed when the container was opened, otherwise a
warning will be output.

param: string $type The type of container.
return: string the HTML required to close the container.

pop_all_but_last($shouldbenone = false)   X-Ref
Close all but the last open container. This is useful in places like error
handling, where you want to close all the open containers (apart from <body>)
before outputting the error message.

param: bool $shouldbenone assert that the stack should be empty now - causes a
return: string the HTML required to close any open containers inside <body>.

discard()   X-Ref
You can call this function if you want to throw away an instance of this
class without properly emptying the stack (for example, in a unit test).
Calling this method stops the destruct method from outputting a developer
debug warning. After calling this method, the instance can no longer be used.


log($action, $type)   X-Ref
Adds an entry to the log.

param: string $action The name of the action
param: string $type The type of action

output_log()   X-Ref
Outputs the log's contents as a HTML list.

return: string HTML list of the log

Functions that are not part of a class:

theme_get_revision()   X-Ref
Returns current theme revision number.

return: int

theme_get_sub_revision_for_theme($themename)   X-Ref
Returns current theme sub revision number. This is the revision for
this theme exclusively, not the global theme revision.

param: string $themename The non-frankenstyle name of the theme
return: int

theme_get_next_revision()   X-Ref
Calculates and returns the next theme revision number.

return: int

theme_get_next_sub_revision_for_theme($themename)   X-Ref
Calculates and returns the next theme revision number.

param: string $themename The non-frankenstyle name of the theme
return: int

theme_set_revision($revision)   X-Ref
Sets the current theme revision number.

param: int $revision The new theme revision number

theme_set_sub_revision_for_theme($themename, $revision)   X-Ref
Sets the current theme revision number for a specific theme.
This does not affect the global themerev value.

param: string $themename The non-frankenstyle name of the theme
param: int    $revision  The new theme revision number

theme_get_config_file_path($themename)   X-Ref
Get the path to a theme config.php file.

param: string $themename The non-frankenstyle name of the theme to check

theme_get_css_filename($themename, $globalrevision, $themerevision, $direction)   X-Ref
Get the path to the local cached CSS file.

param: string $themename      The non-frankenstyle theme name.
param: int    $globalrevision The global theme revision.
param: int    $themerevision  The theme specific revision.
param: string $direction      Either 'ltr' or 'rtl' (case sensitive).

theme_build_css_for_themes($themeconfigs = [], $directions = ['rtl', 'ltr'],$cache = true, $mtraceprogress = false)   X-Ref
Generates and saves the CSS files for the given theme configs.

param: theme_config[] $themeconfigs An array of theme_config instances.
param: array          $directions   Must be a subset of ['rtl', 'ltr'].
param: bool           $cache        Should the generated files be stored in local cache.
return: array         The built theme content in a multi-dimensional array of name => direction => content

theme_reset_all_caches()   X-Ref
Invalidate all server and client side caches.

This method deletes the physical directory that is used to cache the theme
files used for serving.
Because it deletes the main theme cache directory all themes are reset by
this function.

theme_reset_static_caches()   X-Ref
Reset static caches.

This method indicates that all running cron processes should exit at the
next opportunity.

theme_set_designer_mod($state)   X-Ref
Enable or disable theme designer mode.

param: bool $state

theme_is_device_locked($device)   X-Ref
Checks if the given device has a theme defined in config.php.

return: bool

theme_get_locked_theme_for_device($device)   X-Ref
Returns the theme named defined in config.php for the given device.

return: string or null