Sviluppo di temi del discorso e componenti del tema

Documentazione Guide per sviluppatori
, ,
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 Mi Piace
136

Un sacco di link e riferimenti vecchi e/o non più validi nella sezione The PluginApi - modifyClass().

Questo file è cambiato così tanto che checkReplyLength non esiste più…

E più avanti nella stessa sezione:

Questo link porta semplicemente a un errore “404 - Pagina non trovata”…

Ho rinunciato a usare questi documenti dopo questo…

4 Mi Piace
137

Un post è stato diviso in un nuovo argomento: Modello o widget della scheda utente?

138

La documentazione sembra un po’ datata in questa parte… (anche api.modifyClass si lamenta della mancanza di pluginId). Come posso eseguire uno script quando viene caricata la about-page? Questa non sembra funzionare (nessun errore, però). Ho avuto risultati contrastanti con alcuni altri componenti. Grazie.

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

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

  didInsertElement() {
    this._super(...arguments);
    console.log("Welcome to the about page!");
  }

});

</script>
1 Mi Piace
139

Ciao :wave: about-page è ora in .gjs il che significa anche che non è più modificabile in quel modo. Se vuoi apportare modifiche devi usare uno dei connettori disponibili in quella pagina.

Puoi controllarli facilmente con Plugin outlet locations theme component o controllare nel file <PluginOutlet>.

4 Mi Piace
142

Grazie mille. Ha senso. Ho usato un connettore invece, funziona bene.

2 Mi Piace
143

Questa guida è ancora accurata? L’ho letta tutta per provare a creare un componente tema e poi ho guardato i componenti tema di esempio e nessuno di loro utilizza le istruzioni che dovrebbero. Ad esempio, guardando il componente tema discourse-brand-header sembra essere stato rifattorizzato dall’uso di cose come api.createwidget nell’header.html all’uso di un codice completamente diverso con inizializzatori, componenti, ecc. Codice estremamente complesso. La guida parla dell’uso del metodo API con i widget, ma non è quello che usano affatto i componenti. Esiste una guida aggiornata o qualcosa da usare per i componenti?

Modifica: Presumibilmente l’API dei widget sta scomparendo, ma ci sono guide su cosa usare invece? L’intera guida qui sembra basata su codice deprecato?

3 Mi Piace
144

È vero. La guida dovrebbe essere aggiornata. Tuttavia, alcune parti sono ancora molto pertinenti, come la struttura dei file, ecc.

2 Mi Piace
145

Sì, sembra che SCSS sia rilevante, ma per il resto, sembra che tutti i componenti del tema di esempio utilizzino Componenti e siano stati rifattorizzati in una codebase completamente diversa da quella insegnata qui. Ho esaminato tutti i componenti a cui fanno riferimento nella sezione Plugin API e ognuno di essi è stato rifattorizzato in un modo totalmente diverso da quello insegnato qui nella guida. I widget non vengono più utilizzati affatto. Sono tutti Componenti. Esiste una guida su come utilizzare correttamente i nuovi Componenti dato che i widget stanno scomparendo?

2 Mi Piace
146

Mi sono imbattuto in questo post, ad esempio, proprio ora: Upcoming Header Changes - Preparing Themes and Plugins - quindi hanno ristrutturato tutto da widget legacy a componenti Glimmer? Ma questo tutorial è tutto basato su widget legacy. Cosa sono esattamente i componenti Glimmer e ci sono delle guide? Mi sento fortunato ad averlo notato presto, prima di iniziare a sviluppare con widget legacy. Forse aggiungere una nota in questa guida che i widget sono legacy e non dovrebbero più essere utilizzati?

2 Mi Piace
147

Ok, vedo che Glimmer sono nuovi componenti Ember. Ma ho dato un’occhiata al codice del TOC di Discourse e oh mio… ciò che prima aveva circa 10 righe di codice ora ne ha centinaia sparse in molti file con classi complesse, decoratori ecc. Immagino che Ember abbia avuto un momento alla React e abbia deciso di rendere di nuovo le cose davvero complicate. Sembra che i componenti del tema non siano più facili, con una semplice API widget, ma richiedano una codifica estesa…

2 Mi Piace
148

@ddsgad sì, hai ragione, la maggior parte di questa guida è estremamente obsoleta. Ho lavorato di recente a miglioramenti generali della documentazione e spero di aggiornare/sostituire questa nelle prossime settimane.

Come hai menzionato, esempi reali come DiscoTOC possono essere un buon riferimento. E poi ecco alcune guide specifiche che sono più aggiornate:

Per informazioni generali su Ember e i suoi componenti, consiglio di consultare le guide di Ember.

6 Mi Piace
149

Grazie per quei link. Molto utile. Attualmente, personalizziamo fondamentalmente le cose in un argomento di discorso (primo post) per creare design migliori, quindi siamo stati in grado di fare praticamente tutto con JavaScript (querySelectorAll ecc.) e SCSS semplici, quindi immagino che continueremo così per ora.

3 Mi Piace
150

Il tutorial lungo e obsoleto nell’OP è stato ora sostituito con informazioni introduttive/di orientamento più generali, incluso un link a un nuovissimo tutorial in 7 passaggi che segue schemi di sviluppo di temi molto più moderni.

4 Mi Piace
151

Ho letto tutto, mi è piaciuto! Ben spiegato e ottima introduzione!

3 Mi Piace
152

Adoro queste guide! Finalmente ho decifrato api.decorateCookedElement, grazie ancora per la documentazione utile!

4 Mi Piace