Setup Menus in Admin Panel

School.Dataninja.it

Applicazioni web: cartelle e file di progetto

Un'applicazione web è composta da tanti file, organizzarli in una struttura di cartelle ordinata fin dall'inizio dello sviluppo rende la vita più facile a noi e ad eventuali collaboratori.

Anche l’applicazione web più semplice è composta da diversi file: la pagina html principale, eventuali pagine secondarie, le librerie da cui dipende il progetto, i file .js che contengono il tuo codice javascript, quelli .css che contengono le tue regole di stile e così via.

Quando si ha a che fare con più di un file, le buone pratiche da seguire sono due:

  1. organizzare i file in cartelle e sottocartelle secondo un criterio funzionale;
  2. usare nomi comprensibili e autoesplicativi per i file e le cartelle.

La tipica struttura delle cartelle

Di base una semplice visualizzazione con d3js richiede queste risorse per funzionare:

  • una pagina html principale: index.html
  • un file per le regole di stile: css/main.css
  • un file per il codice javascript: js/main.js
  • i file delle librerie usate: lib/[nome libreria]/[file della libreria]
  • eventuali immagini statiche: images/[file delle immagini]
  • eventuali font per i testi: fonts/[file dei font]
  • eventuali file con i dati: data/[file di dati]

Ti suggerisco quindi di organizzare il tuo progetto in una struttura dei file di questo tipo:

  • project/
    • index.html
    • package.json
    • README
    • LICENSE
    • css/
      • main.css
    • js/
      • main.js
    • lib/
      • d3
        • d3.min.js
    • images/
      • favicon.ico
    • fonts/
    • data/

Naturalmente se non devi usare molte librerie è inutile suddividere i file in sottocartelle di lib/, così come si può non usare una cartella fonts/ se non usi font personalizzati. Quando possibile, per le librerie ti suggerisco di usare sempre la versione minificata del codice (normalmente indicata da min nel nome, come per esempio d3.min.js) per minimizzare il peso complessivo dell’applicazione.

Se il codice da inserire nella tua applicazione è pesante, tra librerie e dipendenze esterne, ci sono molti modi per rendere più efficiente il caricamento nel browser dell’utente (ma anche nel tuo durante la fase di sviluppo). Una libreria molto utile in tal senso è Headjs, “the only script in your HEAD” (l’unico script nella tua testa). In produzione, in ogni caso, la soluzioni migliore è concatenare tutte le librerie in un singolo file minificato, operazione automatizzabile con strumenti più avanzati come Grunt, con cui il file package.json diventa necessario. 

Informazioni, istruzioni, licenze

I file README e LICENSE sono importanti soprattutto se hai poi intenzione di rilasciare il codice dell’applicazione, per esempio pubblicandolo su Github o servizi simili. E’ comunque buona prassi prevederli sempre.

Il file README

Nel file README puoi scrivere il nome dell’applicazione, la versione corrente, una breve descrizione, eventualmente un semplice manuale d’uso. Puoi scrivere un testo semplice, ma è utile usare una sintassi particolare, ma molto intuitiva e semplice da imparare: il Markdown (in tal caso magari chiama il file README.md, con l’estensione). Ecco un esempio.

Il file LICENSE

Nel file LICENSE invece puoi indicare il tuo nome come autore dell’applicazione e specificare le condizioni di uso e riuso del codice. Non bisogna essere un esperto giurista per scrivere un file di licenza, se si rimane nell’ambito open-source la scelta di base migliore è copiare e incollare la MIT License, con cui si specifica il titolare del copyright, si permette a chiunque un riuso senza restrizioni purché l’attribuzione all’autore originale sia mantenuta e ci si scarica della responsabilità in caso di eventuali danni intercorsi a causa dell’uso dell’applicazione.

Per approfondire il vasto tema delle licenze software, open o closed che siano, ti consiglio il sito tl;dr Legal, che spiega in termini semplici e in maniera schematica ogni licenza, svolgendo in linguaggio normale il legalese tipico di questi documenti.

I metadati dell’applicazione

Oltre al codice, anche un’applicazione può (e dovrebbe, aggiungo) prevedere la presenza di metadati che la descrivano. A questo serve il file package.json, un semplice file di testo in formato JSON (JavaScript Object Notation) il cui schema è stato sviluppato nell’ambito del progetto Node Package Manager (uno strumento che approfondiremo in un’unità successiva).

Il file package.json

La documentazione ufficiale descrive questo file con dovizia di particolari, ti elenco qui per comodità le parti più utili per la tua applicazione. Intanto si tratta di un file JSON, per cui si apre con una parentesi graffa aperta “{” e si chiude con una parentesi graffa chiusa “}”. In mezzo, una per ogni riga, una coppia chiave:valore, separati dai due punti “:”. Ecco le principali chiavi su cui ti consiglio di soffermarti:

  • name – il nome dell’applicazione, una stringa di caratteri tra virgolette;
  • version -la versione dell’applicazione, secondo lo standard del versionamento semantico, una stringa di caratteri tra virgolette;
  • description -una descrizione compatta dell’applicazione, una stringa di caratteri tra virgolette;
  • keywords – una serie di tag (stringhe di caratteri tra virgolette) in un array, ovvero tra parentesi quadre;
  • homepage – l’url a un’eventuale pagina pubblica, una stringa di caratteri tra virgolette;
  • license – la licenza scelta come la “MIT”, una stringa di caratteri tra virgolette;
  • author – l’autore dell’applicazione (tu!) scritto con il formato “nome cognome <email> (url)”, una stringa di caratteri tra virgolette;
  • contributors – una lista di eventuali contributori nello stesso formato dell’autore (stringhe di caratteri tra virgolette) in un array, ovvero tra parentesi quadre.

Questo lo schema, ecco un esempio.

C’è molto altro, pensato anche per scopi di cui non ci occuperemo in questo corso. Il concetto di fondo però è semplice: descrivere in maniera chiara e condivisa il proprio lavoro e farlo in un formato leggibile e gestibile anche da altre applicazioni (pensa per esempio a un motore di ricerca), non solo da altri esseri umani.

Ne vedrai subito un’applicazione concreta nella prossima unità, quando scoprirai come gestire efficacemente le librerie da cui la tua applicazione dipende.

Letture: 487