Archivos de módulos

Last updated:

Cuando se construye un módulo para páginas, blogs y cotizaciones, el módulo contendrá tres archivos relacionados con el front-end que controlan el contenido, el estilo y la funcionalidad del módulo:

  • module.html
  • module.css
  • module.js

Los módulos de correo electrónico no son compatibles con module.css y module.js. Debido a que los clientes de correo electrónico no admiten JavaScript y la compatibilidad con archivos CSS vinculados es limitada.

Estos archivos siempre se renderizarán en la página cuando una instancia del módulo esté en la página.

Cuando una página incluye varias instancias del mismo módulo, HubSpot sólo cargará module.css y module.js de ese módulo una vez. Por opción predeterminada, module.css y module.js no se cargan de forma asíncrona, pero puedes cambiar esto incluyendo css_render_options y js_render_options en el meta.json del módulo.

Los módulos se pueden construir dentro del administrador de diseño o localmente usando la CLI de HubSpot. En el administrador de diseño, los archivos de los módulos se muestran en un editor de varios paneles.

cms-dev-custom-module1Cuando se visualiza un módulo de forma local, los archivos están contenidos en las carpetas module-name.module.

cms-dev-custom-module0Si utilizas el administrador de diseño o la CLI para crear y administrar módulos depende de las preferencias de tu equipo. Consulta la creación de un workflow eficiente para desarrolladores para recomendaciones.

HTML + HubL (module.html)

El archivo module.html está destinado a HTML y HubL. En general, el lugar en el que se coloca un módulo en el editor de páginas o en el archivo de plantilla determina el lugar en el que se muestra el contenido del archivo module.html. 

Este archivo actúa como un HubL include en la página donde se coloca el módulo. El archivo module.html puede acceder a los valores de los campos del módulo a través de HubL.

CSS (module.css)

Utiliza el archivo module.css para agregar CSS a un módulo.

En general, module.css soporta un subconjunto muy limitado de HubL. Sin embargo, puedes utilizar module_asset_url("my-image.png") para las imágenes agregadas como materiales vinculados al módulo. Esto permite vincular materiales como imágenes, empaquetados con el propio módulo. Por ejemplo:

.testimonial-module__wrapper{ background: url("{{ module_asset_url("bg-pattern.png") }}"); background-repeat:repeat; min-height:200px; width:100%; display:block; }

A continuación, aprende a configurar el CSS de un módulo para que cambie dinámicamente basado en los campos del módulo.

Estilo basado en los valores de los campos del módulo

Hay algunas maneras de influir en el estilo de tu módulo basado en los campos del módulo. Elige la manera que mejor se adapte a tu caso de uso específico.

Clases CSS

Para establecer un estilo predefinido para el módulo con la opción de que los editores seleccionen entre esas opciones, puedes agregar un campo de módulo para establecer clases en tu archivo module.html que se correspondan con las clases CSS de tu archivo module.css.

Por ejemplo, puedes tener un módulo de imagen y texto. Quieres que los creadores de contenidos puedan colocar la imagen a la derecha o a la izquierda del texto en función de un campo de elección. Para ello, puedes configurar tus archivos module.html y module.css de la siguiente manera:

<!-- module.html --> <section class="img-text__wrapper img-text--{{ module.positioning }}" aria-label="{{ module.heading }}"> {# module.position is a choice field with two values "img-left" or "img-right". This dictates the order they appear on desktop. Controlled by CSS #} <div class="img-text__img"> <img src="{{ module.image.src }}" alt="{{ module.image.alt }}"> </div> <div class="img-text__text"> <h2> {% inline_text field="heading" value="{{ module.heading }}" %} </h2> {% inline_rich_text field="text" value="{{ module.text }}" %} </div> </section>
/* module.css */ /* CSS that makes the image show adjacent to the text, and positioned based on the positioning field.*/ /* The media query ensures that on mobile the image will always appear above the text for visual consistency. */ @media(min-width:768px){ .img-text__wrapper{ display:flex; align-items:row; } .img-text__img,.img-text__text{ flex:1; padding:10px; } .img-text--img-right{ flex-direction:row-reverse; } }

bloque require_css

Cuando necesitas dar a los creadores de contenido un control directo sobre propiedades específicas y cuando las clases no son ideales, las etiquetas de estilo con bloques require_css son la mejor opción. 

Para dar a los creadores de contenido un control directo sobre propiedades específicas sin usar clases, puedes agregar estilos al archivo module.html dentro de las etiquetas require_css. Por ejemplo:

<div class="img__wrapper"> {% if module.image.src %} {% set sizeAttrs = 'width="{{ module.image.width }}" height="{{ module.image.height }}"' %} {% if module.image.size_type == 'auto' %} {% set sizeAttrs = 'style="max-width: 100%; height: auto;"' %} {% elif module.image.size_type == 'auto_custom_max' %} {% set sizeAttrs = 'width="100%" height="auto" style="max-width: {{ module.image.max_width }}px; max-height: {{ module.image.max_height }}px"' %} {% endif %} <img src="{{ module.image.src }}" alt="{{ module.image.alt }}" {{ sizeAttrs }}> {% endif %} </div> {% require_css %} <style> img { border-width:{{ module.border_width }}px; border-color:rgba({{ module.border_color.color|convert_rgb}},{{ module.border_color.opacity/100 }}); border-style: solid; } </style> {% end_require_css %}

Debido a que module.html puede renderizar HubL, puedes utilizar los valores de los campos del módulo como variables CSS. Cuando un creador de contenido actualiza el campo en el editor de la página, el CSS se actualizará para coincidir. Este bloque mueve las etiquetas <style> dentro de <head> de tu página dentro de la sentencia standard_header_includes.

También puedes establecer que el CSS se aplique sólo a la instancia del módulo envolviendo el CSS con etiquetas scope_css.  Por ejemplo, podrías actualizar el código del módulo anterior de la siguiente manera:

<div class="img__wrapper"> {% if module.image.src %} {% set sizeAttrs = 'width="{{ module.image.width }}" height="{{ module.image.height }}"' %} {% if module.image.size_type == 'auto' %} {% set sizeAttrs = 'style="max-width: 100%; height: auto;"' %} {% elif module.image.size_type == 'auto_custom_max' %} {% set sizeAttrs = 'width="100%" height="auto" style="max-width: {{ module.image.max_width }}px; max-height: {{ module.image.max_height }}px"' %} {% endif %} <img src="{{ module.image.src }}" alt="{{ module.image.alt }}" {{ sizeAttrs }}> {% endif %} </div> {% require_css %} <style> {% scope_css %} img { border-width:{{ module.border_width }}px; border-color:rgba({{ module.border_color.color|convert_rgb}},{{ module.border_color.opacity/100 }}); border-style: solid; } {% end_scope_css %} </style> {% end_require_css %}

Agregar estilo en línea

Cuando se necesita dar a los creadores de contenidos un control granular sobre sólo unas pocas propiedades y cuando las clases no son ideales, puedes agregar directamente los valores a un atributo de estilo en el HTML.

{# Module.html #} <div style="background: rgba({{ module.bg_color.color|convert_rgb }},{{ module.bg_color.opacity/100 }});"> {% inline_rich_text field="richtext" value="{{ module.richtext }}" %} </div>

Si tienes muchas propiedades y el código se vuelve difícil de leer, considera cambiar al método de bloque require_css.

Importar archivos CSS específicos

require_css es una función de HubL que puedes agregar a module.html y que indica a HubSpot que un módulo o plantilla en particular requiere un archivo CSS concreto para mostrarse. Se agrega una etiqueta de enlace que apunta al archivo css a la página <head> dentro de standard_header_includes

La función require_css sólo cargará ese archivo CSS una vez, independientemente de las veces que ese mismo archivo sea requerido por los módulos y plantillas de una página concreta. Esto lo hace ideal para situaciones en las que los estilos pueden ser compartidos a través de múltiples módulos, pero donde agregar el CSS directamente a las hojas de estilo principales utilizadas en cada página de tu sitio puede no tener sentido.

require_css y los archivos CSS enlazados cumplen el mismo propósito, pero require_css puede utilizarse de forma condicional en función de los valores de los campos. Así se evita cargar un código innecesario.

<!-- module.html --> {{ require_css(get_asset_url("/modules/shared_layout_styles.css")) }}

JavaScript (module.js)

Utiliza el archivo module.js para agregar JavaScript a un módulo.

Al igual que el archivo module.css, el archivo module.js no soporta HubL.

Scripts basados en los valores de los campos

Hay algunas maneras de construir módulos, donde el JavaScript actúa de manera diferente basándose en los valores de los campos. Entender qué método utilizar y cuándo puede significar beneficios de rendimiento en cada página en la que se utilice el módulo. 

Por ejemplo, tienes un módulo de imágenes personalizado, quieres dar a los creadores de contenido la posibilidad de hacer que la imagen se abra en un lightbox. Los creadores de contenido sólo quieren eso para imágenes específicas, y no para todas las instancias del módulo.

Atributos de los datos

Los atributos de datos son atributos personalizados estándar de HTML 5 que los desarrolladores agregan a los elementos. Al igual que todos los elementos admiten class="yourClassName", todos los elementos admiten data-your-attribute="yourValue".

<!-- module.html--> <div class="img-module img-module__wrapper" data-lightbox="{{ module.is_lightbox_enabled }}" data-caption="above"> <!-- module.is_lightbox_enabled is a boolean field, module.caption_position is a choice field. --> {% if module.image.src %} {% set sizeAttrs = 'width="{{ module.image.width }}" height="{{ module.image.height }}"' %} {% if module.image.size_type == 'auto' %} {% set sizeAttrs = 'style="max-width: 100%; height: auto;"' %} {% elif module.image.size_type == 'auto_custom_max' %} {% set sizeAttrs = 'width="100%" height="auto" style="max-width: {{ module.image.max_width }}px; max-height: {{ module.image.max_height }}px"' %} {% endif %} <img src="{{ module.image.src }}" alt="{{ module.image.alt }}" {{ sizeAttrs }}> {% endif %} </div>

Puedes usar atributos de datos para pasar los valores de los campos de tus instancias de módulos para que sean manejados por tu archivo module.js.

Para utilizar los valores de tu archivo module.js, tendrás que recorrer todas las instancias de tu módulo. Agregar un nombre de clase específico del módulo al elemento envolvente más externo de tu módulo te dará un objetivo a utilizar, para que puedas hacer un bucle a través de cada una de tus instancias del módulo.

// module.js let imgModules = document.getElementsByClassName('img-module'); Array.from(imgModules).forEach(function(element) { // loop through each of the instances of the module // set data attributes to variables to make it easy to work with let isLightboxEnabled = element.dataset.lightbox; let captionStyle = element.dataset.caption; if(isLightboxEnabled){ element.addEventListener('click', function(){ showLightbox(captionStyle); // Execute your code for the action you want to take, you can pass your data attributes into functions from libraries. }); } });

Los atributos de datos te permitirán recuperar los valores de los campos para cada instancia del módulo en tu module.js. 

bloque require_js

En situaciones avanzadas, tal vez cuando se utiliza una biblioteca de plantillas de JavaScript o un framework reactivo como Vue.js o React.js, puedes preferir la salida de sólo los datos, mientras que el framework maneja la representación.

En este caso, utiliza una etiqueta de script rodeada por un bloque require_js para proporcionar variables a las que puedas acceder desde el script de la plantilla.

{% require_js %} <script> let myArray = [ {%- for item in module.repeating_text_field -%}"{{ item }}",{%- endfor -%} ]; </script> {% end_require_js %}

Esta técnica puede ser útil para suministrar a las aplicaciones avanzadas un conjunto inicial de datos a partir del cual se puede renderizar. Esto elimina una llamada inicial de JavaScript para recuperar los datos.

require_js

require_js es una función de HubL que indica a HubSpot que un módulo o plantilla en particular requiere un archivo JavaScript concreto para cargarse correctamente. La función toma dos parámetros: la ruta del archivo y la ubicación a la que se debe agregar el archivo ("encabezado" o "pie de página"). 

En un módulo require_js sólo se puede agregar al module.html. El archivo JavaScript al que se hace referencia en la sentencia require_js sólo se cargará una vez por página, independientemente del número de veces que lo requieran los módulos y plantillas dentro de la página. Esto reduce el número de peticiones HTTP y evita la duplicación de código. 

Algunas situaciones en las que esto resulta útil:

  • Si tienes varios módulos o plantillas que requieren el mismo JavaScript, puedes usar require_js para compartir ese script entre módulos.
  • Si trabajas con un bundler de JavaScript como webpack, puede ser más fácil enviar tus archivos js a una ubicación específica. Usando require_js, puedes asociar el JavaScript con tu módulo.

require_js y los archivos javascript enlazados sirven para el mismo propósito, pero require_js puede hacerse condicionalmente en base a los valores de los campos. Esto evita que se cargue un código innecesario. También tienes la opción adicional de cargar JavaScript en el encabezado, si lo necesitas.

Debido aque JavaScript bloquea la visualización, la ubicación predeterminada en la require_js coloca JavaScript es el "pie de página". Más información sobre la optimización del rendimiento.

Información relacionada


¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.