¿Qué plan tengo?

Disponible en los planes Suite Growth y superioresDisponible en todos los planes de Guide

Cuando se descarga un tema, los archivos exportados incluyen un archivo llamado manifest.json. El archivo define el panel Configuración del tema en Guide:

Esta guía describe el archivo de manifiesto y lo que puede hacer con él. También es una referencia de sus especificaciones. Por ejemplo, exporte un tema y abra el archivo manifest.json en un editor de texto.

Temas que se tratan:

  • Comprender el archivo manifest.json
  • Usar las opciones de configuración como variables en manifest.json
  • Modificar el archivo manifest.json
  • Objeto de manifiesto
  • Objeto de configuración
  • Objeto de variable
  • Propiedad de tipo
  • Tipo de archivo
  • Tipo de lista
  • Tipo de intervalo
  • Traducciones

Comprender el archivo manifest.json

Cuando se exporta un tema, los archivos exportados incluyen un archivo llamado manifest.json. Puede usar el archivo de manifiesto para definir el panel Configuración del tema en Guide.

En el panel, puede modificar la configuración actual o crear configuraciones nuevas. En el ejemplo a continuación, el archivo de manifiesto asigna un valor predeterminado de "#30aabc" a la configuración color_brand_text (color_texto_marca):

"settings": [
  {
    "label": "Colors",
    "variables": [
      {
        "identifier": "color_brand_text",
        "type": "color",
        "description": "color_brand_text_description",
        "label": "color_brand_text_label",
        "value": "#30aabc"
      },
      ...
    ]
  },
  ...
]

Después de importar el tema en Guide, la configuración color_brand_text aparece en el panel Configuración con el rótulo Brand text color (Color de texto de la marca), como lo especifica la propiedad “label” en el archivo de manifiesto, y el valor hexadecimal predeterminado del selector de color es #30aabc, como lo especifica la propiedad "value":

Usar las opciones de configuración como variables en manifest.json

A las opciones de configuración también se les llama variables porque es posible usar el identificador para este tipo de opciones como variables en los archivos de temas. Cuando se cambia un valor en el panel Configuración, se actualiza ese valor en todos los archivos que usan la variable.

Nota: Si encuentra un error de variable al importar el tema de Guide, es posible que haya un problema de formato. Si desea más información, consulte el artículo Error: La propiedad ‘#/settings/X/variables/X’ de tipo object no coincidió con ninguno de los esquemas requeridos.

Puede insertar una variable en el archivo style.css del tema usando la sintaxis $identifier, o bien en una plantilla de página usando el helper settings.identifier de Curlybars. Ejemplos:

style.css

input:focus {
  border: 1px solid $color_brand_text;
}

También puede usar llaves sencillas para incrustar el helper en una expresión de CSS de la siguiente manera:

max-width: #{$search_width}px;

Plantilla de página

<div style="background-color:{{settings.color_brand_text}}">

Modificar el archivo manifest.json

El archivo manifest.json no se incluye en la lista de archivos de la página Editar código del Centro de ayuda. Para editar el archivo manifest.json, debe exportar el tema a los archivos, hacer cambios en el archivo de manifiesto de su sistema e importar el tema en Guide.

Para exportar el tema

  • Consulte Descargar un tema del centro de ayuda.

Para importar el tema modificado

  • Consulte Importar un tema del centro de ayuda.

Objeto de manifiesto

El objeto de la raíz del documento del manifiesto tiene estas propiedades:

Nombre Tipo Comentario
name cadena Nombre de tema
author cadena La persona, el equipo o la organización que creó el tema
version cadena Versión del tema que observa la norma Versionado Semántico 2.0.0
api_version cadena Versión de API de creación de plantillas
settings matriz Lista de objetos de configuración. Consulte Objeto de configuración.

Ejemplo

{
  "name": "My second theme",
  "author": "Jane Doe",
  "version": "1.0.1",
  "api_version": 3,
  "settings": [
    ...
  ]
}

Objeto de configuración

En Guide, las opciones de configuración del archivo de manifiesto y del panel Configuración están organizadas en grupos como Colores y Fuentes. El grupo de cada opción está definido en el archivo de manifiesto por medio de un objeto de configuración. Cada objeto consiste en un rótulo y una o más opciones, como Color de la marca y Color de texto.

Puede modificar los objetos de configuración existentes o crear sus propios objetos. Cuando se importa el tema en Guide, los objetos se muestran en el panel Configuración del tema.

Cada objeto de configuración tiene las propiedades siguientes:

Nombre Tipo Comentario
label cadena Un nombre de la propiedad de traducción. Consulte Traducciones. Muestra un título para un grupo de opciones. 
variables matriz

Lista de opciones en el grupo. También se les llama variables. Consulte Objeto de variable. El archivo de manifiesto puede tener un máximo de 200 objetos de variable.

Consulte Límites del producto Guide para el centro de ayuda (Cantidad total de opciones de configuración en manifest.json).

Ejemplo

"settings": [
  {
    "label": "colors_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "fonts_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "brand_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "banners_group_label",
    "variables": [{...}, ...]
  }
]
Nota: El valor de las propiedades "label" corresponde a los nombres de propiedades de traducción. Consulte Traducciones.

Este ejemplo crea las categorías siguientes en el panel Configuración:

Objeto de variable

Cada objeto de opción de configuración tiene una matriz de variables que enumera las opciones reales. Se les llama variables porque se pueden insertar como tales en las plantillas del Centro de ayuda o en un archivo CSS. Consulte Límites del producto Guide para el centro de ayuda (Cantidad total de opciones de configuración en manifest.json).

Puede definir todas las variables que desee. Sin embargo, el archivo de manifiesto debe incluir dos variables de archivo con los identificadores siguientes: "logo" y "favicon". Consulte Variables obligatorias.

Cada variable tiene las propiedades siguientes:

Nombre Tipo Comentario
identifier cadena Nombre de variable que se puede usar en las expresiones de CSS o de Curlybars. Debe tener 30 caracteres o menos y contener solo caracteres alfanuméricos y el carácter de _ (subrayado).
type cadena Control de la interfaz de usuario en el panel Configuración de Guide para obtener el valor del usuario. Una de estas: text, list, checkbox, color, file o range. Consulte Propiedad de tipo.
label cadena

El nombre de la configuración que se muestra junto al control de la interfaz de usuario en el panel Configuración. Admite un máximo de 40 caracteres.

Para traducir este valor, utilice un nombre de propiedad de traducción. Consulte Traducciones. Las traducciones no tienen un límite de caracteres.
description cadena

Una descripción corta de la configuración que se muestra junto al control de la interfaz de usuario en el panel Configuración. Admite un máximo de 80 caracteres.

Para traducir este valor, utilice un nombre de propiedad de traducción. Consulte Traducciones. Las traducciones no tienen un límite de caracteres.
value cadena El valor predeterminado de la configuración
options matriz Solo para el tipo list. Una matriz de elementos. Consulte Objeto de opción.
min entero Solo para el tipo range. El valor mínimo del intervalo
max entero Solo para el tipo range. El valor máximo del intervalo

Ejemplo

"variables": [
  {
    "identifier": "color_brand",
    "type": "color",
    "label": "color_brand_label",
    "description": "color_brand_description",
    "value": "#0072EF"
  },
  ...
]

Este ejemplo crea el rótulo y el control siguientes en el panel Configuración:

Variables obligatorias

Debe especificar las dos variables siguientes en el archivo de manifiesto, de lo contrario, el archivo será rechazado al importarlo:

  • logo: el identifier debe ser "logo" y el type debe ser "file"
  • favicon: el identifier debe ser "favicon" y el type debe ser "file"

Ejemplo

"variables": [
  {
    "identifier": "logo",
    "type": "file",
    "description": "logo_description",
    "label": "logo_label"
  },
  {
    "identifier": "favicon",
    "type": "file",
    "description": "favicon_description",
    "label": "favicon_label"
  }
]

Propiedad de tipo

Cada objeto de variable tiene una propiedad type que especifica un control de interfaz de usuario para establecer el valor de la opción en el panel Configuración de Guide. La propiedad puede tener uno de los siguientes valores:

  • text: campo para ingresar texto. Cada campo de texto tiene un límite de 1000 caracteres.
  • list: lista desplegable. Incluye una lista de objetos de opción para los elementos. Consulte Tipo de lista.
  • checkbox: casilla de verificación. Consulte Tipo de casilla de verificación.
  • color: selector de color.
  • file: cargador de archivos. Consulte Tipo de archivo.
  • range: campo para ingresar intervalo. Consulte Tipo de intervalo.

Ejemplo

{
  "identifier": "color_headings",
  "type": "color",
  ...
}

Tipo de lista

Si el tipo de un objeto de variable es "list" ("lista"), el objeto incluye una matriz options para rellenar la lista desplegable. Cada opción de la lista tiene las propiedades siguientes:

Nombre Tipo Comentario
label cadena

Texto descriptivo que se muestra para el elemento. Admite un máximo de 40 caracteres.

Para traducir este valor, utilice un nombre de propiedad de traducción. Consulte Traducciones. Las traducciones no tienen un límite de caracteres.
value cadena Valor subyacente del elemento

Se debe especificar más de una opción en la matriz para que el tema se importe sin errores. El número de opciones no debe ser superior a 20. Consulte Límites del producto Guide para el centro de ayuda (Número total de opciones en una configuración de tipo de lista).

Ejemplo

{
  "identifier": "font_headings",
  "type": "list",
  "label": "Heading",
  "description": "Font for headings",
  "value": "Arial, 'Helvetica Neue', Helvetica, sans-serif",
  "options": [
    {
      "label": "Arial",
      "value": "Arial, 'Helvetica Neue', Helvetica, sans-serif"
    },
    {
      "label": "Copperplate Light",
      "value": "'Copperplate Light', 'Copperplate Gothic Light', serif"
    },
    {
      "label": "Baskerville",
      "value": "Baskerville, 'Times New Roman', Times, serif"
    }
  ]
}

Tipo de casilla de verificación

Si el tipo de un objeto de variable es “checkbox” (casilla de verificación), utilice la propiedad value del objeto para especificar el valor que se establece cuando el usuario selecciona la casilla de verificación. El valor debe ser booleano.

Nombre Tipo Comentario
value booleano true o false

Ejemplo

{
  "identifier": "scoped_hc_search",
  "type": "checkbox",
  "description": "scoped_help_center_search_description",
  "label": "scoped_help_center_search_label",
  "value": true
}

Tipo de archivo

Un objeto de variable con un tipo de "file" añade un control de cargador de archivos en el panel Configuración. Este tipo de variable no tiene una propiedad valor. Ejemplo:

{
  "identifier": "community_image",
  "type": "file",
  "description": "community_image_description",
  "label": "community_image_label"
}

El valor es la dirección URL de un archivo que el sistema determina.

Debe proporcionar el archivo predeterminado que el tema usará hasta que un usuario cargue un archivo distinto. El nombre del archivo predeterminado debe coincidir con el identificador de la variable. Coloque el archivo en la carpeta settings de sus archivos de temas. Ejemplo:

Use variables de archivo donde se prevén direcciones URL en los archivos de temas. Ejemplos:

style.css

.community_banner {
    background-image: url($community_image);
}

Plantilla de página

<img src="{{settings.community_image}}">

Tipo de intervalo

Un objeto de variable del tipo de intervalo (“range”) añade un control deslizador en el panel Configuración. Ejemplo:

Una variable de intervalo incluye una propiedad min y una max para especificar el intervalo de valores que el usuario puede establecer al mover el deslizador. Los valores deben ser enteros.

Ejemplo

{
  "identifier": "font_size",
  "type": "range",
  "description": "font_size_description",
  "label": "font_size_label",
  "min": 70,
  "max": 150,
  "value": 100
}

Traducciones

Las cadenas visibles en el panel Configuración se definen todas en translations. Una traducción consta de un nombre de propiedad y un valor. Ejemplo:

"text_color_label": "Text color"

Los nombres de las propiedades son arbitrarios: se puede usar cualquier nombre que se desee.

Las traducciones se guardan en archivos JSON según el idioma en la carpeta translations de la carpeta raíz del tema:

/ translations
   - en-us.json
   - es.json
   - fr.json
   - ...

Cada archivo contiene un objeto JSON con una lista de traducciones:

en-us.json

{
  "brand_color_description": "Brand color for major navigational elements",
  "brand_color_label": "Brand color",
  ...
}

Las traducciones se usan para especificar los rótulos y las descripciones en el panel Configuración.

Para especificar las cadenas para rótulos y descripciones

  1. En la carpeta translations, ubique el archivo JSON para el idioma predeterminado del Centro de ayuda. Ejemplo: en-us.json.

  2. Actualice los valores de las propiedades existentes o agregue nuevas propiedades. Ejemplo:

    {
  "text_color_label": "Text color",
  "text_color_description": "Text color for body and heading elements",
  ...
}

  3. En las variables, use el nombre de propiedad de traducción como valor de los atributos "label" o "description".

    "variables": [
  {
    "identifier": "color_text",
    "type": "color",
    "label": "text_color_label",
    "description": "text_color_description",
    "value": "#0072EF"
  },
  ...
]

    Consulte Objeto de variable. Si crea una propiedad o cambia el nombre de una propiedad, asegúrese de actualizar sus variables.

En el panel Configuración, puede localizar los rótulos y las descripciones. Para ello, es necesario que proporcione las cadenas localizadas.

Para localizar rótulos y descripciones

  1. En la carpeta translations, ubique el archivo JSON para cada idioma adicional que desea admitir.

  2. Copie los nombres de propiedad definidos en su archivo de traducción predeterminado. Ejemplo:

    {
  "text_color_description": "",
  "text_color_label": "",
  ...
}

  3. Especifique una cadena localizada por cada propiedad. Ejemplos:

    fr.json

    {
  "text_color_description": "Couleur du texte pour les éléments du titre et du corps",
  "text_color_label": "Couleur du texte",
  ...
}
Tecnología de Zendesk