Guides.rubyonrails.org

1 Fondamenti della linea di comando

Ci sono alcuni comandi che sono assolutamente critici per il vostro uso quotidiano di Rails. Nell’ordine di quanto probabilmente li userete sono:

• rails console
• rails server
• rake
• rails generate
• rails dbconsole
• rails new app_name

Creiamo una semplice applicazione Rails per esaminare ciascuno di questi comandi nel contesto.

1.1 rails new

La prima cosa che vogliamo fare è creare una nuova applicazione Rails eseguendo il comando rails new dopo aver installato Rails.

$ rails new commandsapp create create README.rdoc create .gitignore create Rakefile create config.ru create Gemfile create app ... create tmp/cache create tmp/pids create vendor/plugins create vendor/plugins/.gitkeep

Rails vi fornirà quella che sembra una quantità enorme di roba per un comando così piccolo! Ora avete l’intera struttura di directory di Rails con tutto il codice di cui avete bisogno per eseguire la nostra semplice applicazione proprio fuori dalla scatola.

1.2 rails server

Il comando rails server lancia un piccolo server web chiamato WEBrick che viene fornito insieme a Ruby. Lo userete ogni volta che vorrete accedere alla vostra applicazione attraverso un browser web.

Senza altro lavoro, il server Rails eseguirà la nostra nuova applicazione Rails splendente:

Con soli tre comandi abbiamo creato un server Rails in ascolto sulla porta 3000. Andate sul vostro browser e aprite http://localhost:3000, vedrete un’applicazione Rails di base in esecuzione.

Potete anche usare l’alias “s” per avviare il server: rails s.

Il server può essere eseguito su una porta diversa usando l’opzione -p. L’ambiente di sviluppo di default può essere cambiato usando -e.

$ rails server -e production -p 4000

L’opzione -b lega Rails all’ip specificato, di default è 0.0.0.0. Puoi eseguire un server come demone passando l’opzione -d.

1.3 rails generate

Il comando rails generate usa dei template per creare un sacco di cose. Eseguendo rails generate da solo si ottiene una lista di generatori disponibili:

Puoi anche usare l’alias “g” per invocare il comando generatore: rails g.

Utilizzare i generatori vi farà risparmiare una grande quantità di tempo scrivendo il codice boilerplate, codice necessario al funzionamento dell’app.

Facciamo il nostro controller con il generatore di controller. Ma quale comando dovremmo usare? Chiediamolo al generatore:

Il generatore di controller si aspetta parametri nella forma di generate controller ControllerName action1 action2. Facciamo un controller Greetings con un’azione di hello, che ci dirà qualcosa di carino.

$ rails generate controller Greetings hello create app/controllers/greetings_controller.rb route get "greetings/hello" invoke erb create app/views/greetings create app/views/greetings/hello.html.erb invoke test_unit create test/functional/greetings_controller_test.rb invoke helper create app/helpers/greetings_helper.rb invoke test_unit create test/unit/helpers/greetings_helper_test.rb invoke assets create app/assets/javascripts/greetings.js invoke css create app/assets/stylesheets/greetings.css

Cosa ha generato? Si è assicurato che ci fossero un sacco di directory nella nostra applicazione, e ha creato un file controller, un file view, un file di test funzionale, un helper per la view, un file javascript e un file stylesheet.

Guarda il controller e modificalo un po’ (in app/controllers/greetings_controller.rb):

class GreetingsController < ApplicationController def hello @message = "Hello, how are you today?" endend

Poi la vista, per visualizzare il nostro messaggio (in app/views/greetings/hello.html.erb):

<h1>A Greeting for You!</h1><p><%= @message %></p>

Accendi il tuo server usando rails server.

$ rails server=> Booting WEBrick...

L’URL sarà http://localhost:3000/saluto/hello.

Rails ha un generatore anche per i modelli di dati.

Ma invece di generare direttamente un modello (cosa che faremo dopo), impostiamo uno scaffold. Uno scaffold in Rails è un insieme completo di modello, migrazione del database per quel modello, controller per manipolarlo, viste per visualizzare e manipolare i dati, e una suite di test per ognuno di questi.

Impostiamo una semplice risorsa chiamata “HighScore” che terrà traccia del nostro punteggio più alto nei videogiochi a cui giochiamo.

Il generatore controlla che esistano le directory per i modelli, i controller, gli helper, i layout, i test funzionali e unitari, i fogli di stile, crea le viste, il controller, il modello e la migrazione del database per HighScore (creando la tabella high_scores e i campi), si occupa del percorso per la risorsa, e nuovi test per tutto.

La migrazione richiede di migrare, cioè di eseguire del codice Ruby (che vive in quel 20100209025147_create_high_scores.rb) per modificare lo schema del nostro database. Quale database? Il database sqlite3 che Rails creerà per voi quando eseguiremo il comando rake db:migrate. Parleremo più approfonditamente di Rake tra poco.

Vediamo l’interfaccia che Rails ha creato per noi.

$ rails server

Andate sul vostro browser e aprite http://localhost:3000/high_scores, ora possiamo creare nuovi punteggi alti (55.160 su Space Invaders!)

1.4 rails console

Il comando console vi permette di interagire con la vostra applicazione Rails dalla riga di comando. Sotto sotto, rails console usa IRB, quindi se l’avete mai usato, vi sentirete a casa. Questo è utile per testare idee veloci con il codice e cambiare i dati lato server senza toccare il sito web.

Puoi anche usare l’alias “c” per invocare la console: rails c.

Se vuoi provare del codice senza cambiare alcun dato, puoi farlo invocando rails console –sandbox.

$ rails console --sandboxLoading development environment in sandbox (Rails 3.1.0)Any modifications you make will be rolled back on exitirb(main):001:0>

1.5 rails dbconsole

rails dbconsole capisce quale database stai usando e ti fa entrare in qualsiasi interfaccia a riga di comando tu voglia usare con esso (e capisce anche i parametri della riga di comando da dargli!) Supporta MySQL, PostgreSQL, SQLite e SQLite3.

Puoi anche usare l’alias “db” per richiamare la dbconsole: rails db.

1.6 rails plugin

Il comando rails plugin semplifica la gestione dei plugin. I plugin possono essere installati per nome o per gli URL dei loro repository. È necessario avere Git installato se si vuole installare un plugin da un repo Git. Lo stesso vale anche per Subversion.

$ rails plugin install https://github.com/technoweenie/acts_as_paranoid.git+ ./CHANGELOG+ ./MIT-LICENSE......

1.7 rails runner

runner esegue codice Ruby nel contesto di Rails in modo non interattivo. Per esempio:

$ rails runner "Model.long_running_method"

Puoi anche usare l’alias “r” per invocare il runner: rails r.

Puoi specificare l’ambiente in cui il comando runner deve operare usando lo switch -e.

$ rails runner -e staging "Model.long_running_method"

1.8 rails destroy

Pensa a destroy come il contrario di generate. Capirà cosa ha fatto generate, e lo annullerà.

Puoi anche usare l’alias “d” per invocare il comando destroy: rails d.

2 Rake

Rake è Ruby Make, un’utilità Ruby standalone che sostituisce l’utilità Unix ‘make’, e usa un ‘Rakefile’ e i file .rake per costruire una lista di compiti. In Rails, Rake è usato per i comuni compiti di amministrazione, specialmente quelli sofisticati che si basano l’uno sull’altro.

Puoi ottenere una lista di compiti Rake disponibili per te, che spesso dipendono dalla tua directory corrente, digitando rake –tasks. Ogni task ha una descrizione, e dovrebbe aiutarvi a trovare quello che vi serve.

$ rake --tasks(in /home/foobar/commandsapp)rake db:abort_if_pending_migrations # Raises an error if there are pending migrationsrake db:charset # Retrieves the charset for the current environment's databaserake db:collation # Retrieves the collation for the current environment's databaserake db:create # Create the database defined in config/database.yml for the current Rails.env......rake tmp:pids:clear # Clears all files in tmp/pidsrake tmp:sessions:clear # Clears all files in tmp/sessionsrake tmp:sockets:clear # Clears all files in tmp/sockets

2.1 about

rake about fornisce informazioni sui numeri di versione di Ruby, RubyGems, Rails, i sottocomponenti di Rails, la cartella della vostra applicazione, il nome dell’ambiente Rails corrente, l’adattatore del database della vostra applicazione e la versione dello schema. È utile quando hai bisogno di chiedere aiuto, controllare se una patch di sicurezza potrebbe interessarti, o quando hai bisogno di alcune statistiche per un’installazione Rails esistente.

2.2 assets

Puoi precompilare gli assets in app/assets usando rake assets:precompile e rimuovere quegli assets compilati usando rake assets:clean.

2.3 db

I compiti più comuni del db: Rake sono migrate e create, e sarà utile provare tutti i task di rake per la migrazione (up, down, redo, reset). rake db:version è utile per la risoluzione dei problemi, ti dice la versione corrente del database.

Più informazioni sulle migrazioni possono essere trovate nella guida Migrations.

2.4 doc

Il doc: namespace ha gli strumenti per generare documentazione per la tua app, documentazione API, guide. La documentazione può anche essere spogliata, il che è utile soprattutto per snellire il vostro codebase, come se state scrivendo un’applicazione Rails per una piattaforma embedded.

• rake doc:app genera la documentazione per la vostra applicazione in doc/app.
• rake doc:guides genera le guide Rails in doc/guides.
• rake doc:rails genera la documentazione API per Rails in doc/api.
• rake doc:plugins genera la documentazione API per tutti i plugin installati nell’applicazione in doc/plugins.
• rake doc:clobber_plugins rimuove la documentazione generata per tutti i plugin.

2.5 notes

rake notes cerca nel tuo codice i commenti che iniziano con FIXME, OPTIMIZE o TODO. La ricerca viene fatta nei file con estensione .builder, .rb, .erb, .haml e .slim sia per le annotazioni predefinite che per quelle personalizzate.

Se stai cercando un’annotazione specifica, diciamo FIXME, puoi usare rake notes:fixme. Notate che dovete abbassare il nome dell’annotazione.

Potete anche usare annotazioni personalizzate nel vostro codice ed elencarle usando rake notes:custom specificando l’annotazione usando una variabile d’ambiente ANNOTATION.

$ rake notes:custom ANNOTATION=BUG(in /home/foobar/commandsapp)app/model/post.rb: * Have to fix this one before pushing!

2.6 routes

rake routes elencherà tutte le vostre rotte definite, il che è utile per rintracciare problemi di routing nella vostra applicazione, o per darvi una buona panoramica degli URL in un’applicazione con cui state cercando di familiarizzare.

2.7 test

Rails è dotato di una suite di test chiamata Test::Unit. Rails deve la sua stabilità all’uso dei test. I task disponibili nel namespace test: aiutano nell’esecuzione dei diversi test che si spera scriverete.

2.8 tmp

La directory Rails.root/tmp è, come la directory *nix /tmp, il luogo in cui vengono conservati i file temporanei come le sessioni (se state usando un file store per i file), i file id dei processi e le azioni memorizzate nella cache.

I task namespace tmp: vi aiuteranno a pulire la directory Rails.root/tmp:

2.9 Varie

• rake stats è ottimo per guardare le statistiche sul vostro codice, mostrando cose come KLOC (migliaia di linee di codice) e il vostro rapporto codice/test.
• rake secret vi darà una chiave pseudo-casuale da usare per il vostro segreto di sessione.
• rake time:zones:all elenca tutti i fusi orari che Rails conosce.

3 La linea di comando avanzata di Rails

L’uso più avanzato della linea di comando si concentra sulla ricerca di opzioni utili (anche sorprendenti a volte) nelle utility, e sull’adattamento di queste alle vostre esigenze e al vostro specifico flusso di lavoro. Qui sono elencati alcuni assi nella manica di Rails.

3.1 Rails con database e SCM

Quando create una nuova applicazione Rails, avete la possibilità di specificare che tipo di database e che tipo di sistema di gestione del codice sorgente utilizzerà la vostra applicazione. Questo vi farà risparmiare qualche minuto, e certamente molte battute di tasti.

Vediamo cosa faranno per noi l’opzione –git e l’opzione –database=postgresql:

Abbiamo dovuto creare la directory gitapp e inizializzare un repository git vuoto prima che Rails aggiungesse i file creati al nostro repository. Vediamo cosa ha messo nella nostra configurazione del database:

Ha anche generato alcune linee nella nostra configurazione database.yml corrispondenti alla nostra scelta di PostgreSQL come database.

3.2 server con diversi backend

Molte persone hanno creato un gran numero di diversi server web in Ruby, e molti di essi possono essere usati per eseguire Rails. Dalla versione 2.3, Rails usa Rack per servire le sue pagine web, il che significa che può essere usato qualsiasi webserver che implementi un gestore Rack. Questo include WEBrick, Mongrel, Thin, e Phusion Passenger (per nominarne alcuni!).

Per usare un server diverso, basta installare il suo gem, poi usare il suo nome come primo parametro di rails server:

Feedback

Si consiglia di aiutare a migliorare la qualità di questa guida.

Se vedi qualche errore di battitura o di fatto che sei sicuro di poter correggere, per favore clona il repository di rails e apri una nuova richiesta di pull. Puoi anche chiedere i diritti di commit su docrails se hai intenzione di inviare diverse patch. I commit sono rivisti, ma questo avviene dopo che hai inviato il tuo contributo. Questo repository è cross-merged con master periodicamente.

Potresti anche trovare contenuti incompleti, o roba non aggiornata. Per favore, aggiungi qualsiasi documentazione mancante per il master. Controlla le Ruby on Rails Guides Guidelines per lo stile e le convenzioni.

Se per qualsiasi ragione trovi qualcosa da correggere ma non puoi farlo da solo, per favore apri un problema.

E infine, ma non meno importante, ogni tipo di discussione riguardante la documentazione di Ruby on Rails è benvenuta nella mailing list rubyonrails-docs.