Guida di riferimento rapido per sviluppatori di temi

[Discourse]

Man mano che i temi diventano più potenti, ci sono più aspetti da ricordare sul loro funzionamento. Abbiamo un’ampia documentazione dettagliata sotto #theme-guides, ma se hai solo bisogno di un promemoria, questa guida potrebbe esserti utile.

Risorse Generali

Guida per principianti
Guida per designer
Guida per sviluppatori
Theme Creator
Theme CLI
Directory dei temi
Directory dei componenti
Modificatori dei temi
Impostazioni del sito personalizzabili

Struttura di File/Cartelle maggiori informazioni

about.json
settings.yml
common/, desktop/, mobile/
  {common|desktop|mobile}.scss
  head_tag.html
  header.html
  after_header.html
  body_tag.html
  footer.html
  embedded.scss (solo common)
locales/
  en.yml
  ...
assets/
  (file con nomi arbitrari, riferiti in about.json)
stylesheets/
  (file con nomi arbitrari, possono essere importati l'uno dall'altro e da common/desktop/mobile.scss)
javascripts/
  (file con nomi arbitrari. Supporta .js, .gjs e .hbs)

about.json informazioni sulla struttura, metadati disponibili

{
  "name": "My Theme",
  "component": false,
  "license_url": null,
  "about_url": null,
  "authors": null,
  "theme_version": null,
  "minimum_discourse_version": null,
  "maximum_discourse_version": null,
  "assets": {
    "variable-name": "assets/my-asset.jpg"
  },
  "color_schemes": {
    "My Color Scheme": {
      "primary": "222222"
    }
  }
}

SCSS

Variabili CSS disponibili

Javascript maggiori informazioni

// {theme}/javascripts/api-initializers/init-theme.gjs
import { apiInitializer } from "discourse/lib/api";

export default apiInitializer((api) => {
  // Il tuo codice qui
});

API Plugin JS

Javascript multi-file

Impostazioni maggiori informazioni

settings.yml:

fruit:
  default: apples|oranges
  type: list
  description: # Metodo vecchio. È meglio definire questi nei file delle lingue (vedi sotto)
    en: Descrizione in inglese
    fr: Descrizione in francese

Accesso da JavaScript:

console.log(settings.fruit);

Accesso da template gjs:

<template>{{settings.fruit}}</template>

Accesso da scss:

html {
  font-size: #{$global-font-size}px;
  background: $site-background;
}

Impostazioni del sito personalizzabili maggiori informazioni

about.json:

"theme_site_settings": {
  "enable_welcome_banner": false
}

Accesso da JavaScript:

@service siteSettings;

this.siteSettings.enable_welcome_banner;

Accesso da template gjs:

<template>{{this.siteSettings.enable_welcome_banner}}</template>

Traduzioni maggiori informazioni

locales/en.yml

en:
  my_translation_key: "Adoro i temi"
  theme_metadata: # Questi sono usati nel pannello di amministrazione. Non sono resi disponibili ai tuoi file js/hbs
    description: Questo tema ti permette di fare cose incredibili sul tuo Discourse
    settings:
      fruit: Una descrizione dell'impostazione whitelisted_fruits

Accesso da JavaScript:

import { i18n } from "discourse-i18n";
i18n(themePrefix("my_translation_key"));

Accesso da template gjs:

import { i18n } from "discourse-i18n";

<template>
  {{i18n (themePrefix "my_translation_key")}}
  <DButton @label={{theme-prefix "my_translation_key"}} />
</template>

---

Questo documento è sotto controllo versione - suggerisci modifiche su github.