resources/src/mediawiki.template.js

   1 /**
   2  * @class mw.template
   3  * @singleton
   4  */
   5 ( function () {
   6         var compiledTemplates = {},
   7                 compilers = {};
   8
   9         mw.template = {
  10                 /**
  11                  * Register a new compiler.
  12                  *
  13                  * A compiler is any object that implements a compile() method. The compile() method must
  14                  * return a Template interface with a method render() that returns HTML.
  15                  *
  16                  * The compiler name must correspond with the name suffix of templates that use this compiler.
  17                  *
  18                  * @param {string} name Compiler name
  19                  * @param {Object} compiler
  20                  */
  21                 registerCompiler: function ( name, compiler ) {
  22                         if ( !compiler.compile ) {
  23                                 throw new Error( 'Compiler must implement a compile method' );
  24                         }
  25                         compilers[ name ] = compiler;
  26                 },
  27
  28                 /**
  29                  * Get the name of the associated compiler based on a template name.
  30                  *
  31                  * @param {string} templateName Name of a template (including suffix)
  32                  * @return {string} Name of a compiler
  33                  */
  34                 getCompilerName: function ( templateName ) {
  35                         var nameParts = templateName.split( '.' );
  36                         if ( nameParts.length < 2 ) {
  37                                 throw new Error( 'Template name must have a suffix' );
  38                         }
  39                         return nameParts[ nameParts.length - 1 ];
  40                 },
  41
  42                 /**
  43                  * Get a compiler via its name.
  44                  *
  45                  * @param {string} name Name of a compiler
  46                  * @return {Object} The compiler
  47                  */
  48                 getCompiler: function ( name ) {
  49                         var compiler = compilers[ name ];
  50                         if ( !compiler ) {
  51                                 throw new Error( 'Unknown compiler ' + name );
  52                         }
  53                         return compiler;
  54                 },
  55
  56                 /**
  57                  * Register a template associated with a module.
  58                  *
  59                  * Precompiles the newly added template based on the suffix in its name.
  60                  *
  61                  * @param {string} moduleName Name of the ResourceLoader module the template is associated with
  62                  * @param {string} templateName Name of the template (including suffix)
  63                  * @param {string} templateBody Contents of the template (e.g. html markup)
  64                  * @return {Object} Compiled template
  65                  */
  66                 add: function ( moduleName, templateName, templateBody ) {
  67                         // Precompile and add to cache
  68                         var compiled = this.compile( templateBody, this.getCompilerName( templateName ) );
  69                         if ( !compiledTemplates[ moduleName ] ) {
  70                                 compiledTemplates[ moduleName ] = {};
  71                         }
  72                         compiledTemplates[ moduleName ][ templateName ] = compiled;
  73
  74                         return compiled;
  75                 },
  76
  77                 /**
  78                  * Get a compiled template by module and template name.
  79                  *
  80                  * @param {string} moduleName Name of the module to retrieve the template from
  81                  * @param {string} templateName Name of template to be retrieved
  82                  * @return {Object} Compiled template
  83                  */
  84                 get: function ( moduleName, templateName ) {
  85                         var moduleTemplates;
  86
  87                         // Try cache first
  88                         if ( compiledTemplates[ moduleName ] && compiledTemplates[ moduleName ][ templateName ] ) {
  89                                 return compiledTemplates[ moduleName ][ templateName ];
  90                         }
  91
  92                         moduleTemplates = mw.templates.get( moduleName );
  93                         if ( !moduleTemplates || !moduleTemplates[ templateName ] ) {
  94                                 throw new Error( 'Template ' + templateName + ' not found in module ' + moduleName );
  95                         }
  96
  97                         // Compiled and add to cache
  98                         return this.add( moduleName, templateName, moduleTemplates[ templateName ] );
  99                 },
 100
 101                 /**
 102                  * Compile a string of template markup with an engine of choice.
 103                  *
 104                  * @param {string} templateBody Template body
 105                  * @param {string} compilerName The name of a registered compiler
 106                  * @return {Object} Compiled template
 107                  */
 108                 compile: function ( templateBody, compilerName ) {
 109                         return this.getCompiler( compilerName ).compile( templateBody );
 110                 }
 111         };
 112
 113         // Register basic html compiler
 114         mw.template.registerCompiler( 'html', {
 115                 compile: function ( src ) {
 116                         return {
 117                                 render: function () {
 118                                         return $( $.parseHTML( src.trim() ) );
 119                                 }
 120                         };
 121                 }
 122         } );
 123
 124 }() );