diff --git a/README.ru.rdoc b/README.ru.rdoc index cbcd1e1d..c2383592 100644 --- a/README.ru.rdoc +++ b/README.ru.rdoc @@ -94,7 +94,7 @@ Sinatra — это предметно-ориентированный язык (D end get '/foo' do - # соответствует с non-songbird браузерам + # соответствует non-songbird браузерам end Другими доступными условиями являются +host_name+ и +provides+: @@ -126,7 +126,7 @@ Sinatra — это предметно-ориентированный язык (D === Возвращаемые значения Возвращаемое значение блока маршрута ограничивается телом ответа, которое будет передано HTTP клиенту, -или следующей подпрограммой (middleware) в Rack стеке. Чаще всего это строка, как в вышеизложенных примерах. +или следующей "прослойкой" (middleware, промежуточная программа) в Rack стеке. Чаще всего это строка, как в вышеизложенных примерах. Но и другие значения также приемлемы. Вы можете вернуть любой объект, который будет либо корректным Rack ответом, Rack @@ -172,7 +172,7 @@ Sinatra — это предметно-ориентированный язык (D === Haml шаблоны -Haml gem/библиотека необходима для рендеринга HAML шаблонов: +haml gem/библиотека необходима для рендеринга HAML шаблонов: # Вам нужно будет подключить haml gem в приложении require 'haml' @@ -204,24 +204,35 @@ Haml gem/библиотека необходима для рендеринга H erb :index end -Отрисует ./views/index.erb +Отрисует ./views/index.erb. === Erubis шаблоны -Erubis gem/библиотека необходима для рендеринга erubis шаблонов: +erubis gem/библиотека необходима для рендеринга Erubis шаблонов: - # Вам нужно будет подключить erubis в приложении + # Вам нужно будет подключить Erubis в приложении require 'erubis' get '/' do erubis :index end -Отрисует ./views/index.erubis +Отрисует ./views/index.erubis. + +Также возможно заменить Erb на Erubis: + + require 'erubis' + Tilt.register :erb, Tilt[:erubis] + + get '/' do + erb :index + end + +Отрисует ./views/index.erb с помощью Erubis. === Builder шаблоны -Builder gem/библиотека необходима для рендеринга builder шаблонов: +builder gem/библиотека необходима для рендеринга builder шаблонов: # Вам нужно будет подключить builder в приложении require 'builder' @@ -234,7 +245,7 @@ Builder gem/библиотека необходима для рендеринг === Nokogiri шаблоны -Nokogiri gem/библиотека необходима для рендеринга nokogiri шаблонов: +nokogiri gem/библиотека необходима для рендеринга nokogiri шаблонов: # Вам нужно будет подключить nokogiri в приложении require 'nokogiri' @@ -247,7 +258,7 @@ Nokogiri gem/библиотека необходима для рендеринг === Sass шаблоны -Haml gem/библиотека необходима для рендеринга Sass шаблонов: +haml gem/библиотека необходима для рендеринга Sass шаблонов: # Вам нужно будет подключить haml или sass в приложении require 'sass' @@ -271,7 +282,7 @@ Haml gem/библиотека необходима для рендеринга S === Scss шаблоны -Haml gem/библиотека необходима для рендеринга Scss шаблонов: +haml gem/библиотека необходима для рендеринга Scss шаблонов: # Вам нужно будет подключить haml или sass в приложении require 'sass' @@ -295,7 +306,7 @@ Haml gem/библиотека необходима для рендеринга S === Less шаблоны -less gem/библиотека необходима для рендеринга Less шаблонов: +less gem/библиотека необходима для рендеринга Less шаблонов: # Вам нужно будет подключить less в приложении require 'less' @@ -308,7 +319,7 @@ less gem/библиотека необходима для рендеринга L === Liquid шаблоны -liquid gem/библиотека необходима для рендеринга liquid шаблонов: +liquid gem/библиотека необходима для рендеринга liquid шаблонов: # Вам нужно будет подключить liquid в приложении require 'liquid' @@ -326,7 +337,7 @@ liquid gem/библиотека необходима для рендеринга === Markdown шаблоны -rdiscount gem/библиотека необходима для рендеринга Markdown шаблонов: +rdiscount gem/библиотека необходима для рендеринга Markdown шаблонов: # Вам нужно будет подключить rdiscount в приложении require "rdiscount" @@ -338,19 +349,56 @@ rdiscount gem/библиотека необходима для рендерин Отрисует ./views/index.markdown (+md+ и +mkd+ также являются допустимыми файловыми расширениями). -В markdown невозможно вызывать методы или передавать локальные переменные. Следовательно, вам скорее всего придется -использовать этот шаблон совместно с другим движком рендеринга: +В Markdown невозможно вызывать методы или передавать локальные переменные. +Следовательно, вам, скорее всего, придется использовать этот шаблон совместно с другим +движком рендеринга: erb :overview, :locals => { :text => markdown(:introduction) } -Заметьте, что вы можете вызывать метод markdown из других шаблонов: +Заметьте, что вы можете вызывать метод +markdown+ из других шаблонов: %h1 Hello From Haml! %p= markdown(:greetings) +Вы не можете вызывать Ruby из Markdown, соответственно, вы не можете использовать +лэйаут-шаблоны (layouts) на Markdown. Тем не менее, есть возможность использовать один +движок рендеринга для шаблона, а другой для лэйаута с помощью опции `:layout_engine`: + + get '/' do + markdown :index, :layout_engine => :erb + end + +Отрисует ./views/index.md с ./views/layout.erb в качестве +лэйаута. + +Также вы можете задать такие опции рендеринга глобально: + + set :markdown, :layout_engine => :haml, :layout => :post + + get '/' do + markdown :index + end + +Отрисует ./views/index.md (и любой другой шаблон на Markdown) с +./views/post.haml в качестве лэйаута. + +Также возможно обрабатывать Markdown с помощью BlueCloth, а не RDiscount: + + require 'bluecloth' + + Tilt.register 'markdown', BlueClothTemplate + Tilt.register 'mkd', BlueClothTemplate + Tilt.register 'md', BlueClothTemplate + + get '/' do + markdown :index + end + +Отрисует ./views/index.md с помощью BlueCloth. + === Textile шаблоны -RedCloth gem/библиотека необходима для рендеринга Textile шаблонов: +RedCloth gem/библиотека необходима для рендеринга Textile шаблонов: # Вам нужно будет подключить redcloth в приложении require "redcloth" @@ -361,19 +409,41 @@ RedCloth gem/библиотека необходима для рендеринг Отрисует ./views/index.textile. -В textile невозможно вызывать методы или передавать локальные переменные. Следовательно, вам скорее всего придется -использовать этот шаблон совместно с другим движком рендеринга: +В Textile невозможно вызывать методы или передавать локальные переменные. Следовательно, вам, скорее всего, +придется использовать этот шаблон совместно с другим движком рендеринга: erb :overview, :locals => { :text => textile(:introduction) } -Заметьте, что вы можете вызывать метод textile из других шаблонов: +Заметьте, что вы можете вызывать метод +textile+ из других шаблонов: %h1 Hello From Haml! %p= textile(:greetings) +Вы не можете вызывать Ruby из Textile, соответственно, вы не можете использовать +лэйаут-шаблоны на Textile. Тем не менее, есть возможность использовать один +движок рендеринга для шаблона, а другой для лэйаута с помощью опции `:layout_engine`: + + get '/' do + textile :index, :layout_engine => :erb + end + +Отрисует ./views/index.textile с ./views/layout.erb в качестве +лэйаута. + +Также вы можете задать такие опции рендеринга глобально: + + set :textile, :layout_engine => :haml, :layout => :post + + get '/' do + textile :index + end + +Отрисует ./views/index.textile (и любой другой шаблон на Textile) с +./views/post.haml в качестве лэйаута. + === RDoc шаблоны -RDoc gem/библиотека необходима для рендеринга RDoc шаблонов: +rdoc gem/библиотека необходима для рендеринга RDoc шаблонов: # Вам нужно будет подключить rdoc в приложении require "rdoc" @@ -384,19 +454,41 @@ RDoc gem/библиотека необходима для рендеринга R Отрисует ./views/index.rdoc. -В rdoc невозможно вызывать методы или передавать локальные переменные. Следовательно, вам скорее всего придется -использовать этот шаблон совместно с другим движком рендеринга: +В RDoc невозможно вызывать методы или передавать локальные переменные. Следовательно, вам, скорее всего, +придется использовать этот шаблон совместно с другим движком рендеринга: erb :overview, :locals => { :text => rdoc(:introduction) } -Заметьте, что вы можете вызывать метод rdoc из других шаблонов: +Заметьте, что вы можете вызывать метод +rdoc+ из других шаблонов: %h1 Hello From Haml! %p= rdoc(:greetings) +Вы не можете вызывать Ruby из RDoc, соответственно, вы не можете использовать +лэйаут-шаблоны на RDoc. Тем не менее, есть возможность использовать один +движок рендеринга для шаблона, а другой для лэйаута с помощью опции `:layout_engine`: + + get '/' do + rdoc :index, :layout_engine => :erb + end + +Отрисует ./views/index.rdoc с ./views/layout.erb в качестве +лэйаута. + +Также вы можете задать такие опции рендеринга глобально: + + set :rdoc, :layout_engine => :haml, :layout => :post + + get '/' do + rdoc :index + end + +Отрисует ./views/index.rdoc (и любой другой шаблон на RDoc) с +./views/post.haml в качестве лэйаута. + === Radius шаблоны -radius gem/библиотека необходима для рендеринга Radius шаблонов: +radius gem/библиотека необходима для рендеринга Radius шаблонов: # Вам нужно будет подключить radius в приложении require 'radius' @@ -414,7 +506,7 @@ radius gem/библиотека необходима для рендеринга === Markaby шаблоны -markaby gem/библиотека необходима для рендеринга Markaby шаблонов: +markaby gem/библиотека необходима для рендеринга Markaby шаблонов: # Вам нужно будет подключить markaby в приложении require 'markaby' @@ -425,8 +517,7 @@ markaby gem/библиотека необходима для рендеринг Отрисует ./views/index.mab. -Если у вас установлен Tilt версии 1.2 или выше, то вы также можете использовать внутристроковые -markaby шаблоны: +Вы также можете использовать внутристроковые Markaby шаблоны: get '/' do markaby { h1 "Welcome!" } @@ -434,7 +525,7 @@ markaby шаблоны: === Slim шаблоны -slim gem/библиотека необходима для рендеринга slim шаблонов: +slim gem/библиотека необходима для рендеринга slim шаблонов: # Вам нужно будет подключить slim в приложении require 'slim' @@ -447,7 +538,16 @@ slim gem/библиотека необходима для рендеринга s === CoffeeScript шаблоны -coffee-script gem/библиотека и `coffee` бинарный файл необходимы для рендеринга CoffeeScript шаблонов: +Вам понадобится coffee-script gem/библиотека и что-то одно из следующего списка, +чтобы запускать JavaScript: + +* +node+ (из Node.js) +* вы можете использовать OSX (есть встроенные средства для выполнения JavaScript) +* +therubyracer+ gem/библиотека + +Подробнее смотрите на {странице проекта}[http://github.com/josh/ruby-coffee-script]. + +Таким образом вы можете использовать CoffeeScript шаблоны. # Вам нужно будет подключить coffee-script в приложении require 'coffee-script' @@ -458,18 +558,18 @@ coffee-script gem/библиотека и `coffee` бинарный файл н Отрисует ./views/application.coffee. -=== Внутристроковые шаблоны +=== Встроенные шаблоны get '/' do haml '%div.title Hello World' end -Отрисует внутристроковый шаблон. +Отрисует встроенный (строчный) шаблон. === Доступ к переменным в шаблонах -Шаблоны интерпретируются в том же контексте, что и обработчики маршрутов. Переменные экзмепляра, -установленные в процесе обработки маршрутов, будут доступны напрямую в шаблонах: +Шаблоны интерпретируются в том же контексте, что и обработчики маршрутов. Переменные экземпляра, +установленные в процессе обработки маршрутов, будут доступны напрямую в шаблонах: get '/:id' do @foo = Foo.find(params[:id]) @@ -483,7 +583,7 @@ coffee-script gem/библиотека и `coffee` бинарный файл н haml '%h1= foo.name', :locals => { :foo => foo } end -Это обычно используется когда шаблоны рендерятся как частные (partials) из других шаблонов. +Это обычный подход, когда шаблоны рендерятся как частные (partials) из других шаблонов. === Вложенные шаблоны @@ -504,7 +604,7 @@ coffee-script gem/библиотека и `coffee` бинарный файл н @@ index %div.title Hello world!!!!! -Заметьте: Вложенные шаблоны, определенные в файле-исходнике, который подключил sinatra, будут +Заметьте: Вложенные шаблоны, определенные в файле-исходнике, который подключил Sinatra, будут автоматически загружены. Вызовите enable :inline_templates напрямую, если у вас вложенные шаблоны в других файлах. @@ -525,16 +625,42 @@ coffee-script gem/библиотека и `coffee` бинарный файл н end Если шаблон с именем "layout" существует, то он будет использован каждый раз, -когда шаблоны будут отрисовываться. Вы можете отключить layout-шаблон с помощью :layout => false. +когда шаблоны будут отрисовываться. Вы можете отключать лэйаут в каждом конкретном случае с помощью +:layout => false или отключить его для всего приложения, например, так: set :haml, :layout => false. get '/' do haml :index, :layout => !request.xhr? end -== Методы помощники +=== Привязка файловых расширений -Используйте helpers метод для определения методов помощников для дальнейшего -использования в обработчиках маршрутов и шаблонах: +Чтобы связать расширение файла и движок рендеринга, используйте +Tilt.register. Например, если вы хотите использовать расширение +tt+ +для шаблонов Textile: + + Tilt.register :tt, Tilt[:textile] + +=== Добавление собственного движка рендеринга + +Сначала зарегистрируйте свой движок в Tilt, затем создайте метод, отвечающий за отрисовку: + + Tilt.register :myat, MyAwesomeTemplateEngine + + helpers do + def myat(*args) render(:myat, *args) end + end + + get '/' do + myat :index + end + +Отрисует ./views/index.myat. Чтобы узнать больше о Tilt, +смотрите https://github.com/rtomayko/tilt + +== Методы-помощники + +Используйте метод helpers, чтобы определить методы-помощники, которые +в дальнейшем можно будет использовать в обработчиках маршрутов и шаблонах: helpers do def bar(name) @@ -641,23 +767,23 @@ After-фильтры выполняются после каждого запро request.request_method # "GET" request.query_string # "" request.content_length # длина тела запроса - request.media_type # медиа тип тела запроса + request.media_type # медиатип тела запроса request.host # "example.com" - request.get? # true (для других участвующих HTTP глаголов есть похожие методы) + request.get? # true (есть аналоги для других методов HTTP) request.form_data? # false - request["SOME_HEADER"] # значение SOME_HEADER заголовка + request["SOME_HEADER"] # значение заголовка SOME_HEADER request.referer # источник запроса клиента либо '/' request.user_agent # user agent (используется для :agent условия) - request.cookies # хеш куки браузера + request.cookies # хеш с куками браузера request.xhr? # является ли запрос ajax запросом? request.url # "http://example.com/example/foo" request.path # "/example/foo" - request.ip # IP адрес клиента + request.ip # IP-адрес клиента request.secure? # false - request.env # env хеш как получено Rack + request.env # "сырой" env хеш, полученный Rack end -Некоторые опции, такие как script_name или path_info могут быть переписаны: +Некоторые опции, такие как script_name или path_info доступны для записи: before { request.path_info = "/" } @@ -699,7 +825,7 @@ After-фильтры выполняются после каждого запро Обработчики ошибок исполняются в том же контексте, что и маршруты, before-фильтры, а это означает, что всякие прелести вроде haml, erb, halt и т.д. доступны и им. -===  NotFound +=== NotFound Когда возбуждено исключение Sinatra::NotFound, или кодом ответа является 404, то будет вызван not_found обработчик: @@ -752,9 +878,9 @@ After-фильтры выполняются после каждого запро Sinatra устанавливает специальные not_found и error обработчики, когда запущена в режиме разработки (окружение :development). -== Mime типы +== Mime-типы -Когда вы используете send_file или статические файлы, у вас могут быть mime типы, которые Sinatra +Когда вы используете send_file или статические файлы, у вас могут быть mime-типы, которые Sinatra не понимает по умолчанию. Используйте +mime_type+ для их регистрации по расширению файла: mime_type :foo, 'text/foo' @@ -763,15 +889,15 @@ Sinatra устанавливает специальные not_found и content_type :foo -== Rack подпрограммы +== Rack "прослойки" Sinatra использует Rack[http://rack.rubyforge.org/], минимальный стандартный интерфейс для веб-фреймворков на Ruby. Одной из самых интересных для разработчиков возможностей Rack -является поддержка подпрограмм ("middleware") -- компонентов, +является поддержка "прослоек" ("middleware") — компонентов, "сидящих" между сервером и вашим приложением, которые отслеживают и/или манипулируют HTTP запросами/ответами для предоставления различной функциональности. -В Sinatra очень просто использовать такие Rack подпрограммы с помощью метода +use+: +В Sinatra очень просто использовать такие "прослойки" с помощью метода +use+: require 'sinatra' require 'my_custom_middleware' @@ -792,7 +918,7 @@ Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL username == 'admin' && password == 'secret' end -Rack распространяется с различными стандартными подпрограммами +Rack распространяется с различными стандартными "прослойками" для логирования, отладки, маршрутизации URL, аутентификации, обработки сессий. Sinatra использует многие из этих компонентов автоматически, основываясь на конфигурации, чтобы вам не приходилось регистрировать/использовать (+use+) их вручную. @@ -829,16 +955,15 @@ Rack распространяется с различными стандартн end end -Заметьте: Встроенные модули Sinatra::Test и Sinatra::TestHarness являются -устаревшими, начиная с 0.9.2 релиза. +Обратите внимание: Встроенные модуль Sinatra::Test и класс Sinatra::TestHarness являются +устаревшими, начиная с релиза 0.9.2. -== Sinatra::Base - Подпрограммы, библиотеки и модульные приложения +== Sinatra::Base — "прослойки", библиотеки и модульные приложения Описание своего приложения самым простейшим способом (с помощью DSL верхнего уровня, как в примерах выше) -работает отлично для крохотных приложений, но имеет множество недостатков, когда надо -создать компоненты, такие как Rack -middleware, Rails metal, простые библиотеки с серверными компонентами, -Sinatra расширения. +работает отлично для крохотных приложений, но имеет множество недостатков, когда надо создать компоненты, такие как +Rack middleware ("прослойки"), Rails metal, простые библиотеки с серверными компонентами, +расширения Sinatra. DSL верхнего уровня загрязняет пространство имен Object и подразумевает стиль конфигурации микро-приложения (например, единый файл приложения, ./public и ./views директории, создание логов, страницу деталей об исключениях @@ -855,13 +980,6 @@ DSL верхнего уровня загрязняет пространство end end -MyApp класс является независимым Rack компонентом, который может исполнять роли -Rack подпрограммы, Rack приложения, Rails metal. Вы можете +use+ (использовать) или -+run+ (запустить) этот класс из rackup файла +config.ru+; или контролировать серверную -часть из библиотеки: - - MyApp.run! :host => 'localhost', :port => 9090 - Методы, доступные Sinatra::Base сабклассам идентичны тем, что доступны в DSL верхнего уровня. Большинство приложений верхнего уровня могут быть конвертированы в Sinatra::Base компоненты с помощью двух модификаций: @@ -874,10 +992,68 @@ Rack подпрограммы, Rack приложения, Rails metal. Вы мо Смотрите {Опции и Конфигурация}[http://www.sinatrarb.com/configuration.html] для детальной информации об опциях и их поведении. -=== Использование Sinatra как подпрограммы +=== Запуск модульных приложений -Не только сама Sinatra может использовать подпрограммы Rack, любое Sinatra приложение -само может быть добавлено к любому Rack эндпоинту в качестве подпрограммы. Этим эндпоинтом +Есть два общепринятых способа запускать модульные приложения: запуск напрямую с помощью run!: + + # my_app.rb + require 'sinatra/base' + + class MyApp < Sinatra::Base + # ... здесь код приложения ... + + # запускаем сервер, если исполняется текущий файл + run! if app_file == $0 + end + +И запускаем с помощью: + + ruby my_app.rb + +Или с помощью конфигурационного файла config.ru, который позволяет использовать любой +Rack-совместимый сервер приложений. + + # config.ru + require 'my_app' + run MyApp + +Запускаем: + + rackup -p 4567 + +=== Запуск "классических" приложений с config.ru + +Файл приложения: + + # app.rb + require 'sinatra' + + get '/' do + 'Hello world!' + end + +И соответствующий config.ru: + + require 'app' + run Sinatra::Application + +=== Когда использовать config.ru? + +Вот несколько причин, по которым вы, возможно, захотите использовать config.ru: + +* вы хотите разворачивать свое приложение на различных Rack-совместимых серверах (Passenger, Unicorn, + Heroku, ...). +* вы хотите использовать более одного сабкласса Sinatra::Base. +* вы хотите использовать Sinatra только в качестве "прослойки" Rack. + +Совсем необязательно переходить на использование config.ru лишь потому, что вы стали +использовать модульный стиль приложения. И необязательно использовать модульный стиль, чтобы +запускать приложение с помощью config.ru. + +=== Использование Sinatra в качестве "прослойки" + +Не только сама Sinatra может использовать "прослойки" Rack, но и любое Sinatra приложение +само может быть добавлено к любому Rack эндпоинту в качестве "прослойки". Этим эндпоинтом может быть другое Sinatra приложение, или приложение, основанное на Rack (Rails/Ramaze/Camping/...). require 'sinatra/base' @@ -897,7 +1073,7 @@ Rack подпрограммы, Rack приложения, Rails metal. Вы мо end class MyApp < Sinatra::Base - # подпрограмма будет запущена перед фильтрами + # "прослойка" будет запущена перед фильтрами use LoginScreen before do @@ -1014,31 +1190,69 @@ Sinatra приложения могут быть запущены напряму == На острие -Если вы хотите использовать новейший код Sinatra, то создайте локальный -клон и запускайте свое приложение с sinatra/lib директорией -в LOAD_PATH: +Если вы хотите использовать самый последний код Sinatra, не бойтесь запускать +свое приложение вместе с master бранчем Sinatra, он весьма стабилен. + +Мы также время от времени выпускаем предварительные версии, так что вы можете делать так: + + gem install sinatra --pre + +Чтобы воспользоваться некоторыми самыми последними возможностям. + +=== С помощью Bundler + +Если вы хотите запускать свое приложение с последней версией Sinatra, то +рекомендуем использовать {Bundler}[http://gembundler.com/]. + +Сначала установите Bundler, если у вас его еще нет: + + gem install bundler + +Затем создайте файл +Gemfile+ в директории вашего проекта: + + source :rubygems + gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git" + + # другие зависимости + gem 'haml' # например, если используете haml + gem 'activerecord', '~> 3.0' # может быть, вам нужен и ActiveRecord 3.x + +Обратите внимание, вам нужно будет указывать все зависимости вашего приложения +в этом файле. Однако, непосредственные зависимости Sinatra (Rack и Tilt) Bundler +автоматически скачает и добавит. + +Теперь вы можете запускать свое приложение примерно так: + + bundle exec ruby myapp.rb + +=== Вручную + +Создайте локальный клон репозитория и запускайте свое приложение с sinatra/lib +директорией в LOAD_PATH: cd myapp git clone git://github.com/sinatra/sinatra.git ruby -Isinatra/lib myapp.rb -Также вы можете добавить sinatra/lib директорию в -LOAD_PATH приложения: - - $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib' - require 'rubygems' - require 'sinatra' - - get '/about' do - "I'm running version " + Sinatra::VERSION - end - Чтобы обновить исходники Sinatra: - cd myproject/sinatra + cd myapp/sinatra git pull -== Больше информации +=== Установка глобально + +Вы можете самостоятельно собрать gem: + + git clone git://github.com/sinatra/sinatra.git + cd sinatra + rake sinatra.gemspec + rake install + +Если вы устанавливаете пакеты (gem) от пользователя root, то вашим последним шагом должна быть команда + + sudo rake install + +== Дальнейшее чтение * {Вебсайт проекта}[http://www.sinatrarb.com/] - Дополнительная документация, новости и ссылки на другие ресурсы.