Empezar a usar con módulos

En este tutorial, utilizarás el tema boilerplate de HubSpot CMS para aprender a crear un módulo y recorrer cómo puedes utilizarlo en plantillas y páginas como parte de un tema. Al final del tutorial, habrás creado un módulo de testimonios que incluye un campo de imagen, un campo de texto y un campo de texto enriquecido. 

Si quieres avanzar, puedes mostrar preliminarmente los archivos del proyecto terminado. Dado que el código del tema boilerplate de CMS puede cambiar con el tiempo, solo se incluyen los archivos más críticos que los desarrolladores tendrán que crear o editar durante el tutorial. Estos archivos incluyen:

1. Testimonial.module: la carpeta que contiene los archivos que componen el módulo personalizado que construirás como parte del tutorial.
2. homepage.html: la plantilla que se editará para incluir nuestro módulo personalizado.
3. images: la carpeta que contiene las imágenes de perfil que utilizarás en el módulo de testimonios. 

Antes de comenzar con este tutorial:

• Configurar un Sandbox para desarrolladores de HubSpot CMS. Puedes utilizar tu cuenta existente, pero el entorno de prueba te permitirá desarrollar sin afectar los materiales de tu cuenta principal.
• Instala Node.js, lo que habilita las herramientas de desarrollo local de HubSpot. Se admiten las versiones 10 o superiores.

Durante este tutorial, desarrollarás el módulo localmente. Para interactuar con HubSpot en tu interfaz de línea de comandos, tendrás que instalar la CLI de HubSpot y configurarla para acceder a tu cuenta.

• En el terminal, ejecuta npm install -g @hubspot/cli para instalar la CLI globalmente. Para instalar la CLI solo en tu directorio actual, ejecuta npm install @hubspot/cli.
• En el directorio donde almacenarás los archivos de tu tema, ejecuta hs init.
• Presiona Intro para abrir la página de la clave de acceso personal en tu navegador.
• Selecciona la cuenta en la que deseas realizar el despliegue y haz clic en Continuar con esta cuenta. Se te redirigirá a la página de la clave de acceso personal de la cuenta.
• Junto a Clave de acceso personal, haz clic en Mostrar para revelar tu clave. Luego, haz clic en Copiar para copiarlo en el portapapeles.
• Pega la clave copiada en el terminal y presiona Intro.
• Introduce un nombre único para la cuenta. Este nombre solo será visto y utilizado por ti cuando ejecutes comandos. Luego, presiona Intro. Para conectar las herramientas de desarrollo local a tu cuenta:

Entonces verás un mensaje de éxito confirmando que el archivo hubspot.config.yml fue creado.

• En el terminal, ejecuta hs create website-theme my-theme. Se creará entonces una carpeta de temas en tu directorio de trabajo que contendrá los materiales de la plantilla.
• Sube los archivos a tu cuenta ejecutando hs upload <src> <destination>. 
  • <src> ruta de acceso al archivo local, relativa a tu directorio de trabajo actual.
  • <destination> es la ruta de destino en tu cuenta de HubSpot. El destino puede ser una nueva carpeta.
  • Por ejemplo, hs upload my-theme my-new-theme subiría la carpeta my-theme de tu máquina a una carpeta my-new-theme en HubSpot.

• En cualquier momento, puedes subir manualmente los cambios guardados a HubSpot ejecutando hs upload. Pero también puedes ejecutar hs watch <src> <destination> para cargar automáticamente los cambios locales al guardar. Para dejar de ver, puedes presionar Control-C.

• Inicia sesión en tu cuenta de HubSpot, luego navega al administrador de diseño navegando a Marketing > Archivos y plantillas > Herramientas de diseño.
• En la barra lateral izquierda del administrador de diseño, abre la carpeta del tema que acabas de cargar. 
• En la carpeta del tema, abre la carpeta de módulos.
• En la parte superior izquierda, haz clic en Archivo > Nuevo archivo para crear un nuevo módulo en esta carpeta.
• En el cuadro de diálogo, haz clic en el menú desplegable y luego selecciona Módulo y haz clic en Siguiente.
  
• Selecciona la casilla de comprobación Páginas para que el módulo esté disponible para el sitio web y las páginas de destino.
• Introduce un nombre de archivo para tu módulo y luego haz clic en Crear.

A continuación, agregarás tres campos al módulo:

• Un campo de texto para almacenar el nombre del cliente que da el testimonio.
• Un campo de imagen que almacenará la foto de perfil del cliente.
• Un campo de texto enriquecido que almacenará el testimonio del cliente.

Para agregar estos campos:

• En la barra lateral derecha, haz clic en el menú desplegable Agregar campo y luego selecciona Texto.
  
• Junto al icono del lápiz en la parte superior derecha, en el campo de texto, introduce el nombre del cliente. Verás que el nombre de la variable HubL cambia a customer_name.
• Establece el texto predeterminado en Sally.

• En la barra lateral derecha, haz clic en el icono breadcrumb para volver al menú principal del módulo.
• Agrega otro campo utilizando el mismo método, esta vez seleccionando el tipo de campo Imagen.
• Etiqueta el campo de la imagen como Imagen de perfil y luego establece el nombre de la variable HubL en profile_pic.
• En Imagen predeterminada, selecciona la imagen de perfil proporcionada para sally en la carpeta de images de los archivos del proyecto completados .
• Establece el Texto alternativo en Imagen de perfil del cliente.

• Agrega otro campo utilizando el mismo método, esta vez seleccionando el tipo de campo de texto enriquecido.
• Etiqueta el campo de texto enriquecido como Testimonio.
• Haz clic en el cuadro Texto enriquecido predeterminado y luego escribe «Solo he tenido experiencias maravillosas con esta empresa».

Hasta ahora, has agregado datos en varios campos del módulo. Aunque estos campos tengan datos, el módulo en sí no los mostrará todavía, porque no has agregado los campos al HTML del módulo. Esto se refleja en que el campo module.html está vacío en este punto. 

Para agregar HubL al módulo, copia y pega el siguiente código en el archivo module.html:

En el código anterior, se utiliza la notación de puntos para acceder a varios datos de campo:

• La variable module representa el módulo en sí, mientras que el campo customer_name representa el nombre de la variable que asignó al campo de texto en el paso anterior. En conjunto, module.customer_name busca el texto del nombre del cliente dentro del módulo.
• El valor module.profile_pic.src accede al campo profile_pic del módulo y busca el valor src, que es la URL de la imagen. Sin embargo, aunque la variable HubL contenga la URL de la imagen, es necesario colocarla dentro de una etiqueta HTML de imagen para representarla en la página.

Con el HubL agregado a tu módulo, puedes hacer clic en Vista preliminar en la parte superior derecha para ver el aspecto del módulo hasta el momento.

En la parte superior derecha del administrador de diseño, haz clic en Publicar cambios.

Con tu módulo ya construido, ahora lo bajarás a tu entorno local para copiarlo en tu carpeta de temas. Es importante notar que también puedes construir módulos desde cero localmente, pero para los propósitos de este tutorial es útil ver el proceso de HubSpot junto con el proceso local. 

Para llevar tu módulo a tu entorno local:

• En el terminal, ejecuta el siguiente comando: hs fetch <hs_src> <destination>:
  • <hs_src> representa la ruta del módulo en HubSpot. Para obtener la ruta del archivo, puedes hacer clic con el botón derecho del ratón sobre el módulo en la barra lateral izquierda del administrador de diseño y luego seleccionar Copiar ruta. 
    
  • <destination> representa la ruta del directorio local que contiene tu tema. Si se omite, el comando se dirigirá por opción predeterminada al directorio de trabajo actual.

Para los propósitos de este tutorial, debes bajar el módulo a la carpeta "src/modules" en el directorio "my-theme" que creaste en el Paso 1. Más información sobre el comando fetch.

En tu editor de código preferido, navega hasta la carpeta del módulo que acabas de sacar de tu cuenta de HubSpot. Dentro de tu carpeta de módulos, verás cinco archivos diferentes:

Puedes encontrar información más detallada en nuestra documentación sobre la estructura de archivos del módulo, especialmente en lo que respecta a los archivos fields.json y meta.json. En este tutorial, nos centraremos en los archivos fields.json, module.css y module.html y en cómo se generan, se descargan y se cargan en el editor de módulos en el Administrador de diseño.

Abre el archivo fields.json del módulo. Aparte de algunos de los números de identificación, el atributo src del campo de la imagen, y potencialmente el orden de los campos, el archivo debe contener un objeto JSON similar al siguiente:

Los valores de los siguientes campos coincidirán con los valores que agregaste en el paso 3:

• name: el nombre del campo.
• label: la etiqueta del campo.
• default: el valor predeterminado del campo.  

Para ilustrar la relación entre estos campos y sus datos:

• En tu entorno local, cambia el valor predeterminado del campo de texto enriquecido Testimonio por el siguiente: "Lo recomendaría al 100% a mis colegas y amigos"
• Guarda tu archivo Volveremos a esto en el paso 10.

El archivo module.html debe contener el HubL y el HTML que escribiste en el editor de módulos HubL + HTML en el paso 4.

Para hacer este código más interesante, copia y pega el siguiente código en el archivo:

El archivo module.css debería estar vacío en este punto. Para agregar el estilo, copia y pega el siguiente código en el archivo:

Después de agregar el código, guarda el archivo.

Después de hacer los cambios en el módulo localmente, los empujarás a tu cuenta de HubSpot.

• Navega a tu terminal y asegúrate de que estás en el directorio correcto.
• Ejecuta el comando watch para enviar los cambios a HubSpot al guardar: hs watch <src> <destination>. 
  • <src> ruta de acceso al archivo local, relativa a tu directorio de trabajo actual.
  • <destination> es la ruta de destino en tu cuenta de HubSpot. El destino puede ser una nueva carpeta.
  • Por ejemplo, hs upload my-theme my-new-theme subiría la carpeta my-theme de tu máquina a una carpeta my-new-theme en HubSpot.

• En tu cuenta de HubSpot, navega a Marketing > Archivos y plantillas > Herramientas de diseño.
• En la barra lateral izquierda, navega hasta el tema que has creado, luego abre la carpeta de módulos y selecciona el módulo de Testimonios.
• Con el módulo abierto, ahora deberías ver tus cambios en los paneles module.html y module.css. 
• En la parte superior derecha, haz clic en Vista preliminar. Se abrirá una nueva pestaña para mostrar la vista preliminar del módulo. 

Para recapitular en este tutorial hasta ahora:

• Creaste un módulo en HubSpot.
• Bajaste ese módulo a su entorno local.
• Realizaste cambios en el HubL + HTML y CSS utilizando sus herramientas de desarrollo locales.
• Sube tus cambios a tu cuenta de HubSpot usando el comando CLI watch (Paso 10).

Pero éste es solo uno de los muchos métodos disponibles para crear un módulo. Por ejemplo, también podrías:

1. Crear un módulo en el Administrador de diseño.
2. Bajar ese módulo de nuestra cuenta de HubSpot.
3. Antes de realizar cualquier edición, ejecuta el comando watch. Con el comando watch ejecutado, puedes editar tu módulo localmente y ver los cambios inmediatamente en tu cuenta de HubSpot.

Cuando desarrolles en HubSpot, experimenta con tu workflow para encontrar lo que mejor funciona para ti.

En la siguiente parte de este tutorial, aprende a utilizar el módulo en una plantilla.

Parte 2: Utilización del módulo en una plantilla

En tu editor de código, navega al directorio my-theme que creaste en el paso 1 cuando descargaste inicialmente el tema boilerplate de HubSpot CMS.

Para esta parte del tutorial, trabajarás principalmente con las carpetas de modules y templates.  

Por su definición más básica, los módulos son áreas editables de las plantillas y páginas de HubSpot. Puedes insertar módulos en plantillas en HubSpot utilizando el administrador de diseño, pero aquí vamos a utilizar HubL para agregar módulos a una plantilla en nuestro entorno local.   

• En tu editor de código, abre la carpeta templates y luego abre el archivo home.html.  
• En el archivo home.html, navega hasta el final dnd_section, que debería comenzar alrededor de la línea 28. En esta sección agregarás tu nuevo módulo.
  
• Dentro de esta dnd_section por encima de los otros dnd_modules, copia y pega la siguiente etiqueta de módulo HubL:

Esta etiqueta hace referencia a tu nuevo módulo por su ruta de archivo relativa. En el siguiente paso, agregarás otros parámetros opcionales a la etiqueta.

• Si no has mantenido la ejecución del comando watch para hacer un seguimiento automático de tu trabajo, ejecuta hs watch <src> <dest> en tu terminal para cargar tus cambios. Asegúrate de que este comando se siga ejecutando, mientras completas los siguientes pasos. 
• En tu cuenta de HubSpot, navega al administrador de diseño (Marketing > Archivos y plantillas > Herramientas de diseño.
• En la barra lateral izquierda del administrador de diseño, selecciona el archivo homepage.html.
• En la parte superior derecha, haz clic en Vista preliminar y luego selecciona Vista preliminar en directo con opciones de presentación para abrir la vista preliminar de la plantilla en una nueva ventana.

• En la nueva pestaña, abre su vista preliminar, que debería contener su módulo de testimonios recién agregado.

Para hacer más interesante la plantilla de la página de inicio:

• Vuelve a tu editor de código y abre el archivo homepage.html.
• Agrega los siguientes parámetros a la etiqueta del módulo de testimonios:

Los parámetros anteriores anulan los valores predeterminados que asignaste originalmente a los tres campos. Cada parámetro utiliza el nombre de la variable HubL que asignaste a cada campo en el paso 3:

• customer_name: este parámetro pasa el nombre María al campo del nombre del cliente.
• profile_pic: este parámetro es un objeto que contiene dos propiedades. La propiedad src utiliza la función HubL get_asset_url para recuperar la URL de la foto de perfil de María. No es que la ruta del archivo de la imagen sea relativa a tu directorio de trabajo. La propiedad alt asigna el texto alternativo de la imagen.
• testimonial: este parámetro pasa un nuevo texto al campo de testimonio.

Alternativamente, para el campo de texto enriquecido, podrías utilizar la sintaxis de bloque de HubL para escribir un gran bloque de HTML o texto:

Más información sobre la sintaxis del bloque de módulos.

Si has mantenido el comando watch en ejecución en tu terminal, guarda los cambios para enviarlos a HubSpot. Puedes volver a navegar por el administrador de diseño para obtener una vista preliminar de la plantilla.

en este paso, agregarás otros dos módulos de testimonios a la plantilla siguiendo los mismos pasos que antes:

• Navega a tu editor de código y abre el archivo home.html.
• Debajo del módulo de testimonios que agregaste anteriormente, agrega otra instancia del módulo copiando y pegando el código de ese módulo. En el nuevo módulo de testimonios, especifica los siguientes detalles siguiendo los mismos pasos anteriores:
  • El nombre del cliente es Ollie.
  • El testimonio de Ollie dice: "¡No puedo creer que alguna vez haya llevado a cabo un negocio sin el uso de este producto!"
  • Para la imagen de Ollie, agrega la ruta relativa del archivo dentro de la carpeta images. Entonces dale a la imagen de Ollie el atributo alt de "Imagen de perfil de Ollie".
• Debajo del segundo módulo de testimonios, agrega un tercero con los siguientes datos:
  • El nombre del cliente es Erin.
  • El testimonio de Erin dice: "¡Mi negocio casi se ha triplicado desde que empecé a utilizar este producto! No esperes, empieza ahora"
  • Para la imagen de Erin, agrega la ruta relativa del archivo dentro de la carpeta images. Luego, dale a la imagen de Erin el atributo alt de "Imagen de perfil de Erin".
• Guarda los cambios.

Si has mantenido el comando watch en ejecución en tu terminal, puedes volver a navegar por el Administrador de diseño para mostrar preliminarmente tus cambios en la plantilla. La vista preliminar de la plantilla debería contener ahora los tres módulos de testimonios.

En la siguiente parte de este tutorial, construirás una página de HubSpot utilizando esta plantilla.

Parte 3: Uso de la plantilla personalizada en una página de HubSpot

Antes de que puedas crear una página con la plantilla de página de inicio que acabas de modificar, tendrás que hacer un último cambio en tu entorno local modificando el archivo theme.json. En este archivo, designarás este directorio como un tema que es accesible a través de diferentes productos de HubSpot.  

En tu editor de código, abre el archivo theme.json, luego pega el siguiente objeto JSON en el archivo (sin el comentario //theme.json):

Después de agregar ese código, guarda los cambios para que el comando watch envíe los cambios a HubSpot.

Para crear una página:

• En HubSpot, navega a Marketing > Sitio web > Páginas del sitio web.
• En la parte superior derecha, haz clic en Crear y luego selecciona Página del sitio web. Dale un nombre a tu página y haz clic en Crear página.
• En la pantalla Elegir una plantilla, selecciona Mi tema personalizado utilizando el menú desplegable selector de temas.  
  
  • Si no estás viendo el tema correcto, selecciona Cambiar tema en el menú desplegable del selector de temas.

• En tu tema, haz clic en la plantilla de Inicio. En la parte superior derecha, haz clic en Seleccionar plantilla.

En el editor de la página, deberías ver todos los cambios que has hecho a lo largo de este tutorial.

Para personalizar la página:

• En la barra lateral izquierda, utiliza la pestaña Agregar para elegir entre módulos predeterminados y personalizados. Para agregar un módulo a la página, haz clic y arrástralo al cuerpo de la página en el panel central del editor.
• En la barra lateral izquierda, utiliza la pestaña Contenido para revisar los módulos actuales de la página.
• En la barra lateral izquierda, utiliza la pestaña Diseño para revisar los estilos de tema disponibles para la página. 
• En el panel central donde se muestra el contenido de tu página, puedes hacer clic en los módulos para editar tu contenido.
• Puedes mostrar preliminarmente tus cambios en cualquier momento haciendo clic en Vista preliminar en la parte superior derecha. Más información sobre crear y editar páginas. 

El último paso antes de publicar es editar la configuración de la página:

• En la parte superior del editor, haz clic en la pestaña Configuración.
• Haz clic en el campo Título de la página para agregar un título a la página. Este título se mostrará en la pestaña del navegador cuando un visitante acceda a la página.
• En la URL de la página, haz clic en el campo Content slug para establecer la URL de la página. También puedes hacer clic en el menú desplegable Dominios para seleccionar cualquiera de tus dominios conectados.

• Para publicar tu página, haz clic en Publicar en la esquina superior derecha. Una vez publicada, la página estará en vivo en la URL especificada

• Primeros pasos para usar temas
• Empezar a usar funciones sin servidor
• Creación de un workflow de desarrollo eficiente
• Empezar con la accesibilidad
• Cómo utilizar los frameworks de JavaScript en CMS Hub