Desarrollando temas del discurso y componentes del tema

Documentación Guías para desarrolladores
, ,
1

Discourse Themes and Theme Components can be used to customize the look, feel and functionality of Discourse’s frontend. This section of the developer guides aims to provide all the reference materials you need to develop simple themes for a single site, right up to complex open-source theme components.

This introduction aims to provide a map of all the tools and APIs for theme development. If you prefer a step-by-step tutorial for theme development, jump straight to:

Themes vs. Theme Components

Discourse Themes can be used to customize the frontend user experience using CSS and JavaScript. Each theme has its own git repository, and community admins can generally install and manage them via the Discourse admin panel, even on shared hosting platforms.

Theme Components are themes which are intended for use alongside other Theme Components, as part of an overall Theme. From a development point of view, Theme Components and Themes are almost identical. In these guides, the phrase “Theme” and “Theme Component” are used interchangeably.

Prerequisites

Firstly, make sure you understand how to use existing themes and theme components in Discourse. Using ready-made themes is the quickest and safest way to customize your community. If you need more, then it’s time to consider writing your own theme.

As part of Discourse’s overall architecture, Discourse Themes are built using standard HTML, CSS, JavaScript technologies, and make use of Ember concepts for more advanced UIs. These reference guides assume a base-level understanding of these technologies, and link out to external references where possible.

Discourse is a fast-moving project, and as such any custom theme will require maintenance over time. Make sure you consider this as part of your planning & development processes.

Getting Started

Frontend Customization

More!

Check out the rest of the Developer Guides !

This document is version controlled - suggest changes on github.

142 Me gusta
136

Hay muchos enlaces y referencias antiguos y/o rotos en la sección The PluginApi - modifyClass()…

Este archivo ha cambiado tanto que checkReplyLength ya ni siquiera existe…

Y más adelante en la misma sección:

Este enlace simplemente resulta en un error de “404 - Página no encontrada”…

Me di por vencido al usar esta documentación después de eso…

4 Me gusta
137

Se dividió una publicación en un nuevo tema: ¿Plantilla o widget de tarjeta de usuario?

138

La documentación parece un poco desactualizada en esta parte… (además, api.modifyClass se queja de que falta pluginId). ¿Cómo puedo ejecutar un script cuando se carga about-page? Este no parece funcionar (aunque no hay errores). He tenido resultados mixtos con algunos otros componentes. Gracias.

<script type="text/discourse-plugin" version="0.11.1">

api.modifyClass("component:about-page", {
  pluginId: 'discourse-about-theme',

  didInsertElement() {
    this._super(...arguments);
    console.log("¡Bienvenido a la página about!");
  }

});

</script>
1 me gusta
139

Hola :wave: about-page ahora está en .gjs, lo que también significa que ya no se puede modificar de esa manera. Si quieres hacer cambios, tienes que usar uno de los conectores disponibles en esa página.

Puedes comprobarlos fácilmente con Plugin outlet locations theme component o comprobar en el archivo <PluginOutlet>.

4 Me gusta
142

Muchas gracias. Tiene sentido. He utilizado un conector en su lugar, funciona bien.

2 Me gusta
143

¿Sigue siendo precisa esta guía? La leí entera para intentar crear un componente de tema y luego miré los componentes de tema de ejemplo y ninguno de ellos utiliza las instrucciones que se supone que deben usar. Por ejemplo, al mirar el componente de tema discourse-brand-header, parece que se ha refactorizado de usar cosas como api.createwidget en header.html a usar un código totalmente diferente con inicializadores, componentes, etc. Código extremadamente complejo. La guía habla de usar el método API con widgets, pero eso no es lo que usan ninguno de los componentes. ¿Hay una guía actualizada o algo para usar componentes?

Edición: Supuestamente la API de widgets va a desaparecer, pero ¿hay alguna guía sobre qué usar en su lugar? ¿Toda la guía aquí parece basarse en código obsoleto?

3 Me gusta
144

Es cierto. La guía debería actualizarse. Sin embargo, algunas partes siguen siendo muy relevantes, como la estructura de los archivos, etc.

2 Me gusta
145

Sí, parece que SCSS es relevante, pero por lo demás, parece que todos los componentes de temas de ejemplo usan Componentes y han sido refactorizados a una base de código completamente diferente de lo que se enseña aquí. Revisé todos los componentes a los que enlazan en la sección de la API de complementos y cada uno ha sido refactorizado de una manera totalmente diferente a lo que se enseña aquí en la guía. Los widgets ya no se usan en absoluto. Todo son Componentes. ¿Hay una guía sobre cómo usar correctamente los nuevos Componentes, ya que los Widgets están desapareciendo?

2 Me gusta
146

Así que me encontré con esta publicación, por ejemplo, ahora mismo: Upcoming Header Changes - Preparing Themes and Plugins - ¿entonces refactorizaron todo, desde widgets heredados hasta componentes Glimmer? Pero este tutorial son todos widgets heredados. ¿Qué son exactamente los componentes Glimmer y hay alguna guía? Me siento afortunado de haberlo descubierto temprano, antes de comenzar a desarrollar con widgets heredados. ¿Quizás agregar una nota en esta guía de que los widgets son heredados y ya no deberían usarse?

2 Me gusta
147

Ok, veo que Glimmer son nuevos componentes de Ember. Pero, le eché un vistazo al código de TOC de Discourse y, oh, Dios mío… lo que antes tenía como 10 líneas de código ahora tiene como cientos de líneas en muchos archivos con clases complejas, decoradores, etc. Supongo que Ember tuvo un momento tipo React y decidió que volvamos a complicar las cosas. Parece que los componentes de tema ya no son fáciles, con una simple API de widgets, sino que requieren una codificación extensa…

2 Me gusta
148

@ddsgad sí, tienes razón, la mayor parte de esta guía está extremadamente desactualizada. He estado trabajando en mejoras generales de la documentación recientemente y espero actualizar/reemplazar esta en las próximas semanas.

Como has mencionado, ejemplos del mundo real como DiscoTOC pueden ser una buena referencia. Y aquí tienes algunas guías específicas que están más actualizadas:

Para obtener información general sobre Ember y sus componentes, te recomiendo consultar las guías de Ember.

6 Me gusta
149

Gracias por esos enlaces. Muy útil. Actualmente, básicamente solo personalizamos cosas en un tema de Discourse (la primera publicación) para hacer mejores diseños, por lo que hemos podido hacer básicamente todo con JavaScript plano (querySelectorAll, etc.) y SCSS, así que supongo que nos quedaremos con eso por ahora.

3 Me gusta
150

El tutorial largo y desactualizado en el OP ha sido reemplazado con información más general de introducción/señalización, incluido un enlace a un tutorial de 7 pasos completamente nuevo que sigue patrones de desarrollo de temas mucho más modernos.

4 Me gusta
151

¡He leído todo, me ha gustado! Bien explicado y muy buena introducción.

3 Me gusta
152

¡Me encantan estas guías! Finalmente descifré api.decorateCookedElement, ¡gracias de nuevo por la útil documentación!

4 Me gusta