Aquesta pàgina explica, pas a pas, com crear un tema nou per al JOEL: un joc de colors per a tota la web que els usuaris poden aconseguir al gacha i triar al seu perfil.

Crear un tema requereix accés al servidor (per editar i compilar els estils) i ser administrador (per crear l'achievement). Si ets alumne i tens una idea de tema, pots preparar els colors i passar-los al professorat.

Com funciona un tema

Un tema són tres peces que han de tenir exactament el mateix nom, per exemple theme-mar:

1. Un bloc de colors al fitxer d'estils resources/base.scss, amb la forma :root[data-theme=theme-mar] { ... }. Dins hi ha unes 30 variables de color (--global-text, --widget_black...), i cada part de la web agafa el seu color d'una d'aquestes variables.
2. Un achievement de categoria tema que es diu theme-mar. És el que surt al gacha.
3. La tria de l'usuari: quan algú que té l'achievement el tria a Editar perfil → Tema web, el seu perfil guarda theme-mar i cada pàgina posa data-theme="theme-mar" a l'etiqueta <html>. A partir d'aquí, el navegador fa servir els colors del bloc del pas 1 en lloc dels de per defecte.

Si una variable no apareix al bloc del tema, s'hi fa servir la del tema per defecte (el blau i blanc de sempre). Si el nom no coincideix exactament entre el CSS i l'achievement, el tema no farà res.

Pas 1: triar el nom

Ha de començar per theme- i només pot tenir lletres sense accents, números i guions: theme-mar, theme-retro80. Comprova que no existeixi ja: els temes actuals són theme-dark, theme-candy, theme-wmt, theme-atomdark, theme-DTpurple, theme-BUBIMan, theme-olddark i theme-oldcandy.

Pas 2: escriure els colors

Obre resources/base.scss, copia sencer el bloc d'un tema que s'assembli al que vols (un de fosc com theme-dark o un de clar com theme-candy), enganxa'l a continuació, canvia-li el nom i ves canviant els colors.

Aquestes són les variables i on es fan servir:

Textos

• --text-black: el text normal de tota la pàgina (cos, taules, enllaços d'usuari...). És la variable més important.
• --global-text: títols de pàgina i de seccions (h1, h2...) i text dels casos de prova.
• --text-white: text sobre fons de color: botons, capçaleres de taula, avisos i barra d'informació dels concursos.
• --global-gray: text del peu de pàgina.

Enllaços

• --global-link, --global-link-hover, --global-link-active: color dels enllaços, en passar-hi el ratolí i en clicar-los.
• --title_blue, --title_hover: títols de les entrades del blog i noms de concursos a la portada.

Fons

• --background-white: fons del contingut central de la pàgina, de les pestanyes actives i dels comentaris.
• --background_light_gray: fons de la pàgina (fora del contingut), dels formularis i dels blocs de codi.
• --background_gray: capçaleres de taules ordenables, peu de pàgina i fila de la llista de problemes on hi ha el ratolí.
• --background_table_pyjama: les files parells de les taules ratllades.
• --background_input: caselles de text i àrees de text.
• --background_black, --background_dark_gray: capçalera de les pàgines i barra d'informació dels concursos.

Barra de menú superior

• --widget_black: fons de la barra de menú i dels seus desplegables.
• --nav-text: text del menú, dels desplegables i del menú d'usuari ("Hola, ..."). Si no el poses, fa servir --text-white.
• --nav-active-bg, --nav-active-text: fons i text de la secció on ets ara.
• --text-nav, --nav-hover-bg: text i fons d'un element del menú quan hi passes el ratolí.
• --highlight_blue: la ratlla de color dels desplegables i alguns detalls (problema del dia, enllaços d'usuari).

Botons i vores

• --button_blue: fons dels botons.
• --border_gray, --border_black, --border_dark_gray: vores de caixes, línies separadores i vores de taules.
• --announcement_red: fons dels avisos importants.

Hi ha algunes variables més al bloc (--global-white, --global-black, --button_grad) que avui gairebé no es fan servir. Deixa-les amb un valor raonable.

Un exemple mínim:

:root[data-theme=theme-mar] {
    --text-black: #e6f1ff;
    --global-text: #ffffff;
    --background-white: #0b2545;
    --background_light_gray: #13315c;
    --widget_black: #134074;
    --nav-text: #ffffff;
    --global-link: #8ecae6;
    /* ...i la resta de variables */
}

Pas 3: comprovar que es llegeix

És l'error més habitual. Cada text ha de tenir prou contrast amb el seu fons: com a mínim 4,5 a 1. Ho pots comprovar amb qualsevol comprovador de contrast en línia (per exemple, el de WebAIM: posa-hi el color del text i el del fons). Les parelles que cal comprovar sempre:

• --text-black sobre --background-white i sobre --background_light_gray (text normal i codi).
• --global-text sobre --background-white (títols).
• --nav-text sobre --widget_black (menú i desplegables).
• --nav-active-text sobre --nav-active-bg, i --text-nav sobre --nav-hover-bg (menú).
• --text-white sobre --button_blue (botons).
• --global-link sobre --background-white (enllaços).

Errors que ja han passat en temes existents:

• Oblidar el #: --global-white: a2d2ff; no és un color vàlid i es perd. Ha de ser #a2d2ff.
• Colors inventats: #orange no existeix. O orange, o un codi com #ffa500.
• Text fosc sobre fons fosc al menú: si el fons del menú (--widget_black) és fosc, el text del menú (--nav-text) ha de ser clar, encara que --text-white sigui fosc perquè els teus botons són clars.

Pas 4: compilar i publicar els estils

Al servidor, des de la carpeta del JOEL:

./make_style.sh
cp resources/style.css /tmp/static/style.css

make_style.sh converteix els fitxers .scss en els .css que fa servir la web. La còpia a /tmp/static (la carpeta d'estàtics que serveix nginx) el publica. No cal reiniciar res: la web detecta el fitxer nou en uns segons. Si has canviat també altres fitxers d'estil, copia'ls igual (o fes servir python manage.py collectstatic).

Abans de compilar, comprova que el resultat només conté els teus canvis: si algú altre ha deixat canvis d'estils a mig fer, també es publicarien.

Pas 5: provar-lo sense tenir-lo

Un cop publicats els estils, no cal tenir l'achievement per veure com queda el tema. A qualsevol pàgina del JOEL, obre la consola del navegador (F12, pestanya Console) i escriu:

document.documentElement.dataset.theme = 'theme-mar'

La pàgina canvia als colors del tema a l'instant (només per a tu i fins que recarreguis). Repassa com a mínim: la portada, la llista de problemes, un enunciat amb codi, la pàgina d'un enviament, una taula de classificació, el menú desplegable i el menú d'usuari, els botons, un formulari i el gacha.

Pas 6: crear l'achievement

A l'administració: Achievements → Afegeix.

• Nom: exactament el nom del tema (theme-mar). És el que es veurà al desplegable del perfil.
• Categoria: tema. Només els administradors poden triar-la; els creadors d'achievements només poden fer stickers i icones.
• Qualitat: els temes que hi ha ara són llegendaris.
• Imatge: una captura de la web amb el tema posat, perquè la gent vegi què li ha tocat.
• Descripció: una frase sobre el tema.

A partir d'aquí ja pot sortir al gacha. Per provar-lo de veritat amb el teu usuari, pots donar-te l'achievement des de l'administració i triar-lo a Editar perfil → Tema web.

Resum ràpid

1. Nom: theme-algo, igual a tot arreu.
2. Bloc :root[data-theme=theme-algo] { ... } a resources/base.scss, copiant un tema existent.
3. Contrast de com a mínim 4,5 a 1 a totes les parelles de text i fons.
4. ./make_style.sh i copiar resources/style.css a /tmp/static/.
5. Prova amb document.documentElement.dataset.theme = 'theme-algo'.
6. Achievement amb el mateix nom i categoria tema.