Quale piano sto usando?

Disponibile in tutti i piani Suite Growth e superioriDisponibile in tutti i piani Guide

Quando scarichi un tema, i file esportati includono un file denominato manifest.json. Il file definisce il pannello Impostazioni del tema in Guide:

Questa guida descrive il file manifest e illustra le operazioni che puoi eseguire con tale file. Inoltre, fornisce un riferimento per le specifiche. Per vedere un esempio, esporta il tema e apri il file manifest.json in un editor di testo.

Argomenti trattati:

  • Informazioni sul file manifest.json
  • Uso delle impostazioni in manifest.json come variabili
  • Modifica del file manifest.json
  • Oggetto Manifest
  • Oggetto Setting
  • Oggetto Variable
  • Tipo di proprietà
  • Tipo di file
  • Tipo di elenco
  • Tipo di intervallo
  • Traduzioni

Informazioni sul file manifest.json

Quando esporti un tema, i file esportati includono un file denominato manifest.json. Puoi usare il file manifest per definire il pannello Impostazioni del tema in Guide.

Puoi modificare le impostazioni esistenti nel pannello o crearne di nuove. Nell'esempio seguente, il file manifest assegna il valore predefinito "#30aabc" all'impostazione color_brand_text:

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

Una volta importato il tema in Guide, l'impostazione color_brand_text viene visualizzata nel pannello Impostazioni con l'etichetta Colore testo brand, come specificato dalla proprietà "label" nel file manifest, e il valore esadecimale predefinito del selettore colori è #30aabc, come specificato dalla proprietà “value”:

Uso delle impostazioni in manifest.json come variabili

Le impostazioni sono dette anche variabili perché è possibile usare l’identificatore di un’impostazione come variabile nei file del tema. La modifica di un valore nel pannello Impostazioni aggiorna il valore in tutti i file che usano la variabile.

Nota: se si verifica un errore con la variabile durante l’importazione del tema Guide, potrebbe esserci un problema con la formattazione. Per ulteriori informazioni, leggi l’articolo Errore: la proprietà '#/settings/X/variables/X' di tipo oggetto non corrisponde a nessuno degli schemi richiesti.

Puoi inserire una variabile nel file style.css del tema usando la sintassi $identifier o in un modello di pagina usando l’helper settings.identifier in Curlybars. Esempi:

style.css

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

Puoi anche usare singole parentesi graffe per incorporare l’helper in un’espressione CSS, nel modo seguente:

max-width: #{$search_width}px;

Modello di pagina

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

Modifica del file manifest.json

Il file manifest.json non è incluso nell’elenco di file della pagina Modifica codice del centro assistenza. Per modificare il file manifest.json, è necessario esportare il tema nei file, apportare modifiche al file manifest sul sistema e importare il tema in Guide.

Per esportare il tema

  • Consulta Download di un tema del centro assistenza.

Per importare il tema modificato

  • Consulta Importazione di un tema del centro assistenza.

Oggetto Manifest

L’oggetto radice documento del file manifest presenta le seguenti proprietà:

Nome Tipo Commento
name stringa Nome del tema
author stringa La persona, il team o l’organizzazione che ha creato il tema
version stringa Versione del tema conforme allo standard Versionamento Semantico 2.0.0
api_version stringa Versione API per modelli
settings array Elenco di oggetti impostazione. Vedi Oggetto Setting

Esempio

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

Oggetto Setting

Sia nel file manifest, sia nel pannello Impostazioni di Guide le impostazioni sono organizzate in gruppi come Colori o Caratteri. Ciascun gruppo di impostazioni è definito nel file manifest da un oggetto Setting. Ogni oggetto è costituito da un’etichetta e da una o più impostazioni, come Colore brand e Colore testo.

Puoi modificare gli oggetti setting o crearne di personalizzati. Gli oggetti si riflettono nel pannello Impostazioni del tema quando quest’ultimo viene importato in Guide.

Ogni oggetto Setting presenta le seguenti proprietà:

Nome Tipo Commento
etichetta stringa Nome di una proprietà di traduzione. Consulta Traduzioni. Mostra il titolo di un gruppo di impostazioni. 
variables array

Elenco delle impostazioni del gruppo, dette anche variabili. Vedi Oggetto Variable. Il file manifest può contenere un massimo di 200 oggetti variabili.

Consulta Limiti dei prodotti Guide per il tuo centro assistenza (Numero totale di impostazioni in manifest.json).

Esempio

"settings": [
  {
    "label": "colors_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "fonts_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "brand_group_label",
    "variables": [{...}, ...]
  },
  {
    "label": "banners_group_label",
    "variables": [{...}, ...]
  }
]
Nota: il valore delle proprietà "label" consiste nei nomi di proprietà di traduzione. Vedi Traduzioni.

Il precedente esempio genera le seguenti categorie nel pannello Impostazioni:

Oggetto Variable

Ogni Oggetto Setting ha un array variables che elenca le impostazioni effettive. Si chiamano variabili perché puoi inserirle come variabili nei modelli del centro assistenza o in CSS. Consulta Limiti dei prodotti Guide per il tuo centro assistenza (Numero totale di impostazioni in manifest.json).

Puoi definire tutte le variabili che desideri. Tuttavia, il file manifest deve contenere due variabili di file con i seguenti identificatori: "logo" e "favicon". Vedi Variabili obbligatorie.

Ciascuna variabile presenta le seguenti proprietà:

Nome Tipo Commento
Identificatore stringa Nome di variabile che può essere usato nelle espressioni CSS o Curlybars. Non può superare i 30 caratteri e può contenere solo caratteri alfanumerici e _ (carattere di sottolineatura)
tipo stringa Controllo dell’interfaccia utente nel pannello Impostazioni in Guide per ottenere il valore dall’utente. I tipi possibili sono text, list, checkbox, color, file e range. Vedi Tipo di proprietà
etichetta stringa

Il nome dell’impostazione che viene visualizzato accanto al controllo interfaccia utente nel pannello Impostazioni deve avere al massimo 40 caratteri.

Per tradurre questo valore, usa il nome di una proprietà di traduzione. Vedi Traduzioni. Le traduzioni non hanno un limite di caratteri.
descrizione stringa

Una breve descrizione dell’impostazione visualizzata accanto al controllo interfaccia utente nel pannello Impostazioni deve avere al massimo 80 caratteri.

Per tradurre questo valore, usa il nome di una proprietà di traduzione. Vedi Traduzioni. Le traduzioni non hanno un limite di caratteri.
valore stringa Il valore predefinito dell’impostazione
opzioni array Solo per il tipo list. Array di voci di elenco. Vedi Oggetto opzione
min numero intero Solo per il tipo range. Il valore minimo dell’intervallo
max numero intero Solo per il tipo range. Il valore massimo dell’intervallo

Esempio

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

Il precedente esempio genera l’etichetta e il controllo seguenti nel pannello Impostazioni:

Variabili obbligatorie

Affinché il file non venga rifiutato al momento dell’importazione, è necessario specificare le due variabili seguenti nel file manifest:

  • logo: la proprietà identifier deve essere “logo” e la proprietà type deve essere “file”
  • favicon: la proprietà identifier deve essere “favicon” e la proprietà type deve essere “file”

Esempio

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

Tipo di proprietà

Ogni oggetto Variable presenta una proprietà type che specifica un controllo dell’interfaccia utente per la configurazione del valore di impostazione nel pannello Impostazioni in Guide. La proprietà può avere uno dei seguenti valori:

  • text: campo di immissione del testo. Ogni campo del testo ha un limite di 1000 caratteri.
  • list: elenco a discesa. Include un elenco di oggetti opzione per le voci dell’elenco. Vedi Tipo elenco
  • checkbox: casella di spunta. Vedi Tipo casella di spunta
  • color: selettore colore
  • file: caricamento file. Vedi Tipo file
  • range: campo di immissione dell’intervallo. Vedi Tipo intervallo

Esempio

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

Tipo di elenco

Se la proprietà type di un oggetto Variable è "list", l'oggetto include un array options per il popolamento dell’elenco a discesa. Ciascuna delle opzioni dell’elenco presenta le seguenti proprietà:

Nome Tipo Commento
etichetta stringa

Il testo descrittivo visualizzato per la voce dell’elenco deve avere al massimo 40 caratteri.

Per tradurre questo valore, usa il nome di una proprietà di traduzione. Vedi Traduzioni. Le traduzioni non hanno un limite di caratteri.
valore stringa Valore sottostante della voce dell’elenco

Affinché l’importazione del tema vada a buon fine, è necessario specificare più di un’opzione nell’array. Il numero di opzioni non deve superare 20. Vedi Limiti dei prodotti Guide per il tuo centro assistenza (impostazione del numero totale di opzioni in un tipo di elenco).

Esempio

{
  "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 casella di spunta

Se la proprietà type di un oggetto Variable è "checkbox", usa la proprietà value dell'oggetto per specificare il valore che deve essere impostato quando l'utente seleziona la casella di spunta. Il valore deve essere un valore booleano.

Nome Tipo Commento
valore booleano true oppure false

Esempio

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

Tipo di file

Un oggetto Variable con “file” come proprietà type aggiunge un controllo di caricamento file nel pannello Impostazioni. Questo tipo di variabile non ha una proprietà value. Esempio:

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

Il valore è un URL di file definito dal sistema.

È necessario fornire un file predefinito che possa essere utilizzato dal tema finché un utente non carica un altro file. Il nome del file predefinito deve corrispondere all’identificatore della variabile. Inserisci il file nella cartella delle impostazioni nei file di tema. Esempio:

Usa variabili di file in cui siano previsti gli URL nei file di tema. Esempi:

style.css

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

Modello di pagina

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

Tipo intervallo

Un oggetto Variable con “range” come proprietà type aggiunge un controllo dispositivo di scorrimento nel pannello Impostazioni. Esempio:

Una variabile “range” include una proprietà min e una proprietà max per specificare l’intervallo di valori che l’utente può impostare quando sposta il dispositivo di scorrimento. I valori devono essere numeri interi.

Esempio

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

Traduzioni

Tutte le stringhe visualizzate nel pannello Impostazioni sono definite nelle traduzioni. Una traduzione è costituita dal nome e dal valore di una proprietà. Esempio:

"text_color_label": "Text color"

I nomi delle proprietà sono arbitrari. Puoi specificare il nome che preferisci.

Le traduzioni sono memorizzate in file JSON specifici per la lingua nella cartella translations, nella cartella principale del tema:

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

Ogni file consiste in un oggetto JSON con un elenco di traduzioni:

en-us.json

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

Le traduzioni vengono usate per specificare etichette e descrizioni nel pannello Impostazioni.

Per specificare stringhe per etichette e descrizioni

  1. Nella cartella translations, individua il file JSON per la lingua predefinita del centro assistenza. Esempio: en-us.json.

  2. Aggiorna i valori delle proprietà esistenti o aggiungine di nuove. Esempio:

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

  3. Nelle variabili, usa il nome della proprietà di traduzione come valore degli attributi "label" o "description".

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

    Vedi Oggetto Variable. Se crei una proprietà o ne modifichi il nome, assicurati di aggiornare le variabili.

Puoi localizzare le etichette e le descrizioni nel pannello Impostazioni. Dovrai occuparti di persona di fornire le stringhe localizzate.

Per localizzare etichette e descrizioni

  1. Nella cartella translations, individua il file JSON per ciascuna lingua aggiuntiva che vuoi supportare.

  2. Copia i nomi delle proprietà definiti nel file traduzioni predefinito. Esempio:

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

  3. Specifica una stringa localizzata per ciascuna proprietà. Esempi:

    fr.json

    {
  "text_color_description": "Couleur du texte pour les éléments du titre et du corps",
  "text_color_label": "Couleur du texte",
  ...
}
Powered by Zendesk