Configurazione di Middleman

Gemfile

Ogni progetto generato con Middleman ha un Bundler Gemfile dove vengono specificate le dipendenze. Siccome lo stesso Middleman è una gem di Ruby, essa viene definita (insieme alla versione di Middleman in uso) nel Gemfile.

Tutte le altre librerie e plugins gem in uso dentro il progetto si trovano nel Gemfile.

Struttura file Middleman

data/
lib/
locales/
source/images/
source/javascripts/
source/layouts/
source/partials/
source/stylesheets/
source/templates/
config.rb

Nella cartella source sono inoltre presenti i file delle favicon, generati da https://realfavicongenerator.net/

config.rb

Il file config.rb si occupa della completa configurazione di Middleman. In particolare vengono svolte queste operazioni:

• Attivazione e configurazione di i18n per la localizzazione
• Attivazione e configurazione delle gemme middleman-dato, middleman-paginate, middleman-search_engine_sitemap, middleman-livereload, redcarpet
• Definizione dei PresentationHelpers, per la gestione delle collezioni
• Definizione degli helpers per utilizzare le collezioni nei templates
• Configurazione dei proxies per generare le pagine
• Integrazione con webpack per la gestione degli assets

Sono inoltre inclusi ulteriori helpers, definiti in questi file:

lib/image_helpers.rb lib/path_helpers.rb lib/text_helpers.rb

Partial di Middleman

I partial sono dei file ERB (embedded ruby code, in questo caso usiamo il linguaggio slim) in cui viene scritto un componente grafico (e.g. una card, header, sidebar, footer, ecc.) che può essere aggiunto in qualsiasi template o layout. In questo modo, il contenuto di un partial può essere usato più volte senza duplicare il codice, e il componente può essere modificato per l'intero sito cambiando il codice in un singolo partial.

Note:

• Il nome dei partial inizia sempre con un trattino basso.
• Un partial (per esempio il partial _file-name.html.slim) viene inserito dentro un template o layout con il codice

= partial "partials/file-name"

• E' possibile passare valori specifici per le variabili locali dentro i partial. Per esempio, se il partial _file-name.html.slim ha una variabile con nome title che riceve un valore di tipo stringa, è possibile definire la variabile in questo modo:

= partial "partials/file-name", locals: {title: "This is the title"}

Per maggiori informazioni, consultare la documentazione di Middleman sui partials.

Helper di Middleman

Gli helper sono dei metodi che possono essere usati all'interno dei slim templates per semplificare alcuni task come per esempio l'inserimento e la manipolazione di link, tags e asset. La documentazione sugli helper di Middleman ha molte informazioni utili.

È possibile definire custom helpers direttamente in config.rb nel blocco dei helper:

helpers do
  def some_method
    # ...do something here...
  end
end

oppure altrove nel progetto, per esempio nella cartella lib. In questo progetto sono stati definiti 3 moduli di helper nella cartella lib, i quali sono stati poi importati in config.rb:

# config.rb
require "lib/path_helpers"
require "lib/image_helpers"
require "lib/text_helpers"
...

helpers do
  include PathHelpers
  include ImageHelpers
  include TextHelpers
  ...

end

Gli helper sono sempre accessibili dentro le viste ma non funzionano ovunque in config.rb se chiamati fuori dal block di helper. Per questo motivo c'è dentro config.rb un module con PresentationHelper con dei metodi accessibili ovunque nel config. Spesso è stato definito un PresentationHelper e dopo un helper normale che usa il PresentationHelper e in questo modo lo fa arrivare alle viste.

Molte collezioni di contenuti da Dato sono prima organizzate (sorted) o filtrate (con sotto-selezioni di elementi) dentro il block di helpers di config.rb prima di essere passate alle viste, per esempio usando i helper visible_articles, visible_press_conferences, visible_announcements, etc.