API de configuración de temas

¿Cómo acceder a los valores de las opciones de configuración del tema en el tema?

Se puede acceder fácilmente a cada valor de opción de tema a través de la variable global @config . Esa variable contiene el campo personalizado , que es un objeto donde la clave es el campo de nombre  utilizado en la definición de la opción.

Por ejemplo, si desea acceder a un valor de la opción que utiliza como nombre el valor headerColor , debe escribir en su tema:

{{ @config.custom.headerColor }}

El código anterior generará el valor de la opción headerColor .

¿Cómo acceder a los valores de las opciones de configuración de la publicación en el tema?

Las opciones de configuración de la publicación son accesibles de dos maneras:

• a través de la sintaxis @config.post.* que funciona de la misma manera que la sintaxis @config.custom.* para la opción de tema
• a través  del objeto postViewConfig en el elemento de publicación . 

¡Atención! La sintaxis @config.post.* solo funciona con plantillas de publicaciones individuales. En las páginas con listas de publicaciones, debe utilizar el objeto postViewConfig .

Por ejemplo, para obtener el valor de la opción de publicación definida con el nombre headerColor, puede utilizar en el archivo post.hbs (y también en cualquier plantilla de publicación personalizada ) la siguiente sintaxis:

{{ @config.post.headerColor }}

Si desea obtener el mismo valor en la lista de publicaciones (por ejemplo, en la página de inicio), debe utilizar:

{{ postViewConfig.headerColor }}

Dentro del contexto del artículo de publicación:

{{#each posts}}
    <h2 style="color: {{ postViewConfig.headercolor }};">
        {{ title }}
    </h2>
{{/each}}

El código anterior mostrará la lista de publicaciones con el uso del color de texto especificado por publicación.

¿Cómo crear configuraciones de publicaciones relacionadas con plantillas de publicaciones?

Es posible crear opciones de publicación que se mostrarán solo si se utiliza la plantilla de publicación específica (si las plantillas de publicación están disponibles en su tema).

Debes utilizar el parámetro postTemplates . Puede definirse como un nombre de plantilla de publicación único:

 
{
     "name": "displayAuthor",
     "label": "Display author name",
     "value": 1,
     "type": "select",
     "postTemplates": "alternative",
     "options": [
          {
              "label": "Enabled",
              "value": 1
          },
          {
              "label": "Disabled",
              "value": 0
          }
    ]
}  

o como nombres de plantillas de publicaciones múltiples (separados por coma):

...
"postTemplates": "alternative,test,portfolio", 
...

Si necesita ocultar opciones de publicación específicas para los nombres de plantillas de publicación indicados, anteponga el valor del parámetro postTemplates con un signo de exclamación:

...
"postTemplates": "!alternative,test,portfolio", 
...

En el ejemplo anterior, la configuración de publicación especificada no se mostrará para las plantillas de publicaciones alternativas y de cartera.

Enlace interno entre opciones

Es posible crear enlaces internos entre opciones utilizando campos de nota.

Para crear enlaces internos, cree enlaces con el atributo data-internal-link :

<a href="#" data-internal-link="Fonts">Link A</a>
<a href="#" data-internal-link="Fonts#headings">Link B</a>

El enlace A conducirá a un grupo llamado Fuentes, mientras que el enlace B conducirá a una opción que contiene un campo de anclaje configurado como "encabezados":

{
     "anchor": "headings",
     "name": "separator",
     "type": "separator",
     "label": "Headings",
     "group": "Fonts",
     "note": "Please note: not all of the font weights are working with the fonts listed above.",
     "size": "big"
}

Clases CSS personalizadas para campos

Para mejorar la flexibilidad y la personalización de la interfaz de usuario de Publii, hemos introducido el customCssClassesatributo para campos dentro de complementos, temas y repetidores. Esta función permite a los desarrolladores asignar una o más clases CSS personalizadas a un campo específico, lo que proporciona un mayor control sobre el estilo de los componentes de la interfaz de usuario individuales.

Cómo agregar una única clase CSS personalizada

Para agregar una sola clase CSS personalizada a un campo, use la customCssClassespropiedad en la configuración JSON del campo. Especifique el nombre de la clase como el valor de esta propiedad. Por ejemplo:

{
  "name": "exampleField",
  "label": "Example Field",
  "type": "text",
  "customCssClasses": "unique-class-name"
}

Esto aplicará la unique-class-nameclase CSS al exampleFieldelemento en la interfaz de usuario de Publii.

Cómo agregar múltiples clases CSS personalizadas

También puedes asignar varias clases CSS a un campo separando los nombres de clase con un espacio. Esto permite una personalización aún más detallada del estilo del campo. Por ejemplo:

{
  "name": "exampleField",
  "label": "Example Field",
  "type": "text",
  "customCssClasses": "unique1-class-name unique2-class-name unique3-class-name"
}

En este ejemplo, exampleFieldse aplicarán tres clases CSS independientes al elemento: unique1-class-name, unique2-class-namey unique3-class-name. Esto permite aplicar varias reglas de estilo al mismo campo para lograr efectos visuales más complejos y variados.

Notas de uso

• Asegúrate de que las clases CSS personalizadas que definas estén declaradas correctamente en los archivos CSS de tu tema o complemento. Las clases no definidas no afectarán la apariencia del campo.
• El customCssClassesatributo se puede utilizar con cualquier tipo de campo, lo que proporciona una herramienta versátil para la personalización de la interfaz de usuario en todo su sitio Publii.
• La combinación de varias clases permite un enfoque granular y en capas para el estilo, creando una interfaz más refinada y fácil de usar.

Al aprovechar este customCssClassesatributo, los desarrolladores pueden mejorar significativamente la apariencia y la experiencia del usuario de la interfaz de configuración de temas de Publii. Este atributo permite agregar una o más clases CSS personalizadas a campos de configuración individuales, lo que proporciona un método directo para aplicar opciones de estilo específicas. Dicha personalización garantiza que la interfaz de configuración de temas se alinee perfectamente con la visión de diseño del desarrollador, lo que facilita una experiencia de configuración del usuario más intuitiva y visualmente coherente. Esta capacidad subraya la flexibilidad y adaptabilidad de Publii, lo que permite a los desarrolladores crear paneles de configuración de temas altamente personalizados y fáciles de usar.

Mejorar la interfaz de usuario de configuración del tema con CSS personalizado

Publii presenta una potente función que permite a los desarrolladores de temas personalizar aún más la apariencia de las opciones del tema mediante clases CSS personalizadas. Esta mejora no se limita únicamente a los temas, sino que se extiende a los complementos y repetidores, lo que garantiza una interfaz de usuario uniforme y visualmente atractiva.

Con la customThemeOptionsCssfunción habilitada en la configuración supportedFeatures , Publii ahora permite cargar un archivo theme-options.css directamente desde el directorio principal del tema. Este archivo CSS dedicado proporciona un enfoque centralizado para diseñar la configuración del tema, lo que facilita a los desarrolladores la gestión y actualización de la presentación visual de las opciones configurables de su tema.

El theme-options.cssarchivo debe colocarse en el directorio principal del tema, siguiendo esta ruta: 

\Documents\Publii\sites\your-siteName\input\themes\your-theme-name\

Por ejemplo, si su tema se llama Simple , la estructura se vería así:

- input
  |- themes
     |- simple
        |- theme-options.css
        |- index.hbs
        ...

Esta ruta de archivo garantiza que el theme-options.cssarchivo se cargue correctamente y se aplique a la configuración del tema en la interfaz de Publii. Para utilizar esta función, debe habilitarla explícitamente en la configuración de su tema. Incluya el siguiente código en config.jsonel archivo de su tema en la sección supportedFeatures :

"supportedFeatures": {
    "customThemeOptionsCss": true
}