This Streamlit app allows users to manage and join board game reservations. Users, once logged in, can create new table propositions specifying game name, duration and number of allowed players; there is also a dedicated page to view all the available tables and join them. The view page supports multiple view modes: list, timeline and table and integrate above mentioned user settings with BGG game information like image, category and mechanics. The system is also connected to a Telegram bot that can send notification to a given community when determined events occur (for example table creation)
MATCH.Table.System.mp4
L'applicazione è live su https://match-table-system.streamlit.app/ utilizzando https://streamlit.io/cloud per un hosting gratuito.
In caso si voglia invece eseguire l'applicazione in locale è necessario seguire i passi sotto indicati:
- Installare Python
- con Anaconda
- tramite sito ufficiale
- Clone del repository
git clone https://github.com/informatica92/MATCH-table-system.git
- Creazione e attivazione di un virtualenv
python -m venv venv
source venv/bin/activate # On Windows, use `venv\Scripts\activate`
- Installazione delle dipendenza
pip install -r requirements.txt
- Creazione di un file
secrets.tomlcon le seguenti variabili d'ambiente (oppure valorizza i secrets durante il deploy su Streamlit Cloud):
| Section | Variabile d'ambiente | Descrizione | Default | Obbligatorio |
|---|---|---|---|---|
| # POSTGRESQL DATABASE | --- | --- | --- | --- |
| DB_HOST | Hostname del database | localhost | No | |
| DB_NAME | Nome del database | Sì | ||
| DB_USER | Username del database | Sì | ||
| DB_PASSWORD | Password del database | Sì | ||
| DB_PORT | Porta del database | 5432 | No | |
| DB_SCHEMA | Schema del database (pre esistente) | public | No | |
| # TELEGRAM | --- | --- | --- | --- |
| TELEGRAM_CHAT_ID | Chat ID di Telegram a cui inviare messaggi | No | ||
| TELEGRAM_BOT_TOKEN | Token del bot di Telegram, se mancante, non viene effettuato alcun invio | No | ||
| TELEGRAM_CHAT_ID_PROPOSITION_DEFAULT | Chat ID di Telegram a cui inviare messaggi nel caso delle proposition nella location di default | TELEGRAM_CHAT_ID | No | |
| TELEGRAM_CHAT_ID_PROPOSITION_ROW | Chat ID di Telegram a cui inviare messaggi nel caso delle proposition nelle location custom (system e user ma non default) | TELEGRAM_CHAT_ID | No | |
| TELEGRAM_CHAT_ID_TOURNAMENT | Chat ID di Telegram a cui inviare messaggi nel caso di Tornei | TELEGRAM_CHAT_ID | No | |
| TELEGRAM_CHAT_ID_DEMO | Chat ID di Telegram a cui inviare messaggi nel caso di Demo | TELEGRAM_CHAT_ID | No | |
| # MAP | --- | --- | --- | --- |
| GMAP_MAP_URL | URL della mappa di Google Maps, se mancante non viene mostrata alcuna mappa | No | ||
| # GENERAL SETTINGS | --- | --- | --- | --- |
| TITLE | Titolo dell'applicazione | Board Game Proposals | No | |
| REST_OF_THE_WORLD_PAGE_NAME | Nome della pagina mostrato nella sidebar e in alcuni commenti. NB: il path rimane sempre "/restofthewrold" | Rest of the World | No | |
| DURATION_MINUTES_STEP | Durante la creazione o la modifica di un tavolo, quale sia lo step in termini di minuti che è ammesso per la definizione della DURATA | 30 (mins) | No | |
| LOGO | URL del logo dell'applicazione | Sì | ||
| LOGO_LARGE | URL del logo grande dell'applicazione, se mancante viene usato come logo della sidebar il logo in LOGO | No | ||
| DEFAULT_DATE | Data predefinita per la creazione di un tavolo nel formato YYYY-MM-DD, se mancante o nel passato, viene usata la data odierna |
data odierna | No | |
| BASE_URL | Il base URL in cui è running l'applicazione (per i link telegram e altro) | http://localhost:8501 | No | |
| DONATION_USER | Lo username della pagina Ko-fi da mostrare per donazioni/supporto | informatica92 | No | |
| CAN_ADMIN_CREATE_TOURNAMENT | Se gli ADMIN possono creare proposte di tipo TOURNAMENT (attiva anche la pagina corrispondente) | false | No | |
| CAN_ADMIN_CREATE_DEMO | Se gli ADMIN possono creare proposte di tipo DEMO (attiva anche la pagina corrispondente) | false | No | |
| # DEFAULT LOCATION | --- | --- | --- | --- |
| DEFAULT_LOCATION_ALIAS | L'alias (nome breve e parlante) della location principale del sistema (es "MATCH") | |||
| DEFAULT_LOCATION_COUNTRY | Il Paese in cui è presente la location principale del sistema (es: "Italia") | |||
| DEFAULT_LOCATION_CITY | La città in cui è presente la location principale del sistema (es: "Bari") | |||
| DEFAULT_LOCATION_STREEN_NAME | L'indirizzo in cui è presente la location principale del sistema (es: "via XX Settembre") | |||
| DEFAULT_LOCATION_STREEN_NUMBER | Il numero civico in cui è presente la location principale del sistema (es: "18") | |||
| CAN_USERS_SET_LOCATION | Se gli utenti possono scegliere una location diversa da quella principale in fase di Creazione ("true"/"false") | false | No | |
| [auth] | --- | --- | --- | --- |
| redirect_uri | URI di reindirizzamento per l'autenticazione, può essere: - http://localhost:8501/oauth2callback - https:// dominio deploy/oauth2callback |
Sì | ||
| cookie_secret | Nome del cookie in cui inserire il token di autenticazione | Sì | ||
| [auth.auth0] | --- | --- | --- | --- |
| client_id | Client ID di Auth0 | Sì | ||
| client_secret | Client Secret di Auth0 | Sì | ||
| server_metadata_url | URL del server metadata di Auth0, nella forma https://dominio auth0.com/.well-known/openid-configuration |
Sì |
NB: Alcune "Section" iniziando con # sono commenti e non vengono considerate, servo solo a scopo di organizzazione del file.
Le "Section" che invece hanno forma [nome] sono obbligatorie e devono essere rispettate.
- Eseguire
streamlit run board_game_manager.py
In questo modo sarà possibile specificare una durata più granulare.
Cliccando sul "+/-" ci sarà un incremento in minuti determinato dalla ENV VAR DURATION_MINUTES_STEP che di default vale 30 (quindi 30min)
🎉 Novità: Notifiche Telegram anche per le modifiche dei tavoli (oltre a quelle già presenti per la creazione)
- con un testa BARRATO il vecchio valore per numero di giocatori, ora e data
- con una dicitura NEW per i campi note ed espansioni (e in questo caso si vedrà solo il valore aggiornato)
Ora è possibile accedere, tramite apposito bottone presente sempre nella sidebar e in altre location chiave, ad una pagina di Ko-fi nella quale è possibile effettuare donazioni spontanee e volontaree per supportare lo sviluppo e il mantenimento del server APP e il suo DB.
Minimo 1€ (che neanche un caffè, dai)
Ora è disponibile un check in alto che permette di avere una panoramica su eventuali sovrapposizioni dei vari tavoli a cui ci si è uniti.
Il sistema riconosce tre casistiche:
- No Overlaps: i tavoli a cui ci si è uniti non sono sovrapposti
- Important: due tavoli a cui ci si è uniti hanno la medesima data di inizio
- Warning: due tavoli a cui ci si è uniti hanno una sovrapposizione parziale
Important e Warning sono aggregati in termini di numero se il popover è compresso e l'icona è quella della gravità più alta presente (punto esclamativo se c'è almeno un errore, warning se non ci sono errori ma almeno un warning).
Espandendo il popover si ha poi il detagli delle coppie di tavoli e si può navigare direttamente verso uno di questi per rimuovers, spostare il tavolo...
NB: Il "Go to Table" è disponibile solo nella modalità di visualizzazione "LISTA"
E' disponibile ora il concetto di "Proposition Type". Un tavolo può essere dei seguenti tipi:
- PROPOSITION: tutti i tavoli creati dagli utenti, che siano nella location di sistema, user location o system location
- TOURNAMENT: se abilitato tramite la variabile d'ambiente CAN_ADMIN_CREATE_TOURNAMENT, gli admin (e solo gli admin) potranno creare tavoli di tipo TOURNAMENT
- DEMO: se abilitato tramite la variabile d'ambiente CAN_ADMIN_CREATE_DEMO, gli admin (e solo gli admin) potranno creare tavoli di tipo DEMO
TOURNAMENT e DEMO hanno poi, se abilitati, delle pagine dedicate.
Tutti gli utenti potranno comunque unirsi a questi tavoli
Inoltre ora è anche possibile differenziare le destinazioni delle notifiche Telegram sulla base della tipologia di proposta e della location:
- TELEGRAM_CHAT_ID_PROPOSITION_DEFAULT: dove inviare le proposte base nella location di default (se assente si userà TELEGRAM_CHAT_ID)
- TELEGRAM_CHAT_ID_PROPOSITION_ROW: dove inviare le proposte base nelle location NON di default (se assente si userà TELEGRAM_CHAT_ID)
- TELEGRAM_CHAT_ID_TOURNAMENT: dove inviare le proposte TOURNAMENT (se assente si userà TELEGRAM_CHAT_ID)
- TELEGRAM_CHAT_ID_DEMO: dove inviare le proposte DEMO (se assente si userà TELEGRAM_CHAT_ID)
Tutte le variabili d'ambiente che riportano una destinazione Telegram possono avere le seguenti forme:
- personal - "123456789"
- gruppo - "-100123456789" -> "-100123456789_1" -> General
- gruppo + topic - "-100123456789_4"
Con lo scopo di incrementare la leggibilità e allo stesso tempo avere una maggiore compattezza della vista (non influenzata dalla lunghezza di Espansioni e Note), l'interfaccia è stata aggiornata con degli Expander che di default visualizzano una preview dell'informazione ma, se espansi, permettono di accedere ad ulteriori dettagli.
Ad esempio:
| Campo | Visualizzazione Compatta | Visualizzazione Espansa |
|---|---|---|
| Proposed By | Username | Telegram e BGG username con link |
| Expansions | Numero di Espansioni | La lista di espansioni |
| Notes | Primi caratteri | L'intera nota |
E' ora possibile aggiungere espansioni ai giochi, in modo da poter specificare quali espansioni saranno utilizzate durante la partita.
Le espansioni selezionate in fase di "Create" vengono poi mostrate nella pagine "View & Join"
E' anche possibile modificare le espansioni in seguito utilizzando il tasto "Edit" disponibile sotto ogni proposta.
Quelle che precedentemente erano tabs (destra nell'immagine) ora sono state trasformate in pagine (sinistra nell'immagine), per una navigazione più fluida e intuitiva
Seleziona una pagina dal menu a sinistra, all'interno della sidebar, per accedere alle funzionalità desiderate
Al primo accesso verrà creato un utente che non avrà alcun username. Per impostare un username (e quindi abilitare la creazione e l'unione ai tavoli) è necessario recarsi alla page "User" (vedi "Nuova pagina "User"") ed inserire l'username.
ATTENZIONE: L'username è univoco! Non vi sarà quindi possibile selezionare un nome utente già in uso da un altro user.
Il provider principale di autenticazione è Auth0 ma sono offerti anche i seguenti social providers:
E' ora possibile accedere ad una pagina interamente dedicata all'utente in cui è possibile impostare campi come:
- Nome
- Cognome
- Username
- Telegram username
- BGG username
ATTENZIONE: L'username è univoco! Non vi sarà quindi possibile selezionare un nome utente già in uso da un altro user.
ATTENZIONE: L'username è inoltre necessario per abilitare creazione e unione ai tavoli.
A parte le location di sistema, ogni utente può ora aggiungere una o più location in cui è disponibile a giocare.
Le Location di Sistema (Admin Locations) sono gestibili solo dagli utenti Admin. Si tratta di una impostazione a livello DB.
In fase di creazione di un tavolo, nella pagina "Create", è possibile selezionare la location nella quale si terrà il tavolo:
- in occasione degli eventi MATCH, usare quindi la location (di sistema) "MATCH"
- se lo si desidera, sarà quindi possibile aprire tavoli anche durante tutto l'anno con le location delle varie altre associazioni (es "Masseria Andriani", "Biblioteca di Putignano", "Officina dei Saperi"...)
ATTENZIONE: le location di sistema appariranno sempre a tutti gli utenti e sono quindi trasversali, le location utente, invece, possono essere usate come location solo dall'utente che l'ha creata.
Valorizzando le variabili d'ambiente
- TELEGRAM_CHAT_ID
- TELEGRAM_BOT_TOKEN
Una notifica sul rispettivo canale (chat id/channel id) verrà inviata automaticamente:
- al momento della creazione di un tavolo
Delete ha ora una finestra di conferma e permette anche l'eliminazione di tavoli con 1+ giocatori
Leave/Delete/Edit possibili solo per sè stessi e per i propri tavoli:
- Leave è quindi abilitata solo per sè stessi e per i giocatori ai propri tavoli
- Delete/Edit è quindi possibile solo per i propri tavoli
La GOD MODE permette, in caso di opportuna configurazione dell'utenta da parte degli amministratori, di superare il vincolo per cui Leave/Delete/Edit è possibile solo per sè stessi e per i propri tavoli.
Utile per testing e manutenzione
E' stata aggiunta una visualizzazione a tabella oltre a quella standard a lista e a timeline.
Ancora una volta, selezionando una riga, in basso si aprirà la scheda del gioco e potrete fare Join/Leave/Delete
E' ora presente un flag che permette, di default, di aggiungere il proponente al tavolo da lui creato.
Se deselezionata, il tavolo verrà creato comunque ma senza aggiungere l'utente allo stesso.
Per semplificare la parte di crezione e velocizzarla, l'orario è stato sostituito con dei Time Slot (mattina, pomeriggio, sera, notte).
In fase di Edit è comunque ancora possibile selezionare l'orario desiderato con la consueta precisione di mezz'ora (08:30, 09:00, 09:30...)
I messaggi di successo e conseguente aggiornamento sono stati sostituiti con delle notifiche per maggiore reattività della pagina.
Disponibili per:
- Creazione (ora il suo messaggio si successo in basso è inoltre permanente per evitare creazioni doppie)
- Join
- Leave
- Delete
- Se non è visibile, espandere la sidebar sulla sinistra,
- inserire un username nella casella di testo apposita e premere INVIO.
- L'applicazione ora vi identificherà con quell'username e vi abiliterà le opzioni di:
- creazione di una proposta (o tavolo)
- unione ad una proposta (o tavolo)
- Passare alla tab dedicata (la seconda) e inserire il titolo del gioco nella prima casella di testo. Premere INVIO.
- La selezione sottostante acquisirà ora i titoli di BGG che corrispondono al titolo inserito sopra (così come la ricerca su BGG)
- Scegliete ora un titolo da quella selezione per automatizzare la ricerca dell'immagine, della descrizione, delle meccaniche e delle categorie
- Inserire:
- il numero di giocatori,
- la durata prevista
- data e ora
- note
- Premere "Create Proposition" per salvare
- Il tavolo proposto sarà ora visibile nella tab apposita (la prima)
- Accedere alla tab apposita (la prima)
- Scorrere tra le proposte (in ordine di creazione)
- Accedere alla tab apposita (la prima)
- Individuare una delle proposte
- Cliccare su "Join Table X"
NB:
- Puoi accedere solo una volta ad ogni tavolo con uno specifico username
- Se invece del bottone viene mostrato un messaggio "Set a username to join a table", espandere la sidebar e impostare l'username come indicato sopra
- Accedere alla tab apposita (la prima)
- Individuare una delle proposte
- Cliccare su "Leave" in corrispndenza dell'utente che si desidera rimuovere
- Accedere alla tab apposita (la prima)
- Individuare una delle proposte
- Cliccare su "Delete proposition"
NB:
- Per ragioni di sicurezza, possono essere rimossi solo i tavoli vuoti
- Elimina tutti i giocatori prima di rimuovere il tavolo se ve ne è qualcuno
Valorizzando le variabili d'ambiente
- DEFAULT_DATE
il selettore della data nella tab di creazione verrà inizializzato a quel valore.
ATTENZIONE: il formato deve essere YYYY-MM-DD, es: 2024-09-29
Usando l'apposito selettore nella sidebar, si può passare da una visualizzazione come lista ad una a timeline.
Utile per apprezzare la sequenzialità dei vari tavoli
Usando il toggle, la vista (che sia lista o timeline) viene filtrata per i SOLI TAVOLI a cui ci si è uniti (joined)
NB: richiede l'inserimento dell'username, altrimenti il toggle è disattivato
Usando il tasto "Edit" disponibile sotto ogni gioco, è possibile aprire una finestra per modificare alcune voci del gioco selezionato:
- Numero massimo di giocatori (Max Players)
- Durata (in minuti) (Duration)
- Data (Date)
- Ora (Time)
- Note (Notes)
Clicca poi "Update" per applicare le modifiche
NB: Non è possibile modificare il nome del tavolo e il BGG game id