resources/src/mediawiki/mediawiki.templates.js

   1 /**
   2  * @class mw.template
   3  * @singleton
   4  */
   5 ( function ( mw ) {
   6         var compiledTemplates = {},
   7                 compilers = {};
   8
   9         mw.template = {
  10                 /**
  11                  * Register a new compiler and template
  12                  * @method
  13                  * @param {String} name of compiler. Should also match with any file extensions of templates that want to use it.
  14                  * @param {Function} compiler which must implement a compile function
  15                  */
  16                 registerCompiler: function ( name, compiler ) {
  17                         if ( compiler.compile ) {
  18                                 compilers[name] = compiler;
  19                         } else {
  20                                 throw new Error( 'Template compiler must implement compile function.' );
  21                         }
  22                 },
  23                 /**
  24                  * Work out which compiler is associated with the template based on its suffix
  25                  * @method
  26                  * @param {String} templateName Name of template to add including file extension
  27                  * @return {Function} compiler
  28                  */
  29                 getCompilerFromName: function ( templateName ) {
  30                         var templateParts = templateName.split( '.' ), compiler,
  31                                 ext;
  32
  33                         if ( templateParts.length > 1 ) {
  34                                 ext = templateParts[ templateParts.length - 1 ];
  35                                 if ( compilers[ ext ] ) {
  36                                         compiler = compilers[ ext ];
  37                                 } else {
  38                                         throw new Error( 'Template compiler not found for: ' + ext );
  39                                 }
  40                         } else {
  41                                 throw new Error( 'Template has no suffix. Unable to identify compiler.' );
  42                         }
  43                         return compiler;
  44                 },
  45                 /**
  46                  * Define a template. Compiles newly added templates based on
  47                  * the file extension of name and the available compilers.
  48                  * @method
  49                  * @param {String} moduleName Name of RL module to get template from
  50                  * @param {String} templateName Name of template to add including file extension
  51                  * @param {String} markup Associated markup (html)
  52                  * @return {Function} compiled template
  53                  */
  54                 add: function ( moduleName, templateName, markup ) {
  55                         var compiledTemplate,
  56                                 compiler = this.getCompilerFromName( templateName );
  57
  58                         // check module has a compiled template cache
  59                         compiledTemplates[moduleName] = compiledTemplates[moduleName] || {};
  60
  61                         compiledTemplate = compiler.compile( markup );
  62                         compiledTemplates[moduleName][ templateName ] = compiledTemplate;
  63                         return compiledTemplate;
  64                 },
  65                 /**
  66                  * Retrieve defined template
  67                  *
  68                  * @method
  69                  * @param {string} name Name of template to be retrieved
  70                  * @return {Object} template compiler
  71                  * accepts template data object as its argument.
  72                  */
  73                 get: function ( moduleName, templateName ) {
  74                         var moduleTemplates;
  75
  76                         // check if the template has already been compiled, compile it if not
  77                         if ( !compiledTemplates[ moduleName ] || !compiledTemplates[ moduleName ][ templateName ] ) {
  78                                 moduleTemplates = mw.templates.get( moduleName );
  79                                 if ( !moduleTemplates ) {
  80                                         throw new Error( 'No templates associated with module: ' + moduleName );
  81                                 }
  82
  83                                 if ( moduleTemplates[ templateName ] ) {
  84                                         // add compiled version
  85                                         this.add( moduleName, templateName, moduleTemplates[ templateName ] );
  86                                 } else {
  87                                         throw new Error( 'Template in module ' + moduleName + ' not found: ' + templateName );
  88                                 }
  89                         }
  90                         return compiledTemplates[ moduleName ][ templateName ];
  91                 },
  92                 /**
  93                  * Wraps our template engine of choice
  94                  * @method
  95                  * @param {string} templateBody Template body.
  96                  * @param {string} compilerName The name of a registered compiler
  97                  * @return {Object} template interface
  98                  * accepts template data object as its argument.
  99                  */
 100                 compile: function ( templateBody, compilerName ) {
 101                         var compiler = compilers[ compilerName ];
 102                         if ( !compiler ) {
 103                                 throw new Error( 'Unknown compiler ' + compilerName );
 104                         }
 105                         return compiler.compile( templateBody );
 106                 }
 107         };
 108
 109         // Register basic html compiler
 110         mw.template.registerCompiler( 'html', {
 111                 compile: function ( src ) {
 112                         return {
 113                                 render: function () {
 114                                         return src;
 115                                 }
 116                         };
 117                 }
 118         } );
 119
 120 }( mediaWiki ) );