module ActionController::MimeResponds

# File actionpack/lib/action_controller/metal/mime_responds.rb, line 211
def respond_to(*mimes)
  raise ArgumentError, "respond_to takes either types or a block, never both" if mimes.any? && block_given?

  collector = Collector.new(mimes, request.variant)
  yield collector if block_given?

  if format = collector.negotiate_format(request)
    if media_type && media_type != format
      raise ActionController::RespondToMismatchError
    end
    _process_format(format)
    _set_rendered_content_type(format) unless collector.any_response?
    response = collector.response
    response.call if response
  else
    raise ActionController::UnknownFormat
  end
end

Без поддержки веб-сервисов действие, собирающее данные для отображения списка людей, могло бы выглядеть примерно так:

def index
  @people = Person.all
end

Такое действие неявно поддерживает все форматы, но форматы также можно перечислить явно:

def index
  @people = Person.all
  respond_to :html, :js
end

Вот то же действие со встроенной поддержкой веб-сервисов:

def index
  @people = Person.all

  respond_to do |format|
    format.html
    format.js
    format.xml { render xml: @people }
  end
end

Это означает: «если клиент хочет получить в ответ на это действие HTML или JS, ответьте так же, как раньше, а если клиент хочет XML, верните ему список людей в формате XML». (Rails определяет желаемый формат ответа по заголовку HTTP Accept, отправленному клиентом.)

Допустим, у вас есть действие, добавляющее нового человека и при необходимости создающее его компанию (по названию), если она ещё не существует. Без веб-сервисов оно могло бы выглядеть так:

def create
  @company = Company.find_or_create_by(name: params[:company][:name])
  @person  = @company.people.create(params[:person])

  redirect_to(person_list_url)
end

Вот то же действие со встроенной поддержкой веб-сервисов:

def create
  company  = params[:person].delete(:company)
  @company = Company.find_or_create_by(name: company[:name])
  @person  = @company.people.create(params[:person])

  respond_to do |format|
    format.html { redirect_to(person_list_url) }
    format.js
    format.xml  { render xml: @person.to_xml(include: @company) }
  end
end

Если клиенту нужен HTML, мы просто перенаправляем его обратно к списку людей. Если ему нужен JavaScript, это Ajax-запрос, и мы рендерим шаблон JavaScript, связанный с этим действием. Наконец, если клиенту нужен XML, мы рендерим созданного человека в формате XML, но с одним отличием: в полученный XML также включается компания этого человека, поэтому результат будет выглядеть примерно так:

<person>
  <id>...</id>
  ...
  <company>
    <id>...</id>
    <name>...</name>
    ...
  </company>
</person>

Обратите внимание, однако, на дополнительный фрагмент в начале этого действия:

company  = params[:person].delete(:company)
@company = Company.find_or_create_by(name: company[:name])

Это нужно потому, что входящий XML-документ (если обрабатывается запрос веб-сервиса) может содержать только один корневой узел. Поэтому необходимо изменить структуру запроса так, чтобы он выглядел следующим образом (в кодировке URL):

person[name]=...&person[company][name]=...&...

И вот так (в кодировке XML):

<person>
  <name>...</name>
  <company>
    <name>...</name>
  </company>
</person>

Другими словами, мы формируем запрос так, чтобы он обрабатывал данные одного человека. Затем в действии извлекаем из запроса данные компании, находим или создаём компанию и после этого создаём нового человека, используя оставшиеся данные.

Обратите внимание: вы можете определить собственный анализатор параметров XML, который позволит описывать несколько сущностей в одном запросе (то есть заключать их все в один корневой узел), но если вы последуете общепринятому подходу и оставите настройки Rails по умолчанию, работать будет гораздо проще.

Если вам нужно использовать тип MIME, который по умолчанию не поддерживается, можно зарегистрировать собственные обработчики в config/initializers/mime_types.rb следующим образом.

Mime::Type.register "image/jpeg", :jpg

respond_to также позволяет задать общий блок для разных форматов с помощью any:

def index
  @people = Person.all

  respond_to do |format|
    format.html
    format.any(:xml, :json) { render request.format.to_sym => @people }
  end
end

В примере выше, если формат — xml, будет отрендерено:

render xml: @people

А если формат — json:

render json: @people

any также можно использовать без аргументов — в этом случае он будет применяться к любому формату, запрошенному пользователем:

respond_to do |format|
  format.html
  format.any { redirect_to support_path }
end

У форматов могут быть разные варианты.

Вариант запроса — это специализация формата запроса, например :tablet, :phone или :desktop.

Часто нужно рендерить разные шаблоны html/json/xml для телефонов, планшетов и браузеров на компьютерах. Варианты позволяют легко это сделать.

Задать вариант можно в before_action:

request.variant = :tablet if /iPad/.match?(request.user_agent)

Обрабатывайте варианты в действии так же, как форматы:

respond_to do |format|
  format.html do |variant|
    variant.tablet # renders app/views/projects/show.html+tablet.erb
    variant.phone { extra_setup; render ... }
    variant.none  { special_setup } # executed only if there is no variant set
  end
end

Создайте отдельные шаблоны для каждого формата и варианта:

app/views/projects/show.html.erb
app/views/projects/show.html+tablet.erb
app/views/projects/show.html+phone.erb

Если вы не используете общий код для разных форматов, определять варианты можно проще — с помощью встроенного синтаксиса:

respond_to do |format|
  format.js         { render "trash" }
  format.html.phone { redirect_to progress_path }
  format.html.none  { render "trash" }
end

Для вариантов также поддерживается общий блок any/all, используемый форматами.

Это работает как со встроенным синтаксисом:

respond_to do |format|
  format.html.any   { render html: "any"   }
  format.html.phone { render html: "phone" }
end

так и с блочным синтаксисом:

respond_to do |format|
  format.html do |variant|
    variant.any(:tablet, :phablet){ render html: "any" }
    variant.phone { render html: "phone" }
  end
end

Также можно задать массив вариантов:

request.variant = [:tablet, :phone]

Это работает аналогично согласованию форматов и типов MIME. Если вариант :tablet не объявлен, будет использоваться вариант :phone:

respond_to do |format|
  format.html.none
  format.html.phone # this gets rendered
end