## Lavorare sul sito

Questa guida contiene una veloce panoramica all'architettura del sito, e come
iniziare a lavorare.

Assicurati di aver [l'ambiente di sviluppo](docs/ambiente-di-sviluppo.md)
preparato sulla tua macchina, e di essere entrato nel virtualenv.

### Panoramica dell'architettura del sito

Il sito è un'applicazione in Python 3, scritta utilizzando il framework
[Flask][flask]. Per poter sopportare più facilmente i picchi di traffico a cui
è sottoposto il nostro sito, genera una cache statica di tutte le pagine che lo
consentono, istruendo nginx di servire quelle al posto di renderizzare la
pagina da zero.

Per il frontend, utiliziamo SCSS come preprocessore per gli stili, ed il
[Vanilla Framework][vanilla] di Canonical con [il nostro tema][vanilla-theme]
applicato sopra.

Questa è la struttura del repository:

* `docs/` contiene la documentazione sul sito
* `assets/` contiene gli assets del sito (stili, script ed immagini)
* `uitwww/` contiene il codice Python che fa funzionare il sito
* `uitwww/navbar.json` contiene la struttura del menu
* `uitwww/templates` contiene i template (l'HTML) del sito
* `uitwww/templates/pages` contiene le pagine statiche del sito

### Git workflow

Una cosa importante: per ogni contributo (un bug fix, una nuova feature), crea
un nuovo branch partendo da `develop`. Per ovvie ragioni non puoi pushare
direttamente in master, ma dovrai fare una `Merge Request` e aspettare che
qualcuno del team faccia una review.

Controlla quindi di essere nel master, avere il codice aggiornato, e crea il
tuo branch:

```
git checkout develop
git pull
git checkout -b il-mio-nuovo-contributo
```

E ricordati di aggiungere il tuo nome al file AUTHORS.md ;-)

### Esecuzione del sito in locale

Il sito è ora installato in locale! Per avviarlo basta dare il comando (dopo
aver attivato l'ambiente virtuale):

```
$ uitwww run data -d
```

Questo avvierà il sito in locale, in debug mode (**NON IN PRODUZIONE!** - la
flag `-d`) utilizzando `data/` come directory dove salvare i dati necessari al
funzionamento del sito (per esempio le varie cache).

### Creazione di una build

Per creare una build del sito in formato `.whl` (pacchetti di Python), basta
eseguire il seguente comando:

```
$ invoke build
```

La build si troverà in `build/packages`.

### Creazione di una nuova pagina

Per creare una nuova pagina, bisogna creare un nuovo template Jinja all'interno
della directory `uitwww/templates/pages` chiamato come l'URL della pagina. È
poi necessario riavviare l'applicazione dopo che la pagina è stata creata per
poterla vedere.

Se per esempio si vuole creare la pagina `sezione/pagina`, è necessario creare
il file `uitwww/templates/pages/sezione/pagina.html`. Questo è il contenuto di
base da cui partire:

```
{# Source code of the Ubuntu-it website
 # Copyright (C) ANNO  NOME COGNOME <EMAIL>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Affero General Public License as published
 # by the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 #
 # This program is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; witout even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU Affero General Public License for more details.
 #
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #}

{% extends "layout.html" %}

{% block title %}TITOLO PAGINA{% endblock %}

{% block content %}
    CONTENUTO HTML
{% endblock %}
```

Bisogna inserire poi al posto delle parole in maiuscolo il contenuto.

### Lavorare sugli assets

Essendo scritti in SCSS, gli assets vanno compilati dopo ogni modifica:

```
$ invoke assets
```

Per evitare di eseguire ogni volta il comando, si può passare la flag `-w` che
lo esegue ogni volta che viene rilevata una modifica:

```
$ invoke assets -w
```

[flask]: https://www.palletsproject.com/p/flask
[vanilla]: https://vanillaframework.io
[vanilla-theme]: http://code.ubuntu-it.org/ubuntu-it-web/ubuntuit-vanilla-theme
