path: root/files/es/mdn/tools/kumascript/index.html

---
title: Introducción a KumaScript
slug: MDN/Tools/KumaScript
translation_of: MDN/Tools/KumaScript
original_slug: MDN/Tools/Introduction_to_KumaScript
---
<div>{{MDNSidebar}}</div>

<div>{{draft}}</div>

<h2 id="Vistazo_general">Vistazo general</h2>

<p>En el verano de 2012, MDN  cambió a una nueva plataforma wiki llamada <a class="link-https" href="https://wiki.mozilla.org/MDN/Kuma" title="https://wiki.mozilla.org/MDN/Kuma">Kuma</a>. Esta reemplaza el lenguaje de plantilla <a class="external" href="http://developer.mindtouch.com/en/docs/DekiScript" title="http://developer.mindtouch.com/en/docs/DekiScript">DekiScript</a> con un nuevo sistema llamado <a class="link-https" href="https://github.com/mozilla/kumascript" title="https://github.com/mozilla/kumascript">KumaScript</a>. KumaScript se alimenta de JavaScript del lado del servidor, usando <a class="external" href="http://nodejs.org/" title="http://nodejs.org/">Node.js</a>. Este artículo provee informaciónde cómo usar KumaScript y cómo actualizar scripts migrados parcialmente desde MindTouch.</p>

<p>Para detalles y preguntas frecuentes sobre KumaScript, mira el <a href="https://vreplay.mozilla.com/replay/showRecordDetails.html?sortBy=date&amp;viewCount=1&amp;currentPage=1&amp;groupBy=combo&amp;roomFilter=&amp;usernameFilter=&amp;searchFilter=&amp;usernameFullFilter=&amp;myManager=-1&amp;adminManager=0&amp;webCast=0&amp;command=&amp;recId=1082&amp;auxMessage=&amp;auxMessage1=&amp;lang=en&amp;langChanged=&amp;tenantFilter=&amp;securityTab=" style="line-height: 1.5;">KumaScript Fireside Chat</a> del equipo de desarrolladores<span style="line-height: 1.5;"> MDN</span><span style="line-height: 1.5;">.</span></p>

<p><span style="">¿Qué es KumaScript?</span></p>

<ul>
 <li>Una forma de reutilizar y localizar contenido que aparece repetidamente entre los documentos (por ejemplo, rótulos de compatibilidad, navegación de secciones, carteles de advertencia).</li>
 <li>Una manera de construir documentos sacados de otros documentos.</li>
 <li>Una manera de buscar e incluir contenido de otros sitios web y servicios (por ejemplo, Bugzilla).</li>
</ul>

<h3 id="¿Qué_no_es_KumaScript">¿Qué no es KumaScript?</h3>

<ul>
 <li>KumaScript no soporta scripts interactivos del tipo que pueden aceptar las incripciones por formulario.</li>
 <li>KumaScript no tiene acceso a bases de datos, archivos, ni a cualquier otra forma de guardar información persistentemente.</li>
 <li>KumaScript no soporta la personalización basada en el usuario que tiene la sesión abierta.</li>
 <li>KumaScript no tiene acceso a información de usuario, sólo al contenido y a los metadatos de una wiki que se esté visualizando.</li>
</ul>

<h2 id="Aspectos_básicos">Aspectos básicos</h2>

<p>KumaScript funciona permitiendo a <em>wiki de confianza</em> escribir <a class="link-https" href="https://github.com/visionmedia/ejs" title="https://github.com/visionmedia/ejs">plantillas JavaScript ensambladas</a>. Estas plantillas pueden ser invocadas en el contenido del documento por cualquier editor <em>wiki</em> mediante el uso de <a class="link-https" href="/en-US/docs/KumaTests/hello_test?raw=1" title="/en-US/docs/KumaTests/hello_test?raw=1">macros</a>.</p>

<table style="display: block;">
 <tbody>
  <tr>
   <td>
    <p>Una <a class="link-https" href="/en-US/docs/Template:hello" title="/en-US/docs/Template:hello">plantilla</a> se vé así:</p>
   </td>
   <td>
    <p>Una <a class="link-https" href="/en-US/docs/KumaTests/hello_test?raw=1" title="/en-US/docs/KumaTests/hello_test?raw=1">macro</a> se vé así:</p>
   </td>
   <td>
    <p>El <a class="link-https" href="/en-US/docs/KumaTests/hello_test" title="/en-US/docs/KumaTests/hello_test">resultado de una macro</a> sale así:</p>
   </td>
  </tr>
  <tr>
   <td>
    <pre class="notranslate">
&lt;% for (var i = 0; i &lt; $0; i++) { %&gt;
Hello #&lt;%= i %&gt;
&lt;% } %&gt;</pre>
   </td>
   <td>
    <pre class="notranslate">
\{{ hello("3") }}
</pre>
   </td>
   <td>
    <pre class="notranslate">
Hello #0
Hello #1
Hello #2</pre>
   </td>
  </tr>
 </tbody>
</table>

<h3 id="Sintaxis_de_una_macro">Sintaxis de una macro</h3>

<p>Las plantillas KumaScript se invocan en el contenido del documento con macros, como esta:</p>

<pre class="notranslate">\{{ templateName("arg0", "arg1", ..., "argN") }}
</pre>

<p>La sintaxis de una Macro se compone de estas reglas:</p>

<ul>
 <li>Las Macros comienzan y terminan con los caracteres <code>\{{</code> y <code>}}</code>.</li>
 <li>La primera parte de la macro es el nombre de la plantilla. Esta corresponde a una wiki en <code>/en-US/docs/Template:{name}</code>. Editar y crear estas páginas requiere un permiso especial que los administradores pueden otorgar a editores de confianza.</li>
 <li>Una plantilla puede aceptar parámetros, y esta lista de parámetroa comienza y termina con paréntesis.</li>
 <li>En una plantilla, los parámetros ingresados están disponibles dentro de la macro como las variables <code>$0</code>, <code>$1</code>, <code>$2</code>, y así sucesivamente.</li>
 <li>Todos los parámetros no numéricos deber ir entre comillas. Los números pueden quedar sin ellas.</li>
 <li>La lista completa de parámetros también está disponible en una plantilla como la variable <code>arguments</code>.</li>
</ul>

<h4 id="Usando_JSON_parámetro_de_macro">Usando JSON parámetro de macro</h4>

<p>Hay una característica semi-experimental disponible para las macros. Puedes proveerlas de un objeto JSON como primero y único parámetro, así:</p>

<pre class="notranslate">\{{ templateName({ "Alpha":"one", "Beta":["a","b","c"], "Foo":"http:\/\/mozilla.org\/" }) }}
</pre>

<p>Los datos de esta macro estarán disponibles en un código de plantilla como un objeto en el argumento <code>$0</code> (por ejemplo, <code>$0.Alpha</code>, <code>$0.Beta</code>, <code>$0.Foo</code>). Esto también te permite expresar estructuras de datos complejos en los parámetros de macro que son difíciles o imposibles de hacer con una simple lista de parámetros.</p>

<p>Nota que el estilo de este parámetro es muy complejo. Se debe adherir exactamente a la <a href="http://json.org/" title="http://json.org/">sintaxis JSON</a>, que tiene algunas exigencias escurridizas que son fáciles de pasar por alto (por ejemplo, todas las barras (/) llevan escapes). Cuando haya dudas, <a href="http://jsonlint.com/" title="http://jsonlint.com/">intenta ejecutar tu JSON con un validador</a>.</p>

<h4 id="Cómo_escribir">Cómo escribir "\{{"</h4>

<p>Como la secuencia de caracteres "<code>\{{</code>" se usa para indicar el comienzo de una macro, puede ser un problema si justo quieres usar "<code>\{{</code>" and "<code>}}</code>" como texto de una página. Probablemente dará un mensaje de error <code>DocumentParsingError</code>.</p>

<p>En este caso, puedes escapar la primer llave con una barra invertida, así: <code>\\{</code></p>

<h3 id="Sintaxis_de_la_plantilla">Sintaxis de la plantilla</h3>

<p>Las plantillas KumaScript son procesadas por un <a class="link-https" href="https://github.com/visionmedia/ejs" title="https://github.com/visionmedia/ejs">motor de plantillas JavaScript ensamblado</a> con estas simples reglas:</p>

<ul>
 <li>La mayoría del texto es tratado como salida e incluido en el flujo de salida.</li>
 <li>Las expresiones y variables JavaScript pueden insertarse en el flujo de salida con estos bloques:
  <ul>
   <li><code>&lt;%= expr %&gt;</code> — el valor de la expresión JavaScript es escapado por el HTML antes de incluirse en la salida (por ejemplo, caracteres como <code>&lt;</code> y <code>&gt;</code>  se convierten en <code>&amp;lt;</code> y <code>&amp;gt;</code>).</li>
   <li><code>&lt;%- expr %&gt;</code> — el valor de una expresión JavaScript es incluído en la salida pero sin escape. (usa esto si quieres construir etiquetas HTML o usar los resultados de otra plantilla que puedan incluir etiquetas HTML.)</li>
   <li>Es un error incluir punto y coma dentro de los bloques.</li>
  </ul>
 </li>
 <li>Cualquier cosa dentro de un bloque <code>&lt;% %&gt;</code>  se interpreta como JavaScript. Esto puede incluir bucles, condiciones, etc.</li>
 <li>No hay nada dentro de un bloque <code>&lt;% %&gt;</code> que pueda contribuir al flujo de salida. Pero puedes hacer la transición desde el modo JS al modo de salida usando <code>&lt;% %&gt; </code>—Por ejemplo:
  <pre class="notranslate">&lt;% for (var i = 0; i &lt; $0; i++) { %&gt;
Hello #&lt;%= i %&gt;
&lt;% } %&gt;
</pre>

  <p>Nota como el JS está contenido entre <code>&lt;% ... %&gt;</code>, y la salida va en el espacio entre <code>%&gt; ... &lt;%</code>. El bucle <em>for</em> en JS puede comenzar en un bloque <code>&lt;% %&gt;</code> , luego el flujo de salida, y terminar en un segundo bloque JS <code>&lt;% %&gt;</code>.</p>
 </li>
 <li>For more details on EJS syntax, <a class="link-https" href="https://github.com/visionmedia/ejs" title="https://github.com/visionmedia/ejs">check out the upstream module documentation</a>.</li>
</ul>

<h2 id="Características_avanzadas">Características avanzadas</h2>

<p>Más allá de los aspectos básicos, el sistema KumaScript ofrece algunas características avanzadas.</p>

<h3 id="Variables_de_entorno">Variables de entorno</h3>

<p>Cuando la wiki hace una llamada al servicio KumaScript, <a class="link-https" href="https://github.com/mozilla/kuma/blob/master/apps/wiki/kumascript.py#L130" title="https://github.com/mozilla/kuma/blob/master/apps/wiki/views.py#L537">pasa por una part del contexto del documento actual</a> que KumaScript pone a disposición de las plantillas como variables:</p>

<dl>
 <dt><code>env.path</code></dt>
 <dd>La ruta del documento wiki actual</dd>
 <dt><code>env.url</code></dt>
 <dd>La URL completa del documento wiki actual</dd>
 <dt><code>env.id</code></dt>
 <dd>Un ID único corto para el documento wiki actual</dd>
 <dt><code>env.files</code></dt>
 <dd>Un arreglo de archivos adjuntos para el documento wiki actual. Cada objeto en el arreglo se describe como {{ anch("File objects") }} debajo</dd>
 <dt><code>env.review_tags</code></dt>
 <dd>Un arreglo con las etiquetas de revisión del artículo ("technical", "editorial", etc.)</dd>
 <dt><code>env.locale</code></dt>
 <dd>El sitio del documento wiki actual</dd>
 <dt><code>env.title</code></dt>
 <dd>El título del documento wiki actual</dd>
 <dt><code>env.slug</code></dt>
 <dd>Una URL amigable del documento wiki actual</dd>
 <dt><code>env.tags</code></dt>
 <dd>Una lista de nombers de etiquetas para el documento wiki actual</dd>
 <dt><code>env.modified</code></dt>
 <dd>El último timestamp modificado para el documento wiki actual</dd>
 <dt><code>env.cache_control</code></dt>
 <dd><code>El encabezado Cache-Control</code> henviado en la solicitud para el documento wiki actual, útil para decidir si invalidar los caches</dd>
</dl>

<h4 id="Objetos_de_archivos">Objetos de archivos</h4>

<p>Cada objeto de archivo tiene los siguientes campos:</p>

<dl>
 <dt><code>title</code></dt>
 <dd>El título del archivo adjunto</dd>
 <dt><code>description</code></dt>
 <dd>Una descripción textual de la revisión actual del archivo</dd>
 <dt><code>filename</code></dt>
 <dd>El nombre del archivo</dd>
 <dt><code>size</code></dt>
 <dd>El tamaños del archivo en bytes</dd>
 <dt><code>author</code></dt>
 <dd>El nombre de usuario de la persona que subió el archivo</dd>
 <dt><code>mime</code></dt>
 <dd>El tipo MIME del archivo</dd>
 <dt><code>url</code></dt>
 <dd>La URL en la que se puede encontrar el archivo</dd>
</dl>

<h4 id="Trabajando_con_listas">Trabajando con listas</h4>

<p>Las variables <code>env.tags</code> y <code>env.review_tags</code> devuelven colecciones de etiqutas. Puedes trabajar con estas de varias maneras, por supuesto, pero aquí se dan un par de sugerencias.</p>

<h5 id="Buscar_si_se_colocó_una_etiqueta_específica">Buscar si se colocó una etiqueta específica</h5>

<p>Se puede buscar si una etiqueta específica existe en una página, así:</p>

<pre class="brush: js notranslate">if (env.tags.indexOf("tag") != −1) {
  // The page has the tag "tag"
}
</pre>

<h5 id="Iterar_recorrer_todas_las_etiquetas_de_la_página">Iterar (recorrer) todas las etiquetas de la página</h5>

<p>Se pueden recorrer todas las etiquetas de la página, así:</p>

<pre class="brush: js notranslate">env.tag.forEach(function(tag) {
  // haz cualquier cosa que necesites, tal como:
  if (tag.indexOf("a") == 0) {
    // esta etiqueta empieza con "a" - woohoo!
  }
});</pre>

<h3 id="APIs_y_Módulos">APIs y Módulos</h3>

<p>KumaScript ofrece algunas APIs de utilidad incorporadas, como también la capacidad para definir nuevas APIs en módulos editables como documentos wiki.</p>

<h4 id="Métodos_incorporados">Métodos incorporados</h4>

<p>Es probable que esta documentación mantenida manualmente quede desactualizada con respecto al código. Teniendo en cuanta eso, <a class="link-https" href="https://github.com/mozilla/kumascript/blob/master/lib/kumascript/api.js#L208" title="https://github.com/mozilla/kumascript/blob/master/lib/kumascript/api.js#L208">siempre puedes verificar el último estado de las APIs incorporadas en la fuente de KumaScript</a>. Pero hay una selección de métodos útiles expuestos a plantillas:</p>

<dl>
 <dt><code>md5(string)</code></dt>
 <dd>Devuelve un resumen de hexadecimal MD5 de determinada cadena.</dd>
 <dt><code>template("name", ["arg0", "arg1", ..., "argN"])</code></dt>
 <dd>Ejecuta y devuelve el resultado de las plantillas mencionadas con la lista de parámetros provistos.</dd>
 <dd>Utilizado en plantillas así: <code>&lt;%- template("warning", ["foo", "bar", "baz"]) %&gt;</code>.</dd>
 <dd>Esta es una función JavaScript. Así que, si uno de los parámetroses una variable arg como $2, no lo pongas entre comillas. Así: <code>&lt;%- template("warning", [$1, $2, "baz"]) %&gt;</code>. Si necesitas llamar otra plantilla desde el interior de un bloque e código, no uses <code>&lt;%</code> ... <code>%&gt;</code>. Ejemplo: <code>myvar = "&lt;li&gt;" + template("LXRSearch", ["ident", "i", $1]) + "&lt;/li&gt;";</code></dd>
 <dt><code>require(name)</code></dt>
 <dd>Carga otra plantilla como un módulo. Cualquier resultadu es ignorado. Devuelce cualquier cosa asignada a <code>module.exports</code> en la plantilla.</dd>
 <dd>Utilizado en plantillas así: <code>&lt;% var my_module = require('MyModule'); %&gt;</code>.</dd>
 <dt><code>cacheFn(key, timeout, function_to_cache)</code></dt>
 <dd>Usando la key y duración de entrada de caché proporcionadas, cachea los resultados de la función proporcionada. Prioriza el valor de <code>env.cache_control</code> para invalidar el cache en <code>no-cache</code>, que puede ser enviado por un usuario logueado  que tipee shift-refresh.</dd>
 <dt><code>request</code></dt>
 <dd>Acceso al <a class="link-https" href="https://github.com/mikeal/request" title="https://github.com/mikeal/request"><code>mikeal/request</code></a>, una librería para hacer consultas HTTP. Usar este módulo en las plantillas KumaScriptno es muy amigable, así que quizá desees envolver uso en APIs de módulo que simplifiquen las cosas.</dd>
</dl>

<h4 id="Módulos_de_API_incorporados">Módulos de API incorporados</h4>

<p>Sólo hay una API incorporada por el momento, en el espacio de nombres <code>kuma</code>:</p>

<dl>
 <dt><code>kuma.htmlEscape(string)</code></dt>
 <dd>Escapa los caracteres <code>&amp;, &lt;, &gt;, "</code> a <code>&amp;amp, &amp;lt;, &amp;gt;, &amp;quot;</code>, respectivamente.</dd>
 <dt> </dt>
 <dt><code>kuma.include(path)</code></dt>
 <dd>Incluye contenido de la página en la ruta proporcionada. Cacheo pesado.</dd>
</dl>

<dl>
 <dt><code>kuma.pageExists(path)</code></dt>
 <dd>Indica si existe la página en la ruta proporcionada. Cacheo pesado.</dd>
</dl>

<h4 id="Creando_módulos">Creando módulos</h4>

<p>Usando el mátodo incorporado <code>require()</code>, puedes cargar una plantilla como módulo para compartir variables y métodos comunes entre plantillas. Un módulo puede definirse como una plantilla de la siguiente manera:</p>

<pre class="notranslate">&lt;%
module.exports = {
    add: function (a, b) {
        return a + b;
    }
}
%&gt;
</pre>

<p>Asumiendo que esta plantilla está guardada como <code>/en-US/docs/Template:MathLib</code>, puedes utilizarla en otra plantilla, así:</p>

<pre class="notranslate">&lt;%
var math_lib = require("MathLib");
%&gt;
El resultado de 2 + 2 = &lt;%= math_lib.add(2, 2) %&gt;
</pre>

<p>Y, el resultado de esta plantilla será:</p>

<pre class="notranslate">el resultado de 2 + 2 = 4
</pre>

<h4 id="Módulos_cargados_automáticamente">Módulos cargados automáticamente</h4>

<p>Hay un grupo de módulos editables como plantillas wiki que se cargan automáticamente y quedan disponibles para cada plantilla. Este grupo está definido en el archivo de configuración para el servicio KumaScript. Cualquier cambio a este requiere un bug IT para editar la configuración y el reinicio del servicio.</p>

<p>Para la mayor parte, estos intentos de proveer sustitutos para stand-ins for legacy DekiScript features to ease template migration. But, going forward, these can be used to share common variables and methods between templates:</p>

<ul>
 <li><code>mdn.*</code> - <a class="link-https" href="/en-US/docs/Template:MDN:Common" title="/en-US/docs/Template:MDN:Common">Template:MDN:Common</a></li>
 <li><code>Culture.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Culture" title="/en-US/docs/Template:DekiScript:Culture">Template:DekiScript:Culture</a></li>
 <li><code>Date.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Date" title="/en-US/docs/Template:DekiScript:Date">Template:DekiScript:Date</a></li>
 <li><code>Json.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Json" title="/en-US/docs/Template:DekiScript:Json">Template:DekiScript:Json</a></li>
 <li><code>List.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:List" title="/en-US/docs/Template:DekiScript:List">Template:DekiScript:List</a></li>
 <li><code>Map.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Map" title="/en-US/docs/Template:DekiScript:Map">Template:DekiScript:Map</a></li>
 <li><code>Meta.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Meta" title="/en-US/docs/Template:DekiScript:Meta">Template:DekiScript:Meta</a></li>
 <li><code>Num.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Num" title="/en-US/docs/Template:DekiScript:Num">Template:DekiScript:Num</a></li>
 <li><code>Page.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Page" title="/en-US/docs/Template:DekiScript:Page">Template:DekiScript:Page</a></li>
 <li><code>String.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:String" title="/en-US/docs/Template:DekiScript:String">Template:DekiScript:String</a></li>
 <li><code>Uri.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Uri" title="/en-US/docs/Template:DekiScript:Uri">Template:DekiScript:Uri</a></li>
 <li><code>Web.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Web" title="/en-US/docs/Template:DekiScript:Web">Template:DekiScript:Web</a></li>
 <li><code>Wiki.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Wiki" title="/en-US/docs/Template:DekiScript:Wiki">Template:DekiScript:Wiki</a></li>
 <li><code>Xml.*</code> - <a class="link-https" href="/en-US/docs/Template:DekiScript:Xml" title="/en-US/docs/Template:DekiScript:Xml">Template:DekiScript:Xml</a></li>
</ul>

<p>The best way to see the current state and offerings of these modules is to <a class="link-https" href="/en-US/docs/tag/dekiscript" title="/en-US/docs/tag/dekiscript">take a look at their source directly</a>.</p>

<p><strong>Note:</strong> You might notice that the DekiScript modules use a built-in method named <code>buildAPI()</code>, like so:</p>

<pre class="notranslate">&lt;% module.exports = buildAPI({
    StartsWith: function (str, sub_str) {
        return (''+str).indexOf(sub_str) === 0;
    }
}); %&gt;
</pre>

<p>The reason for this is because DekiScript is case-insensitive when it comes to references to API methods, whereas JavaScript is strict about uppercase and lowercase in references. So, <code>buildAPI()</code> is a hack to try to cover common case variations in DekiScript calls found in legacy templates.</p>

<p>With that in mind, please do not use <code>buildAPI()</code> in new modules.</p>

<h2 id="Tips_and_caveats">Tips and caveats</h2>

<h3 id="Debugging">Debugging</h3>

<p>A useful tip when debugging. You can use the <code>log.debug()</code> method to output text to the scripting messages area at the top of the page that's running your template. Note that you need to be really sure to remove these when you're done debugging, as they're visible to all users! To use it, just do something like this:</p>

<pre class="notranslate">&lt;%- log.debug("Some text goes here"); %&gt;
</pre>

<p>You can, of course, create more complex output using script code if it's helpful.</p>

<h3 id="Limitations_of_content_migration_from_MindTouch">Limitations of content migration from MindTouch</h3>

<p>When we make the move to Kuma, we will migrate content from the old MindTouch-based wiki to the new Kuma-based one. This script will do some basic work to attempt to convert scripts. But, there are many common code patterns that migration can't fix.</p>

<p>So, this means that we'll need human intervention to carry template scripts over the rest of the way to being functional.</p>

<p>To find templates in need of review and repair, <a class="link-https" href="/en-US/docs/needs-review/template" title="/en-US/docs/needs-review/template">check here</a>: <a class="link-https" href="/en-US/docs/needs-review/template" rel="freelink">/en...eview/template</a>.</p>

<p>To find examples of templates that have already been repaired, <a class="link-https" href="/en-US/docs/tag/ks-fixed" title="/en-US/docs/tag/ks-fixed">check here</a>: <a class="link-https" href="/en-US/docs/tag/ks-fixed" rel="freelink">/en...s/tag/ks-fixed</a>.</p>

<p>Check the <a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=714804">template usage stats bug</a> file attachments to help prioritize templates to fix. If you know your way around <code>gzip</code> and <code>grep</code>, <a class="link-https" href="https://bugzilla.mozilla.org/attachment.cgi?id=591545" title="https://bugzilla.mozilla.org/attachment.cgi?id=591545">this attachment</a> (a 1.5MB tab-delimited file listing template/document pairs) can help tell you what templates are used on which pages.</p>

<p>As you repair templates, please uncheck the "Template" review checkbox and add the tag "ks-fixed", which will keep the above lists accurate.</p>

<p>You can also find templates in need of repair by simply browsing through wiki content and spotting where content looks garbled with code or otherwise incorrect. Editing the page should show you the name of a macro that's in need of help. You may also see scripting errors on pages, which should offer editing links to the templates causing issues.</p>

<h3 id="Changing_Locale_Identifiers">Changing Locale Identifiers</h3>

<p>The identifiers for various locales have changed from MindTouch to Kuma:</p>

<ul>
 <li><code>en</code> -&gt; <code>en-US</code></li>
 <li><code>cn</code> -&gt; <code>zh-CN</code></li>
 <li><code>zh_cn</code> -&gt; <code>zh-CN</code></li>
 <li><code>zh_tw</code> -&gt; <code>zh-TW</code></li>
 <li><code>pt</code> -&gt; <code>pt-PT</code></li>
</ul>

<p>This list should not change in the future, assuming we've not missed any. These locale identifier changes become significant in legacy DekiWIki templates.</p>

<h3 id="URL_pattern_changes">URL pattern changes</h3>

<p>The URL pattern for all wiki documents has changed:</p>

<ul>
 <li><code>/{locale}/{slug}</code> -&gt; <code>/{locale}/docs/{slug}</code></li>
</ul>

<p>So, for example:</p>

<ul>
 <li><code>/en/JavaScript</code> -&gt; <code>/en-US/docs/JavaScript</code></li>
 <li><code>/de/JavaScript</code> -&gt; <code>/de/docs/JavaScript</code></li>
 <li><code>/ja/JavaScript</code> -&gt; <code>/ja/docs/JavaScript</code></li>
</ul>

<p>To avoid breaking links, there is an attempt to automatically redirect requests to the legacy-style URLs to new-style URLs. But, efforts should be made to change links to the new-style URLs whenever possible.</p>

<h3 id="Differences_from_DekiScript">Differences from DekiScript</h3>

<p>It's useful to note a few changes from templates in DekiScript, in case you encounter these in migrated content:</p>

<ul>
 <li>No more <code>&lt;span class="script"&gt;</code></li>
 <li>No more <code>template.</code> nor <code>wiki.template</code> prefixing</li>
 <li>No more <code>template({name}[, arguments])</code> syntax</li>
 <li>Arguments must be quoted - e.g., <code>bug(123456)</code> becomes <code>bug("123456")</code> - unless you are calling the template from within another template, and the argument is one of the passed-in args like <code>$1</code> in this example: <code>template("LXRSearch", ["ident", "i", $1])</code>.</li>
</ul>

<h3 id="Caching">Caching</h3>

<p>KumaScript templates are heavily cached to improve performance. For the most part, this works great to serve up content that doesn't change very often. But, as a logged in user, you have two options to force a page to be regenerated, in case you notice issues with scripting:</p>

<ul>
 <li>Hit Refresh in your browser. This causes KumaScript to invalidate its cache for the content on the current page by issuing a request with a <code>Cache-Control: max-age=0</code> header.</li>
 <li>Hit Shift-Refresh in your browser. This causes KumaScript to invalidate cache for the current page, as well as for any templates or content used by the current page by issuing a request with a <code>Cache-Control: no-cache</code> header.</li>
</ul>

<h2 id="Cookbook">Cookbook</h2>

<p>This section will list examples of common patterns for templates used on MDN, including samples of legacy DekiScript templates and their new KumaScript equivalents.</p>

<h3 id="Force_templates_used_on_a_page_to_be_reloaded">Force templates used on a page to be reloaded</h3>

<p>It bears repeating: To force templates used on a page to be reloaded after editing, hit Shift-Reload. Just using Reload by itself will cause the page contents to be regenerated, but using cached templates and included content. A Shift-Reload is necessary to invalidate caches beyond just the content of the page itself.</p>

<h3 id="Recovering_from_Unknown_Error">Recovering from "Unknown Error"</h3>

<p>Sometimes, you'll see a scripting message like this when you load a page:</p>

<pre class="notranslate">Kumascript service failed unexpectedly: &lt;class 'httplib.BadStatusLine'&gt;</pre>

<p>This is probably a temporary failure of the KumaScript service. If you Refresh the page, the error may disappear. If that doesn't work, try a Shift-Refresh. If, after a few tries, the error persists - <a class="link-https" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=mozilla.org&amp;format=itrequest">file an IT bug</a> for Mozilla Developer Network to ask for an investigation.</p>

<h3 id="Broken_wiki.languages_macros">Broken wiki.languages() macros</h3>

<p>On some pages, you'll see a scripting error like this:</p>

<pre class="notranslate">Syntax error at line 436, column 461: Expected valid JSON object as the parameter of the preceding macro but...
</pre>

<p>If you edit the page, you'll probably see a macro like this at the bottom of the page:</p>

<pre class="notranslate">\{{ wiki.languages({ "zh-tw": "zh_tw/Core_JavaScript_1.5_教學/JavaScript_概要", ... }) }}
</pre>

<p>To fix the problem, just delete the macro. Or, replace the curly braces on either side with HTML comments <code>&lt;!-- --&gt;</code> to preserve the information, like so:</p>

<pre class="notranslate">&lt;!-- wiki.languages({ "zh-tw": "zh_tw/Core_JavaScript_1.5_教學/JavaScript_概要", ... }) --&gt;
</pre>

<p>Because Kuma supports localization differently, these macros aren't actually needed any more. But, they've been left intact in case we need to revisit the relationships between localized pages. Unfortunately, it seems like migration has failed to convert some of them properly.</p>

<h3 id="Unconverted_inline_script_blocks">Unconverted inline script blocks</h3>

<p>Occasionally, you'll find some text like this at the bottom of a page, or even somewhere in the middle:</p>

<pre class="notranslate">ottoPreviousNext("JSGChapters");
wiki.languages({
  "fr": "fr/Guide_JavaScript_1.5/Expressions_rationnelles",
  "ja": "ja/Core_JavaScript_1.5_Guide/Regular_Expressions"
});
</pre>

<p>This is a script block that didn't get converted to a KumaScript macro during migration. It happens, unfortunately. If you switch to HTML source editing mode, you'll see this, a <code>&lt;pre class="script"&gt;</code> element:</p>

<pre class="notranslate">&lt;pre class="script" style="font-size: 16px;"&gt;
ottoPreviousNext(&amp;quot;JSGChapters&amp;quot;);
wiki.languages({
  &amp;quot;fr&amp;quot;: &amp;quot;fr/Guide_JavaScript_1.5/Expressions_rationnelles&amp;quot;,
 &amp;nbsp;&amp;quot;ja&amp;quot;: &amp;quot;ja/Core_JavaScript_1.5_Guide/Regular_Expressions&amp;quot;
});
&lt;/pre&gt;
</pre>

<p>This is an inline script - previously allowed by DekiScript, no longer supported by KumaScript.</p>

<p>For this particular example, common to the JavaScript Guide, you can fix it by removing the wiki.languages part (see <a href="/en-US/docs/Project:Introduction_to_KumaScript#Broken_wiki.languages()_macros" title="Project:Introduction_to_KumaScript#Broken_wiki.languages()_macros">previous section</a>) and change the ottoPreviousNext() into a macro like so:</p>

<pre class="notranslate">\{{ ottoPreviousNext("JSGChapters") }}
</pre>

<p>If you see a block of code that's more complex than the above, you will need to create a new template, move the code there, and replace the code in its previous spot with a macro calling the new template.</p>

<h3 id="Finding_the_Current_Pages_Language">Finding the Current Page's Language</h3>

<p>In KumaScript, the locale of the current document is exposed as an environment variable:</p>

<pre class="notranslate">var lang = env.locale;
</pre>

<p>In legacy DekiScript templates, coming up with the locale was a bit harder. You'll see chunks of code like this:</p>

<pre class="notranslate">/* accepts as input one required parameter: MathML element to create an xref to */
var u = uri.parts(Page.uri);
var lang = string.tolower(u.path[0]);
if (string.contains(lang, "project") || string.contains(lang, "Project")) {
  lang = string.substr(lang, 8);
}
/* fall back to page.language on a user page */
else if (string.StartsWith(lang, "user:")) {
  lang = page.language;
}
</pre>

<p>Please replace code like the above with the new KumaScript example. The <code>env.locale</code> variable should be reliable and defined for every document.</p>

<h3 id="Reading_the_contents_of_a_page_attachment">Reading the contents of a page attachment</h3>

<p>You can read the contents of an attached file by using the <code>mdn.getFileContent()</code> function, like this:</p>

<pre class="notranslate">&lt;%
  var contents = mdn.getFileContent(fileUrl);
  ... do stuff with the contents ...
%&gt;
</pre>

<p>or</p>

<pre class="notranslate">&lt;%-mdn.getFileContent(fileObject)%&gt;
</pre>

<p>In other words, you may specify either the URL of the file to read or as a file object. The file objects for a page can be accessed through the array <code>env.files</code>. So, for example, to embed the contents of the first file attached to the article, you can do this:</p>

<pre class="notranslate">&lt;%-mdn.getFileContent(env.files[0])%&gt;
</pre>

<div class="note"><strong>Note:</strong> You probably don't want to try to embed the contents of a non-text file this way, as the raw contents would be injected as text. This is meant to let you access the contents of text attachments.</div>

<p>If the file isn't found, an empty string is returned. There is currently no way to tell the difference between an empty file and a nonexistent one. But if you're putting empty files on the wiki, you're doing it wrong.</p>

<h3 id="Localizing_template_content">Localizing template content</h3>

<p>Templates cannot be translated like other wiki pages. KumaScript only looks for templates in the en-US locale (i.e., <code>/en-US/docs/Template:{name}</code>), and does not look for templates that have been translated to another locale (i.e., <code>/fr/docs/Template:{name}</code>).</p>

<p>So the main way to output content tailored to the current document locale is to pivot on the value of <code>env.locale</code>. There are many ways to do this, but a few patterns are common in the conversion of legacy DekiScript templates:</p>

<h4 id="Ifelse_blocks_in_KumaScript">If/else blocks in KumaScript</h4>

<p>The KumaScript equivalent of this can be achieved with simple if/else blocks, like so:</p>

<pre class="notranslate">&lt;% if ("fr" == env.locale) { %&gt;
&lt;%- template("CSSRef") %&gt; « &lt;a title="Référence_CSS/Extensions_Mozilla" href="/fr/docs/Référence_CSS/Extensions_Mozilla"&gt;Référence CSS:Extensions Mozilla&lt;/a&gt;
&lt;% } else if ("ja" == env.locale) { %&gt;
&lt;%- template("CSSRef") %&gt; « &lt;a title="CSS_Reference/Mozilla_Extensions" href="/ja/docs/CSS_Reference/Mozilla_Extensions"&gt;CSS リファレンス:Mozilla 拡張仕様&lt;/a&gt;
&lt;% } else if ("pl" == env.locale) { %&gt;
&lt;%- template("CSSRef") %&gt; « &lt;a title="Dokumentacja_CSS/Rozszerzenia_Mozilli" href="/pl/docs/Dokumentacja_CSS/Rozszerzenia_Mozilli"&gt;Dokumentacja CSS:Rozszerzenia Mozilli&lt;/a&gt;
&lt;% } else if ("de" == env.locale) { %&gt;
&lt;%- template("CSSRef") %&gt; « &lt;a title="CSS_Referenz/Mozilla_CSS_Erweiterungen" href="/de/docs/CSS_Referenz/Mozilla_CSS_Erweiterungen"&gt;CSS Referenz: Mozilla Erweiterungen&lt;/a&gt;
&lt;% } else { %&gt;
&lt;%- template("CSSRef") %&gt; « &lt;a title="CSS_Reference/Mozilla_Extensions" href="/en-US/docs/CSS_Reference/Mozilla_Extensions"&gt;CSS Reference:Mozilla Extensions&lt;/a&gt;
&lt;% } %&gt;
</pre>

<h5 id="Legacy_DekiScript"><strong>Legacy DekiScript</strong></h5>

<p>A similar way this was done in DekiScript was using <code>&lt;span&gt;</code>'s with <code>lang="{locale}"</code> attributes, like so:</p>

<pre class="notranslate">&lt;p&gt;&lt;span lang="*" class="lang lang-*"&gt;&lt;span class="script"&gt;CSSRef()&lt;/span&gt; « &lt;a title="en/CSS_Reference/Mozilla_Extensions" href="/en/CSS_Reference/Mozilla_Extensions"&gt;CSS Reference:Mozilla Extensions&lt;/a&gt;&lt;/span&gt;
&lt;span lang="en" class="lang lang-en"&gt;&lt;span class="script"&gt;CSSRef()&lt;/span&gt; « &lt;a title="en/CSS_Reference/Mozilla_Extensions" href="/en/CSS_Reference/Mozilla_Extensions"&gt;CSS Reference:Mozilla Extensions&lt;/a&gt;
&lt;span lang="fr" class="lang lang-fr"&gt;&lt;span class="script"&gt;CSSRef()&lt;/span&gt; « &lt;a title="fr/Référence_CSS/Extensions_Mozilla" href="/fr/Référence_CSS/Extensions_Mozilla"&gt;Référence CSS:Extensions Mozilla&lt;/a&gt;&lt;/span&gt;
&lt;span lang="ja" class="lang lang-ja"&gt;&lt;span class="script"&gt;CSSRef()&lt;/span&gt; « &lt;a title="ja/CSS_Reference/Mozilla_Extensions" href="/ja/CSS_Reference/Mozilla_Extensions"&gt;CSS リファレンス:Mozilla 拡張仕様&lt;/a&gt;&lt;/span&gt;
&lt;span lang="pl" class="lang lang-pl"&gt; &lt;span class="script"&gt;CSSRef()&lt;/span&gt; « &lt;a title="pl/Dokumentacja_CSS/Rozszerzenia_Mozilli" href="/pl/Dokumentacja_CSS/Rozszerzenia_Mozilli"&gt;Dokumentacja CSS:Rozszerzenia Mozilli&lt;/a&gt;&lt;/span&gt;
&lt;span lang="de" class="lang lang-de"&gt;&lt;span class="script"&gt;CSSRef()&lt;/span&gt; « &lt;a title="de/CSS_Referenz/Mozilla_CSS_Erweiterungen" href="/de/CSS_Referenz/Mozilla_CSS_Erweiterungen"&gt;CSS Referenz: Mozilla Erweiterungen&lt;/a&gt;&lt;/span&gt;&lt;/span&gt;&lt;/p&gt;
</pre>

<p>This is no longer supported. If you encounter templates built using the legacy DekiScript approach, revise them to use the new KumaScript pattern.</p>

<p>Depending on what text editor is your favorite, you may be able to copy &amp; paste from the browser-based editor and attack this pattern with a series of search/replace regexes to get you most of the way there.</p>

<p>My favorite editor is MacVim, and a series of regexes like this does the bulk of the work with just a little manual clean up following:</p>

<pre class="notranslate">%s#&lt;span#^M&lt;span#g
%s#&lt;span lang="\(.*\)" .*&gt;#&lt;% } else if ("\1" == env.locale) { %&gt;#g
%s#&lt;span class="script"&gt;template.Cssxref(#&lt;%- template("Cssxref", [#
%s#)&lt;/span&gt; &lt;/span&gt;#]) %&gt;
</pre>

<p>Your mileage may vary, and patterns change slightly from template to template. That's why the migration script was unable to just handle this automatically, after all.</p>

<h4 id="String_variables_and_switch">String variables and switch</h4>

<p>Rather than switch between full chunks of markup, you can define a set of strings, switch them based on locale, and then use them to fill in placeholders in a single chunk of markup:</p>

<pre class="notranslate">&lt;%
var s_title = 'Firefox for Developers';
switch (env.locale) {
    case 'de':
        s_title = "Firefox für Entwickler";
        break;
    case 'fr':
        s_title = "Firefox pour les développeurs";
        break;
    case 'es':
        s_title = "Firefox para desarrolladores";
        break;
};
%&gt;
&lt;span class="title"&gt;&lt;%= s_title %&gt;&lt;/span&gt;
</pre>

<p>You'll see examples of this in legacy DekiScript templates. For the most part, this pattern should work as-is, but you may need to adjust the expected values of locales (e.g., <code>en</code>, <code>cn</code>, <code>pt</code> become <code>en-US</code>, <code>zh-CN</code>, <code>pt-PT</code> respectively).</p>

<h4 id="Use_mdn.localString">Use <code>mdn.localString()</code></h4>

<p>A recent addition to the <code>Template:MDN:Common</code> module is <code>mdn.localString()</code>, used like this:</p>

<pre class="notranslate">&lt;%
var s_title = mdn.localString({
  "en-US": "Firefox for Developers",
  "de": "Firefox für Entwickler",
  "es": "Firefox para desarrolladores"
});
%&gt;
&lt;span class="title"&gt;&lt;%= s_title %&gt;&lt;/span&gt;
</pre>

<p>This is more concise than the switch statement, and may be a better choice where a single string is concerned. However, if many strings need to be translated (e.g., as in <a class="link-https" href="/en-US/docs/Template:CSSRef" title="/en-US/docs/Template:CSSRef">CSSRef</a>), a switch statement might help keep all the strings grouped by locale and more easily translated that way.</p>

<p>When the object does not have the appropriate locale, the value of "en-US" is used as the initial value.</p>

<h4 id="Before_and_after_examples">Before and after examples</h4>

<p>Carriage returns added here and there for clarity.</p>

<pre class="notranslate">// Before: DOM0() template Dekiscript
&lt;p&gt;&lt;span class="lang lang-en" lang="en"&gt;DOM Level 0. Not part of any standard. &lt;/span&gt;
&lt;span class="lang lang-es" lang="es"&gt;DOM Nivel 0. No es parte de ninguna norma. &lt;/span&gt;
&lt;span class="lang lang-*" lang="*"&gt;DOM Level 0. Not part of any standard. &lt;/span&gt;
&lt;span class="lang lang-fr" lang="fr"&gt;DOM Level 0. Ne fait partie d'aucune spécification. &lt;/span&gt;
&lt;span class="lang lang-ja" lang="ja"&gt;DOM Level 0。どの標準にも属しません。 &lt;/span&gt;
&lt;span class="lang lang-pl" lang="pl"&gt;DOM Level 0. Nie jest częścią żadnego standardu. &lt;/span&gt;
&lt;span class="lang lang-zh-cn" lang="zh-cn"&gt;DOM Level 0 不属于任何标准.&lt;/span&gt;&lt;/p&gt;

// After: Kumascript version
&lt;% if ("fr" == env.locale) { %&gt;
&lt;p&gt;DOM Level 0. Ne fait partie d'aucune spécification.&lt;/p&gt;
&lt;% } else if ("ja" == env.locale) { %&gt;
&lt;p&gt;DOM Level 0。どの標準にも属しません。 &lt;/p&gt;
&lt;% } else if ("pl" == env.locale) { %&gt;
&lt;p&gt;DOM Level 0. Nie jest częścią żadnego standardu.&lt;/p&gt;
&lt;% } else if ("es" == env.locale) { %&gt;
&lt;p&gt;DOM Nivel 0. No es parte de ninguna norma.&lt;/p&gt;
&lt;% } else if ("zh-CN" == env.locale) { %&gt;
&lt;p&gt;DOM Level 0 不属于任何标准.&lt;/p&gt;
&lt;% } else { %&gt;
&lt;p&gt;DOM Level 0. Not part of any standard.&lt;/p&gt;
&lt;% } %&gt;</pre>

<pre class="notranslate">// From ReleaseChannelInfo() template
// Before:
web.html("&lt;p&gt;Firefox " + $0 + ", based on Gecko " + $1 + ", will ship in " + $2 + ".
 This article provides information about the changes in this release that will
 affect developers. Nightly builds of what will become Firefox " + $0 + " are "
  + web.link(url, "currently available") + " on the " + string.ToUpperFirst($3)
  + " channel.&lt;/p&gt;");

// After:
&lt;p&gt;Firefox &lt;%= $0 %&gt;, based on Gecko &lt;%= $1 %&gt;, will ship in &lt;%= $2 %&gt;. This
 article provides information about the changes in this release that will
 affect developers. Nightly builds of what will become Firefox &lt;%= $0 %&gt;
 are &lt;%- web.link(url, "currently available")%&gt;  on the
 &lt;%= string.ToUpperFirst($3) %&gt; channel.&lt;/p&gt;</pre>

<pre class="notranslate">// Before: old Dekiscript snippet
if ($1 &amp;&amp; string.length($1)) {
  optionsText = optionsText + "&lt;li&gt;" + LXRSearch("ident", "i", $1) + "&lt;/li&gt;";
}

// After: new Kumascript. Quote parameters to template() unless it is an arg variable (like $1).
if ($1 &amp;&amp; string.length($1)) {
    optionsText = optionsText + "&lt;li&gt;" + template("LXRSearch", ["ident", "i", $1]) + "&lt;/li&gt;";
}

// Note that template() within &lt;% ... %&gt; outputs nothing directly. If you want to call another
// template and display its output, use &lt;%= %&gt; or &lt;%- %&gt; like this:
&lt;%- template("LXRSearch", ["ident", "i", $1]) %&gt;</pre>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Project:Getting_started_with_Kuma" title="Getting started with Kuma">Getting started with Kuma</a></li>
 <li><a href="/en-US/docs/Project:KumaScript_reference" title="Project:en/KumaScript reference">KumaScript reference</a></li>
 <li><a class="link-https" href="https://wiki.mozilla.org/MDN/Kuma" title="https://wiki.mozilla.org/MDN/Kuma">Kuma wiki</a></li>
</ul>