Merge pull request #216 from CDRH/dev

v3.1.1

CHANGELOG.md

@@ -25,6 +25,28 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 ### Contributors
 -->
 
+## [v3.1.1](https://github.com/CDRH/orchid/compare/v3.1.0...v3.1.1) - splitting templates, fixing languages
+
+### Fixed
+- bug with locales yaml creation
+
+### Added
+- partials for browse, browse_facet, index, and search_preset header content for easier overriding
+- displays language toggle options in respective languages, therefore English instead of en, Español instead of es, etc
+- helper method `language_toggle_link` moves logic for language links out of view
+- documentation for api connection and controller inheritance
+- adds partials for easier overriding:
+  - `browse_header`
+  - `browse_facet_header`
+  - `index_header`
+  - `search_preset_header`
+  - `analytics` (head)
+  - `language` (head)
+
+### Changed
+- `ALL_LANGUAGES` setting changed back to `languages`
+- language documentation clarified and expanded
+
 ## [v3.1.0](https://github.com/CDRH/orchid/compare/v3.0.3...v3.1.0) - search_preset, improved section links, and misc display
 
 ### Fixed

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    orchid (3.0.3)
+    orchid (3.1.1)
       rails (~> 5.2.0)
 
 GEM

app/helpers/orchid/application_helper.rb

@@ -157,6 +157,26 @@ def iiif(image,
     "#{server}/#{project}%2F#{image_esc}/#{iiif_opts}"
   end
 
+  # returns a link to switch site language preferences
+  def language_toggle_link(lang_code)
+    lang_name = t("languages.#{lang_code}", default: lang_code.upcase)
+
+    if lang_code == I18n.locale.to_s
+      # if this is the current site language, disable link
+      link_to lang_name, "#",
+        class: "btn btn-primary disabled",
+        hreflang: lang_code,
+        rel: "alternate",
+        tabindex: -1
+    else
+      link_to lang_name,
+        locale_link(lang_code),
+        class: "btn btn-default",
+        hreflang: lang_code,
+        rel: "alternate"
+    end
+  end
+
   def locale
     I18n.locale
   end

app/views/items/_browse_facet_header.html.erb

@@ -0,0 +1 @@
+<h1><%= t "browse.browse_type", default: "Browse by" %> <%= @browse_facet_info["label"] %></h1>

app/views/items/_browse_header.html.erb

@@ -0,0 +1,6 @@
+<h1><%= t "browse.title", default: "Browse" %></h1>
+
+<p>
+  <%= link_to t("browse.all_link", default: "All Items in the Collection"), prefix_path(route_path),
+        class: "btn btn-lg btn-default", rel: "search" %>
+</p>

app/views/items/_date_limit.html.erb

@@ -2,7 +2,7 @@
 <% class_in = date_selected ? "in" : "" %>
 <% class_glyphicon = date_selected ? "glyphicon-chevron-down" : "glyphicon-chevron-right" %>
 
-<div class="panel panel-default">
+<div class="panel panel-default panel-filter panel-filter-date">
   <div class="clearfix panel-heading" data-toggle="collapse"
        data-target="#dates" role="Option"
        aria-label="<%= t "search.dates.show_filters", default: "Show Date Filters" %>">

app/views/items/_facets.html.erb

@@ -11,7 +11,7 @@
       <% class_in =  start_open ? "in" : "" %>
       <% class_glyphicon = start_open ? "glyphicon-chevron-down" : "glyphicon-chevron-right" %>
 
-      <div class="panel panel-default">
+      <div class="panel panel-default panel-filter panel-filter-<%= info['label'].parameterize %>">
 
         <!-- panel heading -->
         <div class="clearfix panel-heading" data-toggle="collapse"

app/views/items/_index_header.html.erb

@@ -0,0 +1,5 @@
+<% if params["q"].blank? && params["f"].blank? %>
+  <h1><%= t "search.all_items", default: "All Items" %></h1>
+<% else %>
+  <h1><%= t "search.search_results", default: "Search Results" %></h1>
+<% end %>

app/views/items/_search_preset_header.html.erb

@@ -0,0 +1 @@
+<h1><%= @content_label || @title %></h1>

app/views/items/browse.html.erb

@@ -1,9 +1,4 @@
-<h1><% t "browse.title", default: "Browse" %></h1>
-
-<p>
-  <%= link_to t("browse.all_link", default: "All Items in the Archive"), prefix_path(route_path),
-        class: "btn btn-lg btn-default", rel: "search" %>
-</p>
+<%= render_overridable "items", "browse_header" %>
 
 <h3><%= t "browse.browse_type", default: "Browse by" %>:</h3>
 <% @page_facets.each_slice(3) do |slice| %>

app/views/items/browse_facet.html.erb

@@ -2,7 +2,7 @@
   - "sort_by" sort value (e.g. "count|desc")
 %>
 
-<h1><%= t "browse.browse_type", default: "Browse by" %> <%= @browse_facet_info["label"] %></h1>
+<%= render_overridable "items", "browse_facet_header" %>
 
 <nav>
   <ul class="nav nav-tabs buffer-bottom" role="tablist">

app/views/items/index.html.erb

@@ -1,8 +1,4 @@
-<% if params["q"].blank? && params["f"].blank? %>
-  <h1><%= t "search.all_items", default: "All Items" %></h1>
-<% else %>
-  <h1><%= t "search.search_results", default: "Search Results" %></h1>
-<% end %>
+<%= render_overridable("items", "index_header") %>
 
 <div class="search_form">
   <%= render_overridable("items", "search_box") %>

app/views/items/search_preset.html.erb

@@ -8,7 +8,8 @@ to docs/search_preset.md %>
   - @preset_class : OPTIONAL adds CSS class on <div>
 %>
 
-<h1><%= @content_label || @title %></h1>
+<%# title %>
+<%= render_overridable "items", "search_preset_header" %>
 
 <div class="row search_form search_preset search_preset_<%= @preset_class %>">
 

app/views/layouts/body/_languages.html.erb

@@ -1,16 +1,9 @@
-<% if APP_OPTS["languages"].present? && APP_OPTS["languages"][/\|/] %>
+<% langs = APP_OPTS["languages"] %>
+
+<% if langs.present? && langs[/\|/] %>
   <div class="language_link btn-group" role="group" aria-label="language choice">
-    <% APP_OPTS["languages"].split("|").each do |lang_code| %>
-      <%# create link to switch languages that keeps current parameters %>
-      <%# TODO a11y / ARIA markup for full language names? %>
-      <% if lang_code == I18n.locale.to_s %>
-        <%= link_to lang_code.upcase, "#", class: "btn btn-primary disabled",
-          hreflang: lang_code, rel: "alternate", tabindex: -1 %>
-      <% else %>
-        <%# a11y / ARIA markup for full language name? %>
-        <%= link_to lang_code.upcase, locale_link(lang_code),
-          class: "btn btn-default", hreflang: lang_code, rel: "alternate" %>
-      <% end %>
+    <% langs.split("|").each do |lang_code| %>
+      <%= language_toggle_link(lang_code) %>
     <% end %>
   </div>
 <% end %>

app/views/layouts/body/_title.html.erb

@@ -2,10 +2,14 @@
   <%= link_to home_path do %>
     <div class="h1">
       <% if I18n.exists?("general.project_name", locale) %>
-        <span class="site-title"><%= t "general.project_name" %></span>
+        <span class="site-title">
+          <%= t "general.project_name", default: "Add project name to locale file" %>
+        </span>
       <% end %>
       <% if I18n.exists?("general.project_subtitle", locale) %>
-        <small class="site-subtitle"><%= t "general.project_subtitle" %></small>
+        <small class="site-subtitle">
+          <%= t "general.project_subtitle", default: "Add project subtitle to locale file" %>
+        </small>
       <% end %>
     </div>
   <% end %>

app/views/layouts/head/_analytics.html.erb

@@ -0,0 +1 @@
+<%# override this file to add your own analytics code %>

app/views/layouts/head/_head.html.erb

@@ -4,6 +4,8 @@
     <%= t "general.project_shortname" %>
   </title>
   <%= render_overridable("layouts/head", "meta") %>
+  <%= render_overridable("layouts/head", "language") %>
+  <%= render_overridable("layouts/head", "analytics") %>
   <%= render_overridable("layouts/head", "favicon") %>
   <%= render_overridable("layouts/head", "fonts") %>
   <%= render_overridable("layouts/head", "stylesheets") %>

app/views/layouts/head/_language.html.erb

@@ -0,0 +1,10 @@
+<%# links for alternate language pages %>
+<% if APP_OPTS["languages"].present? && APP_OPTS["languages"][/\|/] %>
+  <% APP_OPTS["languages"].split("|").each do |lang_code| %>
+    <%# if this is the currently selected language
+        then no alternative link is needed for it %>
+    <% next if lang_code == I18n.locale.to_s %>
+    <link rel="alternate" hreflang="<%= lang_code %>"
+      href="<%= locale_link(lang_code) %>" />
+  <% end %>
+<% end %>

app/views/layouts/head/_meta.html.erb

@@ -9,14 +9,3 @@
 <meta charset="utf-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
 <%= csrf_meta_tags %>
-
-<%# links for alternate language pages %>
-<% if APP_OPTS["languages"].present? && APP_OPTS["languages"][/\|/] %>
-  <% APP_OPTS["languages"].split("|").each do |lang_code| %>
-    <%# if this is the currently selected language
-        then no alternative link is needed for it %>
-    <% next if lang_code == I18n.locale.to_s %>
-    <link rel="alternate" hreflang="<%= lang_code %>"
-      href="<%= locale_link(lang_code) %>" />
-  <% end %>
-<% end %>

config/locales/en.yml

@@ -67,7 +67,7 @@ en:
   ##########
   browse:
     # link to search all items
-    all_link: All Items in the Archive
+    all_link: All Items in the Collection
     # label for browsing filters
     browse_type: Browse by
     # how to display specific filters which have no label

config/locales/languages.yml

@@ -0,0 +1,18 @@
+# Below is a list of languages currently supported by Orchid
+#
+# If you want to add an additional language, you will need
+# to add it to your app's languages.yml file below in the
+# langs key, then include the langs in your language's key.
+
+
+langs: &langs
+  en: English
+  es: Español
+
+en:
+  languages:
+    <<: *langs
+
+es:
+  languages:
+    <<: *langs

docs/README.md

@@ -5,6 +5,7 @@
 - [Installation](/docs/installation.md) - dependencies and generator instructions
 - [Settings Overview and Basics](/docs/settings.md) - learn where and what you can change out of the box
 - [Helpful Helpers](/docs/helpers.md) - specific Orchid helpers
+- Testing - Run `rails test` from within the Orchid repository
 
 ## Theming and Customization
 

docs/api_requests.md

@@ -0,0 +1,85 @@
+# API Requests
+
+When you are [overridding default controllers](/docs/overrides.md) or adding
+new [sections](/docs/sections.md) and [search presets](/docs/search_preset.md),
+you may find yourself needing to create custom API requests.
+
+- [Accessing the Connection](#accessing-the-connection)
+- [Querying](#querying)
+  - [The Response](#the-response)
+  - [Querying by ID](#querying-by-id)
+
+## Accessing the Connection
+
+When you first start an Orchid app, it connects to the API endpoint specified
+in your `config/private.yml` file with default settings from `config/public.yml`.
+
+That Query object is stored with a global variable:
+
+```ruby
+$api
+```
+
+Typically, you will not need to work directly with `$api`. In the
+ItemsController, you are provided with an instance variable:
+
+```ruby
+@items_api
+```
+
+`@items_api` will return either `$api` or a section appropriate connection, if
+you are working with sections.
+
+The section API connection information is stored in `$api_sections`, although
+you should rarely need to use it directly.
+
+## Querying
+
+Orchid uses the CDRH API's syntax for requests. You should familiarize yourself
+with the [API documentation](https://github.com/CDRH/api) before writing custom
+requests.
+
+When you initialize your application, Orchid sets up default query parameters
+using your config file settings.
+
+This means that you do not need to specify things such as the number of items
+per page, starting sort, facets, and any default filters for new queries, since
+they are already built in as a convenience.
+
+However, you may override those defaults as desired when creating a new query.
+
+A typical query will look something like this:
+
+```ruby
+@items_api.query({ hash of options })
+```
+
+For example, the following would bring back results of Willa Cather's writing with the text "birthday":
+
+```ruby
+
+options = {
+  "f" => [ "category|Writings", "creator.name|Cather, Willa" ],
+  "q" => "birthday"
+}
+@items_api.query(options)
+```
+
+### The Response
+
+`.query` returns a Response object which has the following methods:
+
+- count : the number of items found
+- facets : a hash with facets + facet counts you requested
+- items : an array of the documents you requested
+- first : the first item
+- pages: the page count needed to display all the items
+
+### Querying by ID
+
+Although you could send a `.query({ identifier: "some.id" })` request and
+select the first item, orchid provides a helpful method to get a single item:
+
+```ruby
+@items_api.get_item_by_id("some.id").first
+```