Feature Wiki

Information about planned and released features

Tabs

Server-Side MathJax Rendering

Page Overview

[Hide]

1 Requirements

ILIAS uses MathJax to render TeX formulars in different kinds of content. MatJax is confgured as a 3rd party JavaScript library that is loaded by the browser to render TeX expressions when a page is shown. This client-side rendering has two drawbacks:

  • The server generated PDF files can't show TeX formulas.
  • Pages with many TeX formulas show first the source expressions and it may take up to half a scond until the TeX is rendered. This disturbs the user, especially in e-exams.
MathJax, however, can also be installed on a server and render TeX to images there. In StudOn we use this for around a year productively.
To run a MathJax server you have to install the following components:The Installation procedure is fairly simple (August 29, 2016: see the Installation notes in ILIAS 5.2 under Administration > Third Party Software > MathJax).

This featue request proposes a second configuration option in the MathJax settings of ILIAS to specify a rendering server.It should be able to select independently whether the server-side rendering is used for browser pages, HTML export of learning modules and the generation of PDF files.

The following screenshot is a Mock-Up for these settings:

The MathJax server is able to create SVG or PNG graphics. The output format for browser and HTML export should be the scalable SVG. The output format for PDF generation depends on the capability of the PDF engine and should be defined by the PDF service.

Rendered SVG graphics can either be embedded on an HTML page as <svg> element or referenced by an <img> tag. PNG images can also be embedded as base64 encoded binary in the <img> tag or referenced in the src attribute. For the browser the graphics should be referenced if they are cached on the server. For export to HTML they should be created as graphic files and referenced in the HTML code. For PDF generation the actual PDF service should decide on embedding or reference (embedding makes the callof an external PDF renderer easier).

I also propose a caching of rendered TeX expressions on the server side. In our implementation we create an MD5 hash from the original TeX expression and use this for the file paths in a cache directory within the ILIAS web data directory. If a file for the hash of a TeX expression is found, it is take from there, otherwise it is rendered by the server and stored there. If, for example a print view of a test is generated, all TeX expressions in the questions will be rendered at once and the participants wil later quickly get the cached files.

2 Additional Information

3 Discussion

Killing, Alexander [alex], 2 June 2016: I support this request.

Bogen, Christian [bogen], 02.06.2016: Sounds very desireable, indeed.

JourFixe, ILIAS [jourfixe], June 06, 2016: We highly appreciate this suggestion and schedule it for 5.2. "Cache graphics" does not need a setting but should be done always. The combination of rendering options requires an early initialisation of the rendering purpose in a request for PDF generation or HTML export. This has to be done by the responsible maintainers for their component. Fred will offer the necessary code changes and offers pull requests for them.

Killing, Alexander [alex], 24 Aug 2016: Great news! I approve all the changes in my and Jörgs components. However in my opinion the main implementation should be moved out of the "Utilities" directory into a proper subdirectory and build a new service with a responsible maintainer.

Neumann, Fred [fneumann], Mai 23, 2018
A follow-up feature request Configurable Delimiters for MathJax-Service proposes a solution for the problem that the standard MathJax delimiters \( and \) are used at places where ILIAS oroginally expects other delimiters.

4 Implementation

Neumann, Fred [fneumann], August 29, 2016

The feature is committed for ILIAS 5.2. All ilUtil functions for TeX rendering are migrated to a separate class ilMathJax in a new MathJax service. They still work as legacy wrappers but are marked as deprecated. The new class is normally used like this:

        include_once './Services/MathJax/classes/class.ilMathJax.php';
        $text = ilMathJax::getInstance()->insertLatexImages($text);

This replaces all former calls of ilUtil::insertLatexImages() with the same parameters.

A special Initialisation has to be done for HTML exports or PDF generation, because their support by the server-side rendering can be switched in the administration and they need different types of output:

  • The browser view will use embedded <svg> code.
  • An HTML export must encode the SVG as base64 in the src-attribute of an img tag. Otherwise the SVG code may not work with a base tag set in the header of the exported HTML page.
  • PDF generation (TCPDF and XSL-FO) needs the rendered formula as PNG image.
As the call of insertLatexImages() is done at several places in the code, the rendering purpose has to be initialized at the beginning of a request, e.g.:

        ilMathJax::getInstance()->init(ilMathJax::PURPOSE_EXPORT);
// or
        ilMathJax::getInstance()->init(ilMathJax::PURPOSE_PDF);

In ilForumExportGUI this is done in a new function prepare(). In ilPDFGenerationGUI this is done in a new function prepareGeneration();

Another special case is the PDF generation with XSL-FO. Here the insertLatexImages() has to be called between the XSL Transformation and RPC call for PDF generation because the rendered PNG has to be included with a special fo tag. For this case a too early rendering has first to be suppressed with  ilMathJax::getInstance()->init(ilMathJax::PURPOSE_DEFERRED_PDF); After the XSL transformation ilMathax can be re-initialized to render TeX for FO processing:

$fo_string = ilMathJax::getInstance()
->init(ilMathJax::PURPOSE_PDF)
->setRendering(ilMathJax::RENDER_PNG_AS_FO_FILE)
->insertLatexImages($fo_string);

Please note that the generated fo tags refer the PNG images with their absolute file paths, because the ILIAS Java server seems not to work with URL referenced images or base64 encoded image data. As a consequence he Java server to run an a machine with access to the file system of the ILIAS repository, e.g. by nfs.

See the Test Cases for a list of Export / PDF generation requests that are supported by the new service.

ilMathJax::insertLatexImages() is currently called from the following places in ILIAS 5.3  - with default or specific arguments:

Bibliographc
ilBibliographicDetailsGUI::prepareLatex() - default
 
Forum
ilForum::prepareText() - <span class="latex"> and [tex]
	
Glossary
ilPresentationListTableGUI::fillRow() - default or [tex]
ilTermListTableGUI() - default
 
Scorm2004
ilSCORM2004Export::buildExportFilePDF() - default	
 
Survey
ilSurveyEditorGUI::printViewObject() - default
 
QuestionPool/Learning Module
ilAssSelfAssessmentQuestionFormatter::format() - <span class="latex"> and [tex]
 
Administration
ilObjExternalToolSettingsGUI::editMathJaxObject() - [tex]
 
Certificate
ilCertificate::outCertificate() - default
 
CoPage
ilPageObjectGUI::showPage() - default
 
Utilities
ilUtil::prepreTextareaOutput() - <span class="latex"> and [tex]

Test Cases

Test cases finished at 2016-08-28 by Neumann, Fred [fneumann] (Test suite MathJax)

  • Administration Settings
    • C13004 MathJax im Browser aktivieren
    • C13005 MathJax im Server aktualisieren
    • C13006 MathJax-Cache leeren
  • MathJax im Blog
    • C13007 TeX im Blog anzeigen
    • C13008 TeX im HTML-Export eines Blogs
  • MathJax im Glossar
    • C13009 TeX im Glossar anzeigen
    • C13010 TeX im HTML-Export eines Glossars
  • MathJax im Wiki
    • C13011 TeX im Wiki anzeigen
    • C13012 TeX im HTML-Export eines Wikis
    • C13013 TeX im PDF-Export eines Wikis
  • MathJax im Forum
    • C13030 TeX im Forum anzeigen
    • C13031 TeX in der Druckansicht anzeigen
    • C13032 TeX im HTML-Export anzeigen
  • MathJax im ILIAS-Lernmodul
    • C13033 TeX im ILIAS-Lernmodul anzeigen
    • C13034 TeX im HTML-Export anzeigen
    • C13035 TeX im SCORM-Export anzeigen

  • MathJax im SCORM 2004-Lernmodul
    • C13050 TeX im SCORM-Lernmodul anzeigen
    • C13051 TeX im SCORM-Export anzeigen
    • C13052 TeX im HTML-Export anzeigen
    • C13053 TeX im PDF-Export anzeigen
    • C13054 TeX im HTML-Export anzeigen
  • MathJax im Zertifikat
    • C13055 MathJax in der Zertifikats-Vorschau anzeigen
    • C13056 MathJax im Zertifikat anzeigen
  • MathJax in der Umfrage
    • C13057 TeX in der Umfrage anzeigen
    • C13058 TeX im PDF-Export anzeigen
  • MathJax im Test
    • C13059 TeX im Test anzeigen
    • C13060 TeX im PDF-Export der Druckansicht
    • C13061 TeX im PDF-Export der Vorschau
    • C13062 TeX in den Testergebnissen anzeigen
    • C13063 TeX im PDF-Export aus Teilnehmerliste

Approval

Approved at 2016-08-25 by Neumann, Fred [fneumann].

Last edited: 23. May 2018, 13:48, Neumann, Fred [fneumann]