ilMathJax Class Reference

Class for processing of latex formulas This class uses a sigleton pattern to store the rendering purpose during a request. More...

Collaboration diagram for ilMathJax:

Public Member Functions
	init (string $a_purpose=self::PURPOSE_BROWSER)
	Initialize the usage for a certain purpose This must be done before any rendering call. More...
	setRendering (string $a_rendering)
	Set the image type rendered by the server. More...
	setDpi (int $a_dpi)
	Set the dpi of the rendered images. More...
	setZoomFactor (float $a_factor)
	Set the zoom factor of the rendered images. More...
	includeMathJax (?ilGlobalTemplateInterface $a_tpl=null)
	Include the Mathjax javascript(s) in the page template. More...
	insertLatexImages (string $a_text, ?string $a_start='[tex]', ?string $a_end='[/tex]')
	Replace all tex code within given start and end delimiters in a text If client-side rendering is enabled, change the start end end delimiters to what Mathjax expects If Server-side rendering is used, replace the whole expression with delimiters by svg or image. More...
	getCacheSize ()
	Get the size of the image cache. More...
	clearCache ()
	Clear the cache of rendered graphics. More...

Static Public Member Functions
static	getInstance ()
	Singleton: get instance for use in ILIAS requests with a config loaded from the settings. More...
static	getIndependent (ilMathJaxConfig $config, ilMathJaxFactory $factory)
	Get an independent instance with a specific config for use in unit tests or on the mathjax settings page Don't use in standard cases! More...

Data Fields
const	PURPOSE_BROWSER = 'browser'
const	PURPOSE_EXPORT = 'export'
const	PURPOSE_PDF = 'pdf'
const	PURPOSE_DEFERRED_PDF = 'deferred_pdf'
const	ENGINE_SERVER = 'server'
const	ENGINE_CLIENT = 'client'
const	ENGINE_DEFERRED = 'deferred'
const	ENGINE_NONE = 'none'
const	RENDER_SVG_AS_XML_EMBED = 'svg_as_xml_embed'
const	RENDER_SVG_AS_IMG_EMBED = 'svg_as_img_embed'
const	RENDER_PNG_AS_IMG_EMBED = 'png_as_img_embed'
const	RENDER_PNG_AS_FO_FILE = 'png_as_fo_file'

Protected Member Functions
	__construct (ilMathJaxConfig $config, ilMathJaxFactory $factory)
	Protected constructor to force the use of an initialized instance. More...
	setEngine (string $a_engine)
	Set the Rendering engine. More...
	renderMathJax (string $a_tex)
	Render image from tex code using the MathJax server. More...

Protected Attributes
const	OUTPUT_SVG = 'svg'
const	OUTPUT_PNG = 'png'
const	DEFAULT_DPI = 150
const	DEFAULT_ZOOM = 1.0
ilMathJaxConfig	$config
ilMathJaxFactory	$factory
string	$engine
string	$rendering = self::RENDER_SVG_AS_XML_EMBED
string	$output = self::OUTPUT_SVG
int	$dpi
float	$zoom_factor
array	$default_server_options

Static Protected Attributes
static self	$_instance

Detailed Description

Class for processing of latex formulas This class uses a sigleton pattern to store the rendering purpose during a request.

The rendering purpose for export or deferred PDF generation must be determined at the beginning of a request. All following calls to convert latex code must use this purpose. Use init() to reset the purpose and all related settings.

Definition at line 29 of file class.ilMathJax.php.

Constructor & Destructor Documentation

__construct()

ilMathJax::__construct ( ilMathJaxConfig  $config, ilMathJaxFactory  $factory  )

protected

Protected constructor to force the use of an initialized instance.

Definition at line 113 of file class.ilMathJax.php.

References $config, $factory, factory(), and init().

    {
        $this->config = $config;
        $this->factory = $factory;
        $this->init(self::PURPOSE_BROWSER);
    }

Here is the call graph for this function:

Member Function Documentation

clearCache()

ilMathJax::clearCache

(

)

Clear the cache of rendered graphics.

Definition at line 457 of file class.ilMathJax.php.

References factory().

                                : void
    {
        $image = $this->factory->image('', $this->output, $this->dpi);
        $image->clearCache();
    }

Here is the call graph for this function:

getCacheSize()

ilMathJax::getCacheSize

(

)

Get the size of the image cache.

Definition at line 449 of file class.ilMathJax.php.

References factory().

                                  : string
    {
        return $this->factory->image('', $this->output, $this->dpi)->getCacheSize();
    }

Here is the call graph for this function:

getIndependent()

static ilMathJax::getIndependent ( ilMathJaxConfig  $config, ilMathJaxFactory  $factory  )

static

Get an independent instance with a specific config for use in unit tests or on the mathjax settings page Don't use in standard cases!

Definition at line 138 of file class.ilMathJax.php.

References $config, and $factory.

Referenced by ilMathJaxSettingsGUI\editSettings(), ilMathJaxTest\testClientSideRendering(), ilMathJaxTest\testInstanceCanBeCreated(), and ilMathJaxTest\testServerSideRendering().

                                                                                             : ilMathJax
    {
        return new self($config, $factory);
    }

Here is the caller graph for this function:

getInstance()

static ilMathJax::getInstance ( )

static

Singleton: get instance for use in ILIAS requests with a config loaded from the settings.

Definition at line 123 of file class.ilMathJax.php.

Referenced by ILIAS\Wiki\Export\WikiHtmlExport\buildExportFile(), ilMathJaxSettingsGUI\clearCache(), ilMathJaxSettingsGUI\editSettings(), ILIAS\components\Export\HTML\Util\exportCOPageFiles(), ilAssSelfAssessmentQuestionFormatter\format(), ILIAS\components\ILIAS\Glossary\Table\TermListTable\getDataRetrieval(), ilPresentationTableGUI\getShortTextForTerm(), ilGlossaryTermGUI\output(), ilForumExportGUI\prepare(), ilForum\prepareText(), ilLegacyFormElementsUtil\prepareTextareaOutput(), assQuestionGUI\prepareTextareaOutput(), ilForumExportGUI\printPost(), ilForumExportGUI\printThread(), and ilPageObjectGUI\showPage().

                                        : ilMathJax
    {
        if (!isset(self::$_instance)) {
            // #37803: here we can't use ilSettingsFactory because of race conditions in ilSettingsFactory::settingsFor()
            $repo = new ilMathJaxConfigSettingsRepository(new ilSetting('MathJax'));
            self::$_instance = new self($repo->getConfig(), new ilMathJaxFactory());
        }
        return self::$_instance;
    }

Here is the caller graph for this function:

includeMathJax()

ilMathJax::includeMathJax

(

?ilGlobalTemplateInterface

$a_tpl = null

)

Include the Mathjax javascript(s) in the page template.

Definition at line 258 of file class.ilMathJax.php.

References factory().

Referenced by init().

                                                                            : ilMathJax
    {
        if ($this->config->isClientEnabled()) {
            $tpl = $a_tpl ?? $this->factory->template();

            if (!empty($this->config->getClintPolyfillUrl())) {
                $tpl->addJavaScript($this->config->getClintPolyfillUrl());
            }
            if (!empty($this->config->getClientScriptUrl())) {
                $tpl->addJavaScript($this->config->getClientScriptUrl());
            }
        }

        return $this;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

init()

ilMathJax::init

(

string

$a_purpose = self::PURPOSE_BROWSER

)

Initialize the usage for a certain purpose This must be done before any rendering call.

Definition at line 147 of file class.ilMathJax.php.

References includeMathJax(), null, setEngine(), and setRendering().

Referenced by __construct().

                                                                 : ilMathJax
    {
        // reset the class variables
        $this->engine = null;
        $this->rendering = self::RENDER_SVG_AS_XML_EMBED;
        $this->output = self::OUTPUT_SVG;
        $this->dpi = self::DEFAULT_DPI;
        $this->zoom_factor = self::DEFAULT_ZOOM;

        // try the server-side rendering first, set this engine, if possible
        if ($this->config->isServerEnabled()) {
            if ($a_purpose === self::PURPOSE_BROWSER && $this->config->isServerForBrowser()) {
                // delivering svg directly in page may be faster than loading image files
                $this->setEngine(self::ENGINE_SERVER);
                $this->setRendering(self::RENDER_SVG_AS_XML_EMBED);
            } elseif ($a_purpose === self::PURPOSE_EXPORT && $this->config->isServerForExport()) {
                // offline pages must always embed the svg as image tags
                // otherwise the html base tag may conflict with references in svg
                $this->setEngine(self::ENGINE_SERVER);
                $this->setRendering(self::RENDER_SVG_AS_IMG_EMBED);
            } elseif ($a_purpose === self::PURPOSE_PDF && $this->config->isServerForPdf()) {
                // embedded png should work in most pdf engines
                // details can be set by the rendering engine
                $this->setEngine(self::ENGINE_SERVER);
                $this->setRendering(self::RENDER_PNG_AS_IMG_EMBED);
            } elseif ($a_purpose === self::PURPOSE_DEFERRED_PDF && $this->config->isServerForPdf()) {
                // final engine and rendering is set before the pdf is created
                $this->setEngine(self::ENGINE_DEFERRED);
            }
        }

        // support client-side rendering if enabled
        if ($this->config->isClientEnabled()) {
            // included mathjax script may render code which is not found by the server-side rendering
            // see https://docu.ilias.de/goto_docu_wiki_wpage_5614_1357.html
            $this->includeMathJax();

            // set engine for client-side rendering, if server is not used for the purpose
            if (!isset($this->engine)) {
                $this->setEngine(self::ENGINE_CLIENT);
            }
        }

        // no engine available or configured
        if (!isset($this->engine)) {
            $this->engine = self::ENGINE_NONE;
        }

        return $this;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

insertLatexImages()

ilMathJax::insertLatexImages	(	string	$a_text,
		?string	$a_start = '[tex]',
		?string	$a_end = '[/tex]'
	)

Replace all tex code within given start and end delimiters in a text If client-side rendering is enabled, change the start end end delimiters to what Mathjax expects If Server-side rendering is used, replace the whole expression with delimiters by svg or image.

Parameters

string	$a_text	text to be converted
string | null	$a_start	start delimiter to be searched for
string | null	$a_end	end delimiter to be converted

Returns

string replaced text

Definition at line 283 of file class.ilMathJax.php.

References renderMathJax(), ilStr\strIPos(), ilStr\strLen(), and ilStr\subStr().

                                                                                                            : string
    {
        // don't change anything if mathjax is not configured
        if ($this->engine === self::ENGINE_NONE) {
            return $a_text;
        }

        // this is a fix for bug5362
        $a_start = str_replace("\\", "", $a_start ?? '[tex]');
        $a_end = str_replace("\\", "", $a_end ?? '[/tex]');

        // current position to start the search for delimiters
        $cpos = 0;
        // find position of start delimiter
        while (is_int($spos = ilStr::strIPos($a_text, $a_start, $cpos))) {
            // find position of end delimiter
            if (is_int($epos = ilStr::strIPos($a_text, $a_end, $spos + ilStr::strLen($a_start)))) {
                // extract the tex code inside the delimiters
                $tex = ilStr::subStr($a_text, $spos + ilStr::strLen($a_start), $epos - $spos - ilStr::strLen($a_start));

                // undo a code protection done by the deferred engine before
                if (ilStr::subStr($tex, 0, 7) === 'base64:') {
                    $tex = base64_decode(substr($tex, 7));
                }

                // omit the html newlines added by the ILIAS page editor
                $tex = str_replace(array('<br>', '<br/>', '<br />'), '', $tex);

                // tex specific replacements
                $tex = preg_replace("/\\\\([RZN])([^a-zA-Z])/", "\\mathbb{" . "$1" . "}" . "$2", $tex);

                // check, if tags go across div borders
                if (is_int(ilStr::strIPos($tex, '<div>')) || is_int(ilStr::strIPos($tex, '</div>'))) {
                    // keep the original code including delimiters, continue search behind
                    $cpos = $epos + ilStr::strLen($a_end);
                } else {
                    switch ($this->engine) {
                        case self::ENGINE_CLIENT:
                            // prepare code for processing in the browser
                            // add necessary html encodings
                            // use the configured mathjax delimiters
                            $tex = str_replace('<', '&lt;', $tex);
                            $replacement = $this->config->getClientLimiterStart() . $tex
                                . $this->config->getClientLimiterEnd();
                            break;

                        case self::ENGINE_SERVER:
                            // apply server-side processing
                            // mathjax-node expects pure tex code
                            // so revert any applied html encoding
                            $tex = html_entity_decode($tex, ENT_QUOTES, 'UTF-8');
                            $replacement = $this->renderMathJax($tex);
                            break;

                        case self::ENGINE_DEFERRED:
                            // protect code to save it for post production
                            $replacement = '[tex]' . 'base64:' . base64_encode($tex) . '[/tex]';
                            break;

                        default:
                            // keep the original
                            $replacement = $tex;
                            break;
                    }

                    // replace delimiters and tex code with prepared code or generated image
                    $a_text = ilStr::subStr($a_text, 0, $spos) . $replacement
                        . ilStr::subStr($a_text, $epos + ilStr::strLen($a_end));

                    // continue search behind replacement
                    $cpos = $spos + ilStr::strLen($replacement);
                }
            } else {
                // end delimiter position not found => stop search
                break;
            }

            if ($cpos >= ilStr::strlen($a_text)) {
                // current position at the end => stop search
                break;
            }
        }
        return $a_text;
    }

Here is the call graph for this function:

renderMathJax()

ilMathJax::renderMathJax ( string  $a_tex )

protected

Render image from tex code using the MathJax server.

Definition at line 371 of file class.ilMathJax.php.

References $default_server_options, $dpi, Vendor\Package\$e, $server, and factory().

Referenced by insertLatexImages().

                                                   : string
    {
        $options = $this->default_server_options;
        $options['math'] = $a_tex;
        $options['dpi'] = $this->dpi;

        switch ($this->output) {
            case self::OUTPUT_PNG:
                $options['svg'] = false;
                $options['png'] = true;
                $suffix = ".png";
                break;

            case self::OUTPUT_SVG:
            default:
                $options['svg'] = true;
                $options['png'] = false;
                $suffix = ".svg";
                break;
        }

        $image = $this->factory->image($a_tex, $this->output, $this->dpi);

        try {
            if (!$image->exists()) {
                $server = $this->factory->server($this->config);
                $image->write($server->call($options));
            }

            // get the image properties
            switch ($this->output) {
                case self::OUTPUT_PNG:
                    [$width, $height] = getimagesize($image->absolutePath());
                    $width = round($width * $this->zoom_factor);
                    $height = round($height * $this->zoom_factor);
                    $mime = 'image/png';
                    break;

                case self::OUTPUT_SVG:
                default:
                    $svg = simplexml_load_string(file_get_contents($image->absolutePath()));
                    $width = round($svg['width'] * $this->zoom_factor);
                    $height = round($svg['height'] * $this->zoom_factor);
                    $mime = 'image/svg+xml';
                    break;
            }

            // generate the html code
            switch ($this->rendering) {
                case self::RENDER_SVG_AS_XML_EMBED:
                    $html = $image->read();
                    break;

                case self::RENDER_SVG_AS_IMG_EMBED:
                case self::RENDER_PNG_AS_IMG_EMBED:
                    $html = '<img src="data:' . $mime . ';base64,'
                        . base64_encode($image->read())
                        . '" style="width:' . $width . '; height:' . $height . ';" />';
                    break;

                case self::RENDER_PNG_AS_FO_FILE:
                    $html = '<fo:external-graphic src="' . $image->absolutePath() . '"'
                        . ' content-height="' . $height . 'px" content-width="' . $width . 'px"></fo:external-graphic>';
                    break;

                default:
                    $html = htmlspecialchars($a_tex);
                    break;
            }
            return $html;
        } catch (Exception $e) {
            return "[TeX rendering failed: " . $e->getMessage() . htmlentities($a_tex) . "]";
        }
    }

Here is the call graph for this function:

Here is the caller graph for this function:

setDpi()

ilMathJax::setDpi

(

int

$a_dpi

)

Set the dpi of the rendered images.

Definition at line 240 of file class.ilMathJax.php.

                                      : ilMathJax
    {
        $this->dpi = $a_dpi;
        return $this;
    }

setEngine()

ilMathJax::setEngine ( string  $a_engine )

protected

Set the Rendering engine.

Definition at line 201 of file class.ilMathJax.php.

Referenced by init().

                                                  : ilMathJax
    {
        switch ($a_engine) {
            case self::ENGINE_CLIENT:
            case self::ENGINE_SERVER:
            case self::ENGINE_DEFERRED:
                $this->engine = $a_engine;
                break;
            default:
                $this->engine = self::ENGINE_NONE;
        }

        return $this;
    }

Here is the caller graph for this function:

setRendering()

ilMathJax::setRendering

(

string

$a_rendering

)

Set the image type rendered by the server.

Definition at line 219 of file class.ilMathJax.php.

Referenced by init().

                                                     : ilMathJax
    {
        switch ($a_rendering) {
            case self::RENDER_SVG_AS_XML_EMBED:
            case self::RENDER_SVG_AS_IMG_EMBED:
                $this->rendering = $a_rendering;
                $this->output = self::OUTPUT_SVG;
                break;

            case self::RENDER_PNG_AS_IMG_EMBED:
            case self::RENDER_PNG_AS_FO_FILE:
                $this->rendering = $a_rendering;
                $this->output = self::OUTPUT_PNG;
                break;
        }
        return $this;
    }

Here is the caller graph for this function:

setZoomFactor()

ilMathJax::setZoomFactor

(

float

$a_factor

)

Set the zoom factor of the rendered images.

Definition at line 249 of file class.ilMathJax.php.

                                                  : ilMathJax
    {
        $this->zoom_factor = $a_factor;
        return $this;
    }

Field Documentation

$_instance

self ilMathJax::$_instance

staticprotected

Definition at line 56 of file class.ilMathJax.php.

$config

ilMathJaxConfig ilMathJax::$config

protected

Definition at line 61 of file class.ilMathJax.php.

Referenced by __construct(), and getIndependent().

$default_server_options

array ilMathJax::$default_server_options

protected

Initial value:

= array(
        "format" => "TeX",
        "math" => '',        
        "svg" => true,
        "mml" => false,
        "png" => false,
        "speakText" => false,
        "speakRuleset" => "mathspeak",
        "speakStyle" => "default",
        "ex" => 6,
        "width" => 1000000,
        "linebreaks" => false,
    )

Definition at line 96 of file class.ilMathJax.php.

Referenced by renderMathJax().

$dpi

int ilMathJax::$dpi

protected

Definition at line 86 of file class.ilMathJax.php.

Referenced by renderMathJax().

$engine

string ilMathJax::$engine

protected

Definition at line 71 of file class.ilMathJax.php.

$factory

ilMathJaxFactory ilMathJax::$factory

protected

Definition at line 66 of file class.ilMathJax.php.

Referenced by __construct(), and getIndependent().

$output

string ilMathJax::$output = self::OUTPUT_SVG

protected

Definition at line 81 of file class.ilMathJax.php.

$rendering

string ilMathJax::$rendering = self::RENDER_SVG_AS_XML_EMBED

protected

Definition at line 76 of file class.ilMathJax.php.

$zoom_factor

float ilMathJax::$zoom_factor

protected

Definition at line 91 of file class.ilMathJax.php.

DEFAULT_DPI

const ilMathJax::DEFAULT_DPI = 150

protected

Definition at line 50 of file class.ilMathJax.php.

DEFAULT_ZOOM

const ilMathJax::DEFAULT_ZOOM = 1.0

protected

Definition at line 51 of file class.ilMathJax.php.

ENGINE_CLIENT

const ilMathJax::ENGINE_CLIENT = 'client'

Definition at line 38 of file class.ilMathJax.php.

ENGINE_DEFERRED

const ilMathJax::ENGINE_DEFERRED = 'deferred'

Definition at line 39 of file class.ilMathJax.php.

ENGINE_NONE

const ilMathJax::ENGINE_NONE = 'none'

Definition at line 40 of file class.ilMathJax.php.

ENGINE_SERVER

const ilMathJax::ENGINE_SERVER = 'server'

Definition at line 37 of file class.ilMathJax.php.

OUTPUT_PNG

const ilMathJax::OUTPUT_PNG = 'png'

protected

Definition at line 48 of file class.ilMathJax.php.

OUTPUT_SVG

const ilMathJax::OUTPUT_SVG = 'svg'

protected

Definition at line 47 of file class.ilMathJax.php.

PURPOSE_BROWSER

const ilMathJax::PURPOSE_BROWSER = 'browser'

Definition at line 31 of file class.ilMathJax.php.

Referenced by ilMathJaxSettingsGUI\editSettings().

PURPOSE_DEFERRED_PDF

const ilMathJax::PURPOSE_DEFERRED_PDF = 'deferred_pdf'

Definition at line 34 of file class.ilMathJax.php.

PURPOSE_EXPORT

const ilMathJax::PURPOSE_EXPORT = 'export'

Definition at line 32 of file class.ilMathJax.php.

Referenced by ILIAS\Wiki\Export\WikiHtmlExport\buildExportFile(), ILIAS\components\Export\HTML\Util\exportCOPageFiles(), and ilForumExportGUI\prepare().

PURPOSE_PDF

const ilMathJax::PURPOSE_PDF = 'pdf'

Definition at line 33 of file class.ilMathJax.php.

RENDER_PNG_AS_FO_FILE

const ilMathJax::RENDER_PNG_AS_FO_FILE = 'png_as_fo_file'

Definition at line 45 of file class.ilMathJax.php.

RENDER_PNG_AS_IMG_EMBED

const ilMathJax::RENDER_PNG_AS_IMG_EMBED = 'png_as_img_embed'

Definition at line 44 of file class.ilMathJax.php.

RENDER_SVG_AS_IMG_EMBED

const ilMathJax::RENDER_SVG_AS_IMG_EMBED = 'svg_as_img_embed'

Definition at line 43 of file class.ilMathJax.php.

RENDER_SVG_AS_XML_EMBED

const ilMathJax::RENDER_SVG_AS_XML_EMBED = 'svg_as_xml_embed'

Definition at line 42 of file class.ilMathJax.php.

---

The documentation for this class was generated from the following file:

• components/ILIAS/MathJax/classes/class.ilMathJax.php