Guida rapida per sviluppatori di temi

Man mano che i temi diventano più potenti, ci sono più cose da ricordare sul loro funzionamento. Abbiamo molta documentazione dettagliata sotto #howto / #themes, ma se hai solo bisogno di qualcosa per rinfrescarti la memoria, questa guida può essere d’aiuto.

Risorse Generali

Guida per principianti
Guida per designer
Guida per sviluppatori
Theme Creator
Theme CLI
Directory dei Temi
Directory dei Componenti
Theme Modifiers
Impostazioni del sito modificabili tramite tema

Struttura File/Cartelle leggi di più

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 denominati arbitrariamente, referenziati in about.json)
stylesheets/
  (file denominati arbitrariamente, possono essere importati l'uno dall'altro, e common/desktop/mobile.scss)
javascripts/
  (file denominati arbitrariamente. Supporta .js .hbs e .raw.hbs)

about.json info 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 leggi di più

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

export default apiInitializer((api) => {
  // Your code here
});

JS Plugin API

Javascript Multi-file

Impostazioni leggi di più

settings.yml:

fruit:
  default: apples|oranges
  type: list
  description: # Metodo vecchio. È meglio definirli nei file di locale (vedi sotto)
    en: English Description
    fr: Description Française

Accesso da JavaScript:

console.log(settings.fruit);

Accesso dai template gjs:

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

Accesso da scss:

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

Impostazioni del sito modificabili tramite tema leggi di più

about.json:

"theme_site_settings": {
  "enable_welcome_banner": false
}

Accesso da JavaScript:

@service siteSettings;

this.siteSettings.enable_welcome_banner;

Accesso dai template gjs:

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

Traduzioni leggi di più

locales/en.yml

en:
  my_translation_key: "I love themes"
  theme_metadata: # Questi sono usati nel pannello admin. 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 fruit whitelisted

Accesso da JavaScript:

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

Accesso dai template gjs:

import { i18n } from "discourse-i18n";

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

Questo documento è controllato tramite versione - suggerisci modifiche su github.

This is super useful.

Could I also suggest that a useful reference to add is the list of available color transformations:

I must be missing something here, I’m trying to use I18n.t(themePrefix("my_translation_key")) but the Firefox console reports that themePrefix is undefined.
How can I invoke that function from an api function?

Il link non sembra più valido.

Hai ragione. Dovrebbe essere ora:

https://github.com/discourse/discourse/blob/main/app/assets/javascripts/discourse/app/lib/plugin-api.js

Grazie @th21 e @Arkshine - ho aggiornato il link

Il link all’API dei plugin è cambiato di nuovo:

https://github.com/discourse/discourse/blob/main/app/assets/javascripts/discourse/app/lib/plugin-api.gjs

Grazie! Aggiornato

Questi due link non sembrano più funzionare.

Grazie per l’avviso! È tutto risolto ora.