The Section Architecture

Umlaut has what could be considered a 'domain specific language' for describing the display individual sections of content on the resolve menu page. These sections often correspond to a ServiceTypeValue, like "fulltext". But sometimes may include multiple ServiceTypeValues (eg related_items section includes cited_by and similar_items), or no ServiceTypeValue at all (eg section to display a COinS).

A description of a section is simply a hash with certain conventional keys describing various aspects of the contents and display of that section. These hashes are listed in the resolve_sections application configuration variable, initialized in the resolve_views.rb initializer, and customized or over-ridden in the local resolve_views.rb initializer.

One benefit of describing a section through configuration is that section display can often by changed at configure time without requiring a code time. Another is that the description of the section can be used not only to generate the initial HTML page; but also by the javascript that update the sections with new background content as available; and by the partial_html_sections api that delivers HTML fragments for sections in an XML or JSON container.

A description of a section is simply a hash, suitable for passing to SectionRenderer.new, detailed below. Plus some additional variables specifying where to display the section, documented in the resolve_views.rb initializer.

The SectionRenderer

A SectionRenderer object provides logic for displaying a specific section on the Umlaut resolve menu page. It is initialized with a hash describing the details -- or significantly, with simply a pointer to such a hash already existing in the resolve_sections config variable.

A SectionRenderer is typically created by the ResolveHelper#render_section method, which then passes the SectionRender object to the _section_display.erb.html that does the actual rendering, using the SectionRenderer for logic and hashes to pass to render calls in the partial.

Creating a new SectionRenderer from a config'ed section.

A SectionRender can simply be passed an id matching a section defined in config, it will then look up it's actual arguments from the config. For example:

[SectionRenderer.new(:id => "holding")]
   looks up actual initialization params from the hash in the config
   resolve_sections list that has a :div_id => "holding".

This can be used with ResolveHelper#render_section if you want to display a section with a known div_id, simply:

render_section( :id => "holding")

Section Options

Section options are typically configured in hashes in the application config variable resolve_sections, which is expected to be a list of hashes. That hash is suitable to be passed to a SectionRenderer.new() as configuration options for the section. The various ways these options can be used is documented below.

Simplest Case, Defaults

As is common in ruby, SectionRenderer will make a lot of conventional assumptions, allowing you to be very concise for the basic simple case:

{ :div_id => "fulltext" }

This means that:

• this section is assumed to be contained within a <div id="fulltext">. The div won't be automatically rendered, it's the containing pages responsibility to put in a div with this id.

• this section is assumed to contain responses of type ServiceTypeValue

• The section will be displayed with stock heading block including a title constructed from the display_name of ServiceTypeValue, or in general the display_name of the first ServiceTypeValue included in this section.

• The section will include a stock 'spinner' if there are potential background results being gathered for the ServiceTypeValue(s) contained.

• The actual ServiceResponses collected for the ServiceTypeValue included will be rendered with a _standard_response_item partial, using render :collection.

• The section will be displayed whether or not there are any actual responses included. If there are no responses, a message will be displayed to that effect.

The display of a section can be customized via configuration parameters to a large degree, including supplying your own partial to take over almost all display of the section.

Customizing ServiceTypeValues

You can specifically supply the ServiceTypeValues contained in this section, to a different type than would be guessed from the div_id:

{:div_id => "my_area", :service_type_values => ["fulltext"]}

Or specify multiple types included in one section:

{:div_id => "related_items", :service_type_values => ['cited_by', 'similar]}

Or a section that isn't used for displaying service responses at all, and has no service type:

{:div_id => "coins", :partial => "coins", :service_type_values => []}

Note that a custom partial needs to be supplied if there are no service_type_values supplied.

Customizing heading display

You can supply a title for the section that's different than what would be guessed from it's ServiceTypeValues. You can also supply a prompt.

{:div_id =>"excerpts", :section_title=>"Lots of good stuff", :section_prompt => "Limited previes and excerpts."}

You can also suppress display of the stock section heading at all:

{:show_heading => false, ...}

This may be becuase you don't want a heading, or because you are supplying a custom partial that will take care of the heading in a custom way.

Customizing spinner display

You can also suppress display of the stock spinner, because you don't want a spinner, or because your custom partial will be taking care of it.

{:show_spinner => false, ...}

By default, the spinner displays what type of thing it's waiting on, guessing from the ServiceTypeValue configured. If you want to specify this item name:

{:item_name_plural => "Related Items", ...}

Customizing visibility of section

By default, a section will simply be displayed regardless of whether there are any actual responses to display. However, the 'visibility' argument can be used to customize this in many ways. visibilty:

true

Default, always show section.

false

Never show section. (Not sure why you'd want this).

:any_services

Show section if and only if there are any configured services that generate the ServiceTypeValues included in this section, regardless of whether in this case they have or not.

:in_progress

Show the section if responses exist, OR if any services are currently in progress that are capable of generating responses of the right type for this section.

:responses_exist

Show the section if and only if some responses have actually been generated of the types contained in this section.

:complete_with_responses

Show the section only if there are responses generated, AND all services supplying responses of the type contained in section have completed, no more responses are possible.

(lambda object)

Most flexibly of all, you can supply your own lambda supplying custom logic to determine whether to show the section, based on current context. The lambda will be passed the SectionRenderer object as an argument, providing access to the Umlaut Request with context. eg:

:visibility => lambda do |renderer|
                         renderer.request.something == something
               end

List with limit

You can have the section automatically use the ResolveHelper#list_with_limit helper to limit the number of items initially displayed, with the rest behind a 'more' expand/contract widget.

{ :div_id => "highlighted_link",
  :list_visible_limit => 1,
  :visibility => :in_progress, ... }

Custom partial display

By default, the SectionRenderer assumes that all the ServiceResposnes included are capable of being displayed by the standard_item_response, and displays them simply by render standard_item_response with a :colection. Sometimes this assumption isn't true, or you want custom display for other reasons. You can supply your own partial that the renderer will use to display the content.

{ :div_id => "my_div", :partial => "my_partial", ... }

The partial so supplied should live in resolve/_my_partial.html.erb

When this partial is called, it will have local variables set to give it the data it needs in order to create a display:

responses_by_type

a hash keyed by ServiceTypeValue name, with the the value being an array of the respective ServiceType objects.

responses

a flattened list of all ServiceTypes included in this section, of varying ServiceTypeValues. Most useful when the section only includes one ServiceTypeValue

renderer

The SectionRenderer object itself, from which the current umlaut request can be obtained, among other things.

You can supply additional static local arguments to the partial in the SectionRenderer setup:

{:div_id=> "foo", :partial=>"my_partial", :partial_locals => {:mode => "big"}, ... }

the :partial_locals argument can be used with the standard_response_item too:

{:div_id => "highlighted_link", :partial_locals => {:show_source => true}}

Note that your custom partial will still be displayed with stock header and possibly spinner surrounding it. You can suppress these elements:

{:div_id => "cover_image", :partial => "cover_image", :show_heading => false, :show_spinner => false}

But even so, some 'wrapping' html is rendered surrounding your partial. If you want to disable even this, becuase your partial will take care of it itself, you can do so with :show_partial_only => true

{:div_id => "search_inside", :partial => "search_inside", :show_partial_only => true}