Descripción de los campos de los módulos y temas

Last updated:

Los módulos y los temas tienen el concepto de campos. Los campos son campos de formulario para personalizar el módulo o el tema. Los campos pueden utilizarse para controlar tanto el estilo como la función de los módulos y temas utilizados en un sitio.

Creación y administración de negocios

Puedes agregar campos al archivo fields.json de un módulo localmente a través de la CLI de HubSpot y en el editor de módulos de la aplicación. Para agregar campos a un tema, debes actualizar el archivo fields.json del tema localmente utilizando la CLI. 

CLI de HubSpot

Cuando se construye localmente los campos de los módulos y temas pueden ser editados a través de un archivo fields.json dentro de la carpeta del módulo o tema. Para los módulos, este archivo se creará automáticamente cuando se utilice el comando hs create module. Todas las opciones de campo disponibles en el editor de módulos están disponibles como propiedades que puedes agregar o editar en el archivo fields.json. Esto incluye campos de repetición, grupos y condiciones. Una de las ventajas de editar localmente es que facilita la inclusión de tus módulos en sistemas de control de versiones como git.

Editor de módulos

El administrador de diseño tiene una interfaz de usuario de editor de módulos integrada que te permite crear, agrupar y editar campos de módulos. El editor de módulos contiene una vista preliminar del módulo que te permite ver el aspecto del módulo por sí mismo, así como probar sus campos. Dado que los módulos no viven en el vacío, siempre debes probarlos en una plantilla que planees utilizar, para ver qué estilos a nivel de plantilla pueden afectarlo. Ten en cuenta que si un módulo está contenido en una carpeta bloqueada no puede ser editado de esta manera.

Editor de módulos del administrador de diseño

Nota: si estás trabajando principalmente de forma local pero quieres utilizar el editor de módulos para configurar los campos, asegúrate de recuperar los cambios. Esto es especialmente importante para quienes utilizan sistemas de control de versiones como git.

Campos contiguos

Por opción predeterminada, los campos de los módulos en los editores de contenido se apilan verticalmente. Sin embargo, puedes colocar los campos del módulo uno al lado del otro agregando una propiedad display_width a los campos en el archivo fields.json con un valor de half_width

side-by-side-modules0

Un solo campo con un display_width de half_width aparecerá como half-width en el editor de contenido. Cuando el campo por encima o por debajo de ese campo en el archivo fields.json se establece en half_width, se colocarán uno al lado del otro.

// Example module fields.json file [ { "name": "number_field", "label": "Number", "required": false, "locked": false, "display": "slider", "min": 1, "max": 10, "step": 1, "type": "number", "prefix": "", "suffix": "", "default": null, "display_width":"half_width" }, { "label": "Description", "name": "description", "type": "text", "required": true, "default": "Add a description", "display_width": "half_width" } ]

Grupo de campos

Cuando los campos están relacionados entre sí a menudo tiene sentido que se muestren visualmente agrupados. Los módulos y los temas permiten agrupar varios campos. 

Grupo de campos sin grupos de campos anidados

Los grupos de campos sin grupos de campos anidados se muestran simplemente con divisores por encima y por debajo del grupo, y la etiqueta del grupo se muestra en la parte superior del grupo.

Grupo de campos anidados

Los grupos de campos pueden ser anidados. Un grupo de campos que contenga otro grupo de campos se mostrará como un botón. Al hacer clic en el botón para ver el grupo, se mostrará el contenido de ese grupo.

Los grupos de campos pueden estar anidados a 3 niveles de profundidad, lo que significa que los campos del módulo pueden tener 4 niveles de profundidad. Facilitando la creación de interfaces de usuario que transmitan las relaciones entre los campos y una mayor profundidad granular.

Grupos de campos en fields.json

Los objetos de grupo de campos pueden ser listados como subordinados de otros grupos de campos, su estructura es muy similar a la de los propios campos con el único parámetro especial de "hijos", que es una matriz de campos y grupos que contienen.

// Field group example { "type": "group", "name": "typography", "label": "Typography", "expanded": true, "children": [ { "type": "font", "name": "h1_font", "label": "Heading 1", "load_external_fonts": true, "default": { "color": "#000", "font": "Merriweather", "font_set": "GOOGLE", "variant": "700", "size": "48" } } ] } // Field group inside of a field group { "type": "group", "name": "header", "label": "Header", "children": [ { "type": "font", "name": "h1_font", "label": "Heading 1", "load_external_fonts": true, "default": { "color": "#000", "font": "Merriweather", "font_set": "GOOGLE", "variant": "700", "size": "48" } { "type": "group", "name": "navigation", "label": "Navigation", "expanded": false, "children": [ { "name" : "bg_color", "label" : "Background color", "sortable" : false, "required" : false, "locked" : false, "type" : "color", "default" : { "color" : "#ff0000", "opacity" : 100 } } ] } } ] }

Grupo de campos ampliado de manera predeterminada

Los grupos de campos pueden configurarse para que se expandan por opción predeterminada estableciendo la propiedad booleana expanded en true en las propiedades de grupo de fields.json como se muestra en el código de ejemplo anterior. Los grupos de campos no se expanden por opción predeterminada y cuando se utilizan grupos de campos anidados, el grupo de origen (parent) no puede hacer uso de esta propiedad.

Salida de los valores de los campos dentro de los grupos de campos

Los grupos de campos crean diccionarios que contienen los valores de los campos que deseas imprimir. Si se anidan grupos de campos, el grupo de campos anidado es un diccionario dentro del diccionario del grupo de campos externo. Para acceder a esos datos, atravesarás el árbol desde el tema raíz o la variable del módulo, dependiendo de tu contexto.

<div> {# printing a value from a field group `recipe_summary` is the field group, `title` is the text field. #} {{module.recipe_summary.title}} </div>/* Printing a Font field's color value, when the font field is within a field group. `typography` is the field group, `h1_font` is the field */ h1{ color: {{ theme.typography.h1_font.color }}; }

Campos de estilo

Los campos de estilo son un tipo de grupo de campo especial en el archivo fields.json de un módulo o tema que da a los creadores de contenido el control sobre el estilo de un módulo o tema en el editor de páginas y temas. A continuación, aprende a agregar campos de estilo a un módulo o tema. Más información sobre las mejores prácticas para utilizar y organizar los campos de estilo.

Campos de estilo del módulo

Los campos de estilo agregados a un módulo aparecerán en la pestaña Estilos del editor de páginas al editar el módulo:

style-field-module-editor0

Cuando se agregan campos de estilo al archivo fields.json de un módulo, se agregan dentro de un grupo de estilos. Ese grupo, sin embargo, puede contener varios grupos dentro de él, como se muestra a continuación:

// Module style fields [ { "type": "group", "name": "styles", "tab": "STYLE", "children": [{ "name": "img_spacing", "label": "Spacing around image", "required": false, "type": "spacing", "default": { "padding": { "top": { "value": 10, "units": "px" }, "bottom": { "value": 10, "units": "px" }, "left": { "value": 10, "units": "px" }, "right": { "value": 10, "units": "px" } }, "margin": { "top": { "value": 10, "units": "px" }, "bottom": { "value": 10, "units": "px" } } } }] } ]

Los siguientes campos pueden utilizarse como campos de estilo en los módulos. Conoce cada uno de los tipos de campo en la guía de módulos y tipos de campo.

Más información sobre los tipos de campo de módulos y temas.

Ve la plantilla de CMS para un ejemplo de campos de estilo dentro del archivo fields.json de un módulo.

Campos de estilo del tema

Los campos de estilo agregados a un tema aparecerán en la barra lateral izquierda del editor de temas:

style-field-theme-editor0

Todos los campos de estilo dentro del archivo fields.json de un tema se agregarán a la barra lateral izquierda del editor de temas, en lugar de tener que ponerlos bajo un grupo de estilos, como se muestra a continuación:

// Theme style fields [ { "label": "Global colors", "name": "global_colors", "type": "group", "children": [ { "label": "Primary", "name": "primary", "type": "color", "visibility": { "hidden_subfields": { "opacity": true } }, "default": { "color": "#494A52" } }, { "label": "Secondary", "name": "secondary", "type": "color", "visibility": { "hidden_subfields": { "opacity": true } }, "default": { "color": "#F8FAFC" } } ] }, { "label": "Global fonts", "name": "global_fonts", "type": "group", "children": [ { "label": "Primary", "name": "primary", "type": "font", "visibility": { "hidden_subfields": { "size": true, "styles": true } }, "inherited_value": { "property_value_paths": { "color": "theme.global_colors.primary.color" } }, "default": { "fallback": "sans-serif", "font": "Lato", "font_set": "GOOGLE" } }, { "label": "Secondary", "name": "secondary", "type": "font", "visibility": { "hidden_subfields": { "size": true, "styles": true } }, "inherited_value": { "property_value_paths": { "color": "theme.global_colors.primary.color" } }, "default": { "fallback": "serif", "font": "Merriweather", "font_set": "GOOGLE" } } ] }, { "name": "branding_color", "label": "branding_color", "type": "color", "default": { "color": "#3b7bc0", "opacity": 60 }, "inherited_value": { "property_value_paths": { "color": "brand_settings.primaryColor" } } }, { "name": "secondary_branding_color", "label": "Secondary Branding color", "type": "color", "default": { "color": "#ff6b6b", "opacity": 60 }, "inherited_value": { "property_value_paths": { "color": "brand_settings.colors[2]" } } } ] } ]

Los siguientes campos pueden utilizarse como campos de estilo en los módulos. Conoce cada uno de los tipos de campo en la guía de módulos y tipos de campo.

Más información sobre los tipos de campo de módulos y temas.

Ve la plantilla del CMS para un ejemplo de campos de estilo dentro del archivo fields.json de un tema. 

Nota: si es un proveedor del mercado, no debe sustituir los campos de contenido existentes por campos de estilo en los módulos existentes. Cambiar la jerarquía de los campos en un archivo fields.json puede hacer que las instancias de los módulos existentes pierdan sus datos. En su lugar, debes agregar nuevos campos de estilo, o crear un nuevo listado que tenga los campos debidamente agrupados. Esto evitará que sus actualizaciones sean cambios de ruptura para los clientes que confían en sus temas. Para abogar por las vías de migración de los módulos antiguos, consulta el foro HubSpot Ideas.

CSS generado

Algunos campos de estilo ofrecen una forma de imprimir css directamente en función del valor del campo. Esto es especialmente útil con los campos que pueden controlar un estilo más complicado como los gradientes. Tipos de campo que tienen una propiedad generada .css :

  • Gradiente (solo puede utilizarse como campo de estilo)
  • Espaciado (solo puede utilizarse como campo de estilo)
  • Imagen de fondo (solo puede utilizarse como campo de estilo)
  • Borde (solo puede utilizarse como campo de estilo)
{% require_css %} <style> {% scope_css %} .team-member { {% if module.styles.gradient.css %} background: {{ module.styles.gradient.css }}; {% endif %} {{ module.styles.bg_img.css }} {{ module.styles.spacing.css }} {{ module.styles.border.css }} } {% end_scope_css %} </style> {% end_require_css %}

Repetidores

Al crear módulos que formatean información, a menudo hay tipos de información que se repiten. Un módulo de recetas, por ejemplo, puede tener un campo de "Ingrediente". Bueno, la mayoría de las recetas tienen más de un ingrediente. Podrías darles un campo de texto enriquecido, pero entonces pierdes tu capacidad de forzar un estilo consistente y agregar funcionalidad alrededor de cada ingrediente. Ahí es donde entran los repetidores, HubSpot tiene dos formas de repetidores: Campos repetidos y Grupos repetidos.

Campos repetidos

Los campos que se repiten son campos normales, pero los creadores de contenido pueden agregar, eliminar y reordenar las instancias del campo. Tomemos el ejemplo de nuestro módulo de recetas de antes, cada ingrediente podría ser un campo de texto repetido. Esto hace que el creador de contenido pueda agregar tantos ingredientes como desee. Desde el punto de vista del desarrollador, obtenemos una matriz que podemos recorrer para imprimir esa lista de ingredientes, aplicando el formato y la funcionalidad que queramos. 

campo de repetición

Los campos de repetición se utilizan mejor en situaciones muy sencillas. A menudo, la repetición de grupos tiene más sentido.

Campos repetidos en fields.json

// Repeating field example { "name" : "ingredient", "label" : "Ingredient", "required" : false, "locked" : false, "occurrence" : { "min" : 1, "max" : null, "sorting_label_field" : null, "default" : 1 }, "allow_new_line" : false, "show_emoji_picker" : true, "type" : "text", "default" : [ "1 cup water" ] }

Recorrer los elementos del módulo HTML+HubL

<!--Looping through a repeating field--> <ul> {% for item in module.ingredient %} <li>{{ item }}</li> {% endfor %} </ul>

Grupos de repetición

Los grupos de repetición son grupos de campos con la opción de repetición activada. Los grupos de repetición permiten a los creadores de contenido agregar, eliminar y reordenar grupos de campos. De nuevo utilizando el escenario del módulo de recetas, digamos que quieres integrar tu lista de ingredientes con una funcionalidad de lista de compra. La cantidad de un ingrediente sería fundamental. Mientras que alguien podría proporcionar eso en el campo de texto, entonces tendríamos que analizar el campo de texto y esperar que estemos separando con éxito la cantidad del ingrediente. Aquí es donde los grupos de repetición resultan útiles. La salida de estos campos es un objeto que se puede recorrer en bucle.

Grupo de campos que se repiten

Grupos repetidos en fields.json

// Repeating field group example { "id" : "ingredients", "name" : "ingredients", "label" : "Ingredients", "required" : false, "locked" : false, "occurrence" : { "min" : 1, "max" : null, "sorting_label_field" : "ingredients.ingredient", "default" : null }, "children" : [ { "id" : "ingredients.ingredient", "name" : "ingredient", "label" : "Ingredient", "required" : false, "locked" : false, "validation_regex" : "", "allow_new_line" : false, "show_emoji_picker" : false, "type" : "text", "default" : "Water" }, { "id" : "ingredients.quantity", "name" : "quantity", "label" : "Quantity", "required" : false, "locked" : false, "display" : "text", "min" : 0, "step" : 1, "type" : "number", "default" : 1 }, { "id" : "ingredients.measurement", "name" : "measurement", "label" : "Measurement", "help_text" : "Unit of measurement (cups, tbsp, etc.)", "required" : false, "locked" : false, "allow_new_line" : false, "show_emoji_picker" : false, "type" : "text", "default" : "cups" } ], "type" : "group", "default" : [ { "ingredient" : "Water", "quantity" : 1, "measurement" : "cups" } ] }

Recorrer los campos repetidos en los módulos

<h2>Ingredients</h2> <ul> {% for ingredient in module.ingredients %} <li> <button data-quantity="{{ ingredient.quantity }}" data-unit="{{ ingredient.measurement }}" data-ingredient="{{ ingredient.ingredient }}"> Add to cart </button> {{ ingredient.quantity }} {{ ingredient.measurement }} {{ ingredient.ingredient }} </li> {% endfor %} </ul>

Opciones del repetidor

Para mejorar la experiencia de edición y evitar que los editores de contenido proporcionen valores a los que no se ha dado cabida mediante programación, le permitimos establecer valores mínimos y máximos para el número de elementos que los creadores de contenido pueden agregar a un campo repetido o a un grupo repetido. 

En el caso de los grupos de repetición, también se puede establecer qué campo actúa como etiqueta para ese elemento cuando se ve el repetidor.

Número máximo de ocurrencias
"occurrence" : { "min" : 1, "max" : 4, "sorting_label_field" : "ingredients.ingredient", }
Opciones del repetidor
ParameterTypeDescription Default
max
Integer

Número máximo de apariciones de este grupo. Evita que el creador de contenido agregue más de este número de elementos en la interfaz gráfica.

null
min
Integer

Número mínimo de apariciones de este grupo de campos. Evita que los usuarios tengan menos de este número de elementos en la UI.

null
sorting_label_field
String

Este es el id del campo, del que se extrae el texto para mostrarlo en la UI en las tarjetas arrastrables. El valor predeterminado es el primer campo del grupo.

Campos heredados

La propiedad inherited_value se puede configurar para que un campo herede su valor predeterminado de otros campos. Para establecer todo el valor predeterminado de un campo a partir del valor de otro campo, establece en default_value_path la ruta del nombre del campo de destino. Cuando se establece default_value_path , se ignorará cualquier default establecido en el campo.

Para acceder a los valores de otros campos, las rutas deben incluir module. al principio, como si se accediera al valor en el código HubL del módulo.

// Inherited fields { "name": "body_font", "type": "font", "default": { "font": "Helvetica", "color": "#C27BA0" } }, { "name": "h1_font", "type": "font", "default": {}, "inherited_value": { "default_value_path": "module.body_font" } }

En el caso de los campos complejos (campos cuyos valores son objetos), los usuarios pueden tener una mayor granularidad sobre las propiedades que se heredan a través de property_value_path. Cualquier ruta referida en inherited_value también puede incluir claves del valor de un campo para los campos complejos; por ejemplo, los campos de color tienen valores de objeto que contienen el color mismo así como la opacidad. Así que para obtener el valor de color real de un color sin la opacidad, la ruta terminaría en .color. Por ejemplo, un campo de fuente puede heredar solo su color de otro campo de color:

// Inherited fields with objects { "name": "secondary_color", "type": "color", "default": { "color": "#C27BA0", "opacity": 100 } }, { "name": "h1_font", "type": "font", "default": { "font": "Helvetica", "size": 12, "size_unit": "px" }, "inherited_value": { "property_value_paths": { "color": "module.secondary_color.color" } } }

También puedes combinar los efectos de default_value_path y property_value_paths para heredar un valor predeterminado de un campo mientras se hereda un valor de propiedad específico de un campo diferente:

// combining the effects of default_value_path and property_value_paths { "name": "body_font", "type": "font", "default": { "font": "Helvetica", "color": "#000000" } }, { "name": "secondary_color", "type": "color", "default": { "color": "#C27BA0", "opacity": 100 } }, { "name": "h1_font", "type": "font", "default": {}, "inherited_value": { "default_value_path": "module.body_font", "property_value_paths": { "color": "module.secondary_color.color" } } }

Si un campo hereda de otro campo, pero luego se anula directamente en el nivel de la página o en la configuración del tema, su conexión con el campo de control se interrumpe. Cualquier otro campo que se adjunte a través de default_value_path o property_value_paths ya no afectará al valor del campo.

Tipos de campo

Para proporcionar una mejor experiencia en la referencia de la información, hemos separado la información del tipo de campo, de la información general de los campos. La información sigue existiendo en la página de referencia de los campos de módulos y temas.


¿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.