Guides.rubyonrails.org

Chapters

1. Miejsca dla kodu inicjującego
2. Korzystanie z inicjalizatorów wstępnych
3. Konfiguracja komponentów Rails
   • Ogólna Konfiguracja Railsów
   • Konfiguracja i18n (internacjonalizacji)
   • Konfiguracja modułu Active Record
   • Konfiguracja modułu Action Controller
   • Konfiguracja modułu Action View
   • Konfiguracja modułu Action Mailer
   • Konfiguracja modułu Active Resource
   • Konfiguracja modułu Active Support
4. Używanie inicjalizatorów (Initializers)
5. Korzystanie z inicjalizatorów końcowych (After-Initializers)
6. Ustawienia Środowiskowe Railsów
7. Changelog

1 Miejsca dla kodu inicjującego

Railsy oferują (co najmniej) pięć dobrych lokalizacji dla umiejscowienia kodu inicjującego:

• inicjalizatory wstępne (Preinitializers)
• plik environment.rb (środowisko)
• Specyficzne środowiskowe pliki konfiguracyjne (Environment)
• inicjalizatory (Initializers) (load_application_initializers)
• inicjalizatory końcowe (After-Initializers)

2 Korzystanie z inicjalizatorów wstępnych

Railsy udostępniają inicjalizator wstępny do uruchomienia kodu, zanim framework sam w sobie się załaduje. Jeśli zapiszesz kod w pilku RAILS_ROOT/config/preinitializer.rb, to zostanie on załadowany jako pierwszy, przed którymkolwiek elementów frameworka (moduł Active Record, moduł Action Pack, i tak dalej.) Jeśli chcesz zmienić zachowanie jednej z klas, używanych w procesie inicjacji, możesz to zrobić w tym pliku.

3 Konfiguracja komponentów Rails

Ogólnie rzecz biorąc, konfiguracja Railsów oznacza konfigurację komponentów Rails, jak również samych Railsów. Plik environment.rb i specyficzne środowiskowe pliki konfiguracyjne (takie jak config/environments/production.rb) pozwalają określić różne ustawienia, które chciałbyś przekazać wszystkim komponentom. Dla przykładu domyślny dla Rails 2.3 plik environment.rb zawiera jedno ustawienie:

jest to ustawienie samych Railsów. Jeśli chcesz przenieść ustawienia do indywidualnych składników Rails, możesz to zrobić dzięki temu samemu obiektowi config:

Railsy będą używać tego konkretnego ustawienia do skonfigurowania modułu Active Record.

3.1 Ogólna Konfiguracja Railsów

• config.routes_configuration_file zastępuje domyślną ścieżkę dla pliku konfiguracji trasy. Ta domyślną to config/routes.rb.

• config.cache_classes ustala czy klasy aplikacji powinny czy nie powinny się przeładować na każde żądanie.

• config.cache_store konfiguruje którego sposobu przechowywania pamięci cache użyć do buforowania Rails. Opcje obejmują: memory_store, :file_store, :mem_cache_store lub nazwę własnej niestandardowej klasy.

• config.controller_paths akceptuje szereg ścieżek, które będą przeszukiwane przez kontrolery. Domyślnie app/controllers.

• config.database_configuration_file zastępuje domyślną ścieżkę dla pliku konfiguracyjnego bazy danych. Domyślnie do config/database.yml.

• config.dependency_loading włącza lub wyłącza ładowanie zależności podczas cyklu żądania. Ustawianie dependency_loading na true pozwoli nowym klasom być załadowanym podczas żądania, a ustawienie ich na false wyłącza to zachowanie.

• config.eager_load_paths akceptuje tablicę ścieżek, z której zostaną załadowane przy starcie Railsów, jeśli klasa cache jest aktywna. Wszystkie elementy tej tablicy muszą być również w load_paths.

• config.frameworks akceptuje tablicę elementów frameworka Rails, które powinny zostać załadowane. (Domyślnie do :active_record :action_controller :action_view :action_mailer i :active_resource).

• config.load_once_paths akceptuje tablicę ścieżek, które Railsy tylko raz automatycznie pobiorą. Wszystkie elementy tej tablicy muszą być również w load_paths.

• config.load_paths akceptuje tablicę dodatkowych ścieżek do dopisania do ścieżki ładowania. Domyślnie wszystkie ścieżki do app, lib, vendor i mock znajdują się na liście.

• config.log_level określa wyjście wyświetlanych poleceń loggera Rails. W trybie produkcji – domyślnie do :info. W trybie rozwoju do :debug.

• config.log_path nadpisuje ścieżkę do użytkowego pliku log. Domyślnie do log/#{environment}. log (np. log/development.log lub log/production.log).

• config.logger akceptuje logger zgodny z interfejsem Log4r lub domyślną klasą Logger w Ruby 1.8+, który jest następnie wykorzystywany do logowania informacji z modułu Action Controller. Ustaw na nil (zero), aby wyłączyć rejestrowanie.

• config.metals akceptuje tablicę wykorzystywaną jako moduły metals do załadowania. Jeśli jest ustawiony na nil, wszystkie moduły metals zostaną załadowane w kolejności alfabetycznej. Jeśli jest ustawiony na [], moduły nie zostaną załadowane. W przeciwnym wypadku będą ładowane w określonej kolejności.

• config.plugin_loader zastępuje klasę, która obsługuje ładowanie każdej wtyczki. Domyślnie Rails::Plugin::Loader.

• config.plugin_locators zastępuje klasę, zajmującą się znajdywaniem potrzebnych wtyczek, które chciałbyś załadować do swojej aplikacji. Domyślnie jest to Rails::Plugin::FileSystemLocator.

• config.plugin_paths nadpisuje ścieżkę do głównego katalogu wtyczek. Domyślnie vendor/plugins.

• config.plugins akceptuje listę wtyczek do załadowania. Jeśli jest ustawiony na nil, wszystkie wtyczki zostaną załadowane. Jeśli jest ustawiony na [], żadne wtyczki nie zostaną załadowane. W przeciwnym wypadku, wtyczki zostaną załadowane w określonej kolejności.

• config.preload_frameworks włącza lub wyłącza wstępne ładowanie wszystkich frameworków przy starcie.

• config.reload_plugins włącza lub wyłącza przeładowywanie wtyczek.

• config.root_path konfiguruje ścieżkę głównego katalogu aplikacji.

• config.time_zone ustawia domyślną strefę czasową dla aplikacji i umożliwia przenoszenie strefy czasowej do modułu Active Record.

• config.view_path określa ścieżkę głównego katalogu widoków aplikacji. Domyślnie app/views.

• config.whiny_nils włącza lub wyłącza ostrzeżenia, gdy powoływane są metody nil. Domyślnie false.

3.2 Konfiguracja i18n (internacjonalizacji)

• config.i18n.default_locale ustawia domyślne ustawienia regionalne aplikacji wykorzystywane do i18n. Domyślnie :en.

• config.i18n.load_path ustawia ścieżkę, której Rails używa, aby wyszukać pliki lokalne. Domyślnie config/locales/*.{yml,rb}

3.3 Konfiguracja modułu Active Record

config.active_record zawiera wiele opcji konfiguracyjnych:

• config.active_record.logger akceptuje logger zgodny z interfejsem Log4r lub domyślną klasą Logger w Ruby 1.8x, który jest następnie przekazywany do każdego nowego połączenia z bazą danych. Możesz pobrać ten logger wywołując logger zarówno z modelowej klasy Active Record jak i z modelowej instancji Active Rekord. Ustaw na nil, aby wyłączyć rejestrowanie.

• config.active_record.primary_key_prefix_type umożliwia dostosowanie nazewnictwa klucza głównego kolumn. Domyślnie, Railsy zakładają, że klucze główne kolumn nazywają się id (i ta opcja konfiguracyjna nie musi być ustawiona.) Istnieją dwie inne możliwości:
  • :table_name ustawia klucz główny dla klasy Customer na customerid
  • :table_name_with_underscore ustawia klucz główny dla klasy Customer jako customer_id

• config.active_record.table_name_prefix pozwala ustawić globalny łańcuch znaków, który zostanie dodany do nazw tabeli. Jeśli ustawisz na northwest_, następnie klasa Customer będzie przeszukiwać northwest_customers jako tabelę. Domyślnie jest to ciąg pusty.

• config.active_record.table_name_suffix pozwala ustawić globalny łańcuch znaków, który zostanie dodany do nazw tabeli. Jeśli ustawisz na _northwest, następnie klasa Customer będzie przeszukiwać customers_northwest jako tabelę. Domyślnie jest to ciąg pusty.

• config.active_record.pluralize_table_names określa, czy Railsy będą szukać pojedynczych czy mnogich nazw tabel w bazie danych. Jeśli jest ustawiony na true (domyślnie), wtedy klasa Customer będzie korzystać z tabeli customers. Jeśli jest ustawiona na false, klasa Customers będzie korzystać z tabeli customer.

• config.active_record.colorize_logging (domyślnie true) określa, czy korzystać z kodów kolorów ANSI podczas zapisywania do logu informacji z modułu ActiveRecord.

• config.active_record.default_timezone określa, czy użyć Time.local (jeśli jest ustawione na :local) lub Time.utc (jeśli jest ustawione na :utc), przy wyciąganiu dat i godzin z bazy danych. Domyślnie :local.

• config.active_record.schema_format kontroluje format zrzutu schematu bazy danych do pliku. Dostępne opcje to: :rubin (domyślne) dla wersji niezależnej od bazy danych, opierającej się na migracjach, lub :sql dla zestawu (potencjalnie zależnych od bazy) poleceń SQL.

• config.active_record.timestamped_migrations sprawdza czy migracje są ponumerowane seryjnymi całkowitymi czy znacznikiem czasu. Domyślnie ustawione na true dla wykorzystania preferowanych znaczników czasu, jeśli wielu programistów pracuje na tej samej aplikacji.

• config.active_record.lock_optimistically ustala czy moduł ActiveRecord użyje blokowania optymistycznego. Domyślnie true.

Adapter MySQL udostępnia jedną dodatkową opcję konfiguracji:

• ActiveRecord::ConnectionAdapters::MysqlAdapter.emulate_booleans kontroluje czy moduł ActiveRecord uzna wszystkie kolumny tinyint(1) bazy danych MySQL za wartości logiczne. Domyślnie jest to true.

Mechanizm dokonujący zrzutu schematu udostępnia jedną dodatkową opcję konfiguracji:

• ActiveRecord::SchemaDumper.ignore_tables akceptuje tablicę tabel, które nie powinny zostać włączone do żadnego wygenerowanego pliku schematu. To ustawienie będzie ignorowane, dopóki config.active_record.schema_format ==:ruby.

3.4 Konfiguracja modułu Action Controller

config.action_controller zawiera szereg ustawień konfiguracji:

• config.action_controller.asset_host dostarcza ciąg znaków dodawany do wszystkich helperów generujących URL w AssetHelper. Jest zaprojektowany, by umożliwić przeniesienie wszystkich plików JavaScript, CSS i plików graficznych do wydzielonego hosta przechowującego zasoby tego rodzaju.

• config.action_controller.consider_all_requests_local zazwyczaj ustawione na true w trakcie rozwoju i na false podczas produkcji, jeśli jest ustawione na true, to każdy błąd spowoduje wyświetlenie szczegółowych informacji dotyczących debugowania, wysłanych w odpowiedzi HTTP. Dla jeszcze dokładniejszej kontroli, należy ustawić na false i zaimplementować local_request?, aby określić, które żądania powinny umożliwić debugowanie informacji o błędach.

• config.action_controller.allow_concurrency powinien być ustawiony na true, by umożliwić jednoczesne przetwarzanie działań w bezpiecznym trybie wielowątkowym (threadsafe), czyli takie, by jednoczesne wywoływanie funkcji przez kilka watków działało poprawnie. Ustawione domyślnie na false. zapewne nie chcesz wywołać tego bezpośrednio, ale, ze względu na wiele innych regulacji, należy zadbać, aby tryb bezpieczeństwa wątków działał poprawnie. Zamiast tego należy po prostu wywołać config.threadsafe! wewnątrz swojego pliku production.rb, co sprawi, że wszystkie niezbędne zmiany zostaną zastosowane.

• config.action_controller.param_parsers dostarcza tablicę handlerów, które mogą wyłuskać informacje z przychodzących żądań HTTP i dodać je do params hash. Domyślnie parsery dla formularzy wieloczęściowych, formularzy kodowanych URL, XML i JSON są aktywne.

• config.action_controller.default_charset określa domyślne kodowanie (zestaw znaków) dla wszystkich renderów. Domyślnie jest to “utf-8”.

• config.action_controller.logger akceptuje logger zgodny z interfejsem Log4r lub domyślną klasą Logger w Ruby 1.8+, który jest następnie wykorzystywany do logowania informacji z modułu Action Controller. Ustaw na nil, aby wyłączyć rejestrowanie.

• config.action_controller.resource_action_separator określa znak stosowany między zasobami i akcjami (działaniami), przy tworzeniu lub interpretacji adresów URL typu REST. Domyślnie jest to “/”.

• config.action_controller.resource_path_names to skrót domyślnych nazw kilku akcji zgodnych z REST. Domyślnie, nową akcję nazwiemy new, a edycję akcji edit.

• config.action_controller.request_forgery_protection_token ustawia nazwę znaku parametru dla modułu RequestForgery. Wywołanie protect_from_forgery ustawia go domyślnie na :authenticity_token.

• config.action_controller.optimise_named_routes włącza niektóre optymalizacje przy tworzeniu tablicy routingu. Jest ustawione domyślnie na true.

• config.action_controller.use_accept_header określa zasady ustalania formatu odpowiedzi. Jeśli jest ustawione na true (domyślnie), to respond_to i Request#format wezmą pod uwagę nagłówek Accept. Jeśli jest ustawione na false to format żądania zostanie ustalony wyłącznie przez analizę params[:format]. Jeśli nie ma parametru format, to odpowiedź będzie w formacie HTML lub JavaScript, w zależności od tego, co wywołuje AJAXowe żądanie.

• config.action_controller.allow_forgery_protection włącza lub wyłącza ochronę CSRF. Domyślnie jest ustawione na false w trybie testowym i true we wszystkich innych trybach.

• config.action_controller.relative_url_root można użyć, by wskazać Railsom, że rozwijasz aplikację w podkatalogu. Domyślnie ENV['RAILS_RELATIVE_URL_ROOT'].

• config.action_controller.session_store określa nazwę sposobu przechowywania danych sesji. Domyślnie jest to :cookie_store; inne poprawne opcje to :active_record_store :mem_cache_store lub nazwa własnej klasy niestandardowej.

Cache’owanie kodu dodaje dwa dodatkowe ustawienia:

• ActionController::Base.page_cache_directory określa katalog, w którym Rails stworzy scache’owane strony dla serwera web. Wartość domyślna to Rails.public_path (zazwyczaj ustawione jako RAILS_ROOT“/public”+).

• ActionController::Base.page_cache_extension ustawia rozszerzenie wykorzystywane przy generowaniu stron do cache (ignorowane, jeśli przychodzące żądanie ma już rozszerzenie). Domyślnie jest to .html.

Mechanizm przechowywania sesji modułu Active Record może jeszcze być skonfigurowany:

• ActiveRecord::SessionStore::Session.table_name określa nazwę tabeli używanej do przechowywania sesji. Domyślnie sessions.

• ActiveRecord::SessionStore::Session.primary_key określa nazwę kolumny ID używanej w tabeli sesji. Domyślnie session_id.

• ActiveRecord::SessionStore::Session.data_column_name określa nazwę kolumny, która przechowuje uporządkowane dane sesji. Domyślnie data.

3.5 Konfiguracja modułu Action View

Istnieje tylko kilka opcji konfiguracyjnych modułu Action View, poczynając od czterech na ActionView::Base:

• config.action_view.debug_rjs określa, czy odpowiedzi RJS powinny być opakowane w blok try/catch, który wywołuje metodę JavaScript alert dla złapanych wyjątków (poczym ponownie je rzuca). Domyślnie false.

• config.action_view.warn_cache_misses mówi Railsom czy wyświetlać ostrzeżenie o każdym wyniku działań bufora na ścieżkach widoków. Domyślnie false.

• config.action_view.field_error_proc zapewnia generator HTML do wyświetlania błędów pochodzących z Active Record. Domyślnie Proc.new{ |html_tag, instance| “<div class=\”fieldWithErrors\“>#{html_tag}</div>” }

• config.action_view.default_form_builder mówi Railsom, który builder ma być używany domyślnie. Domyślnym jest ActionView::Helpers::FormBuilder.

• config.action_view.logger akceptuje logger zgodny z interfejsem Log4r lub domyślną klasą Logger w Ruby 1.8+, który jest następnie wykorzystywany do logowania informacji z modułu Action View. Ustaw na nil, aby wyłączyć rejestrowanie.

• Config.action_view.erb_trim_mode określa jaki tryb obcinania ma być używany przez ERB. Domyślnie jest to '-'. Patrz: “Dokumentacja ERB”: http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/ aby uzyskać więcej informacji.

3.6 Konfiguracja modułu Action Mailer

Istnieje szereg ustawień dostępnych w config.action_mailer:

• config.action_mailer.template_root określa główny folder działania szablonów modułu Mailer.

• config.action_mailer.logger akceptuje logger zgodny z interfejsem Log4r lub domyślną klasą Logger w Ruby 1.8+, który jest następnie wykorzystywany do logowania informacji z modułu Action Mailer. Ustaw na nil, aby wyłączyć rejestrowanie.

• config.action_mailer.smtp_settings umożliwia szczegółową konfigurację metody dostarczania :smtp. Akceptuje hash z opcjami, jak np. dowolna z następujących:
  • :address – Pozwala korzystać ze zdalnego serwera poczty. Wystarczy zmienić z domyślnego ustawienia “localhost”.
  • :port – W przypadku, gdy twój serwer pocztowy nie działa na porcie 25, można go zmienić.
  • :domain – Jeśli musisz określić domenę HELO, możesz to zrobić tutaj.
  • :user_name – Jeśli serwer poczty wymaga uwierzytelniania, należy tutaj wstawić nazwę użytkownika.
  • :password – Jeśli serwer poczty wymaga uwierzytelniania, należy ustawić hasło w tym miejscu.
  • :authentication – Jeśli serwer poczty wymaga uwierzytelniania, należy tutaj określić jego typ. Jest to jeden z symboli :plain, :login, :cram_md5.

• config.action_mailer.sendmail_settings umożliwia szczegółową konfigurację metody dostarczania :sendmail. Akceptuje hash z opcjami, jak np. dowolna z następujuących:
  • :location – Położenie wykonywalnego sendmaila. Domyślnie jest to /usr/sbin/sendmail.
  • :arguments – Argumenty wiersza poleceń. Domyślnie jest to -i -t.

• config.action_mailer.raise_delivery_errors określa, czy zgłosić błąd, jeśli nie można dostarczyć przesyłki email. Domyślnie jest to true.

• config.action_mailer.delivery_method określa metodę dostarczania. Dozwolone wartości to :smtp (domyślnie), :sendmail i :test.

• config.action_mailer.perform_deliveries określa, czy mail zostanie faktycznie wysłany. Domyślnie jest to true, ustawienie na false może być przydatne dla testów.

• config.action_mailer.default_charset mówi modułowi Action Mailer, jakiego kodowania używać dla body i zakodowania tematu. Domyślnie jest to utf-8.

• config.action_mailer.default_content_type określa typ zawartości domyślnie używany w głównej części wiadomości. Domyślnie jest to “text/plain”

• config.action_mailer.default_mime_version domyślna wersja MIME wiadomości. Domyślnie: 1,0.

• config.action_mailer.default_implicit_parts_order – Gdy wiadomość jest zbudowana w sposób dorozumiany (np. wiele części składa się z szablonów, które określają typ zawartości w nazwach plików) ta zmienna steruje kolejnością części. Domyślnie ["text/html", "text/enriched", "text/plain"]. Elementy, które pojawiają się pierwsze w tablicy, mają wyższy priorytet dla klienta poczty i pojawiają się jako ostatnie w komunikatach zakodowanych w mime.

3.7 Konfiguracja modułu Active Resource

Jest tylko jedno ustawienie konfiguracji dostępne dla config.active_resource:

• config.active_resource.logger akceptuje logger zgodny z interfejsem Log4r lub domyślną klasą Logger w Ruby 1.8+, który jest następnie wykorzystywany do logowania informacji z modułu Active Resource. Ustaw na nil, aby wyłączyć rejestrowanie.

3.8 Konfiguracja modułu Active Support

Istnieje kilka opcji konfiguracyjnych dostępnych w module Active Support:

• config.active_support.escape_html_entities_in_json włącza lub wyłącza cytowanie jednostek HTML przy serializacji JSON. Domyślnie true.

• config.active_support.use_standard_json_time_format włącza lub wyłącza serializację daty do formatu ISO 8601. Domyślnie false.

• ActiveSupport::BufferedLogger.silencer ustawione na false, aby wyłączyć możliwość logowania w tle bloku. Domyślnie true.

• ActiveSupport::Cache:: Store.logger określa logger wykorzystany w ramach działalności cache’u.

• ActiveSupport::Logger.silencer ustawione na false, aby wyłączyć możliwość logowania w tle bloku. Domyślnie true.

4 Używanie inicjalizatorów (Initializers)

Po załadowaniu frameworka wraz z gemami i wtyczkami w aplikacji, Rails zaczyna ładować inicjalizatory. Inicjalizator to dowolny plik w kodzie Ruby, zapisany w config/initializers w twojej aplikacji. Możesz użyć inicjalizatora do przechowywania ustawień konfiguracyjnych, które powinny zostać wykonane po załadowaniu wszystkich frameworków i wtyczek.

5 Korzystanie z inicjalizatorów końcowych (After-Initializers)

inicjalizatory końcowe są wprowadzane (jak można się domyślić) po załadowaniu inicjalizatorów. Możesz dodać blok after_initialize (lub tablicę takich bloków) poprzez ustawienie config.after_initialize w którymś z plików konfiguracyjnych Rails:

6 Ustawienia Środowiskowe Railsów

Niektóre części Rails można również skonfigurować z zewnątrz poprzez dostarczanie zmiennych środowiskowych. Następujące zmienne środowiskowe są rozpoznawane przez różne części Rails:

• ENV['RAILS_ENV'] określa środowisko Rails (produkcja, rozwój, test, itd.), w ramach którego będą realizowane Railsy.

• ENV['RAILS_RELATIVE_URL_ROOT'] jest używany przez kod routingu dla rozpoznania adresów URL, gdy przenosisz swoją aplikację do podkatalogu.

• ENV["RAILS_ASSET_ID"] zastąpi domyślny sposób zwolnienia cache dla znaczników czasu, które Railsy generują dla pobieralnych elementów.

• ENV["RAILS_CACHE_ID"] i ENV["RAILS_APP_VERSION"] są używane do generowania kluczy rozszerzonej pamięci w kodzie chachowania Rails. Pozwala to na tworzenie wielu oddzielnych cache’y dla jednej aplikacji.

• ENV['RAILS_GEM_VERSION'] określa wersję gemów wykorzystanych przez Railsy, jeśli w pliku environment.rb nie zostało zdefiniowane RAILS_GEM_VERSION.

7 Changelog

Lighthouse ticket

• 13 sierpnia 2009: Aktualizacja składni config i dodanie ogólnych opcji konfiguracyjnych przez “Johna Pignatę”
• 3 stycznia 2009: Pierwszy w miarę kompletny projekt Mika Gunderloy’a
• 5 listopada 2008: Wstępny zarys stworzony przez Mike Gunderloy