diff --git a/app/views/layouts/body/_languages.html.erb b/app/views/layouts/body/_languages.html.erb
index 9e142e96..d66308c5 100644
--- a/app/views/layouts/body/_languages.html.erb
+++ b/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[/\|/] %>
- <% 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 %>
<% end %>
diff --git a/app/views/layouts/body/_title.html.erb b/app/views/layouts/body/_title.html.erb
index dca438c0..5d03fd23 100644
--- a/app/views/layouts/body/_title.html.erb
+++ b/app/views/layouts/body/_title.html.erb
@@ -2,10 +2,14 @@
<%= link_to home_path do %>
<% if I18n.exists?("general.project_name", locale) %>
- <%= t "general.project_name" %>
+
+ <%= t "general.project_name", default: "Add project name to locale file" %>
+
<% end %>
<% if I18n.exists?("general.project_subtitle", locale) %>
- <%= t "general.project_subtitle" %>
+
+ <%= t "general.project_subtitle", default: "Add project subtitle to locale file" %>
+
<% end %>
<% end %>
diff --git a/app/views/layouts/head/_analytics.html.erb b/app/views/layouts/head/_analytics.html.erb
new file mode 100644
index 00000000..8fef2747
--- /dev/null
+++ b/app/views/layouts/head/_analytics.html.erb
@@ -0,0 +1 @@
+<%# override this file to add your own analytics code %>
diff --git a/app/views/layouts/head/_head.html.erb b/app/views/layouts/head/_head.html.erb
index 8a05e7ac..04e0f250 100644
--- a/app/views/layouts/head/_head.html.erb
+++ b/app/views/layouts/head/_head.html.erb
@@ -4,6 +4,8 @@
<%= t "general.project_shortname" %>
<%= 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") %>
diff --git a/app/views/layouts/head/_language.html.erb b/app/views/layouts/head/_language.html.erb
new file mode 100644
index 00000000..7922ff32
--- /dev/null
+++ b/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 %>
+
+ <% end %>
+<% end %>
diff --git a/app/views/layouts/head/_meta.html.erb b/app/views/layouts/head/_meta.html.erb
index a85390ec..03db2bcf 100644
--- a/app/views/layouts/head/_meta.html.erb
+++ b/app/views/layouts/head/_meta.html.erb
@@ -9,14 +9,3 @@
<%= 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 %>
-
- <% end %>
-<% end %>
diff --git a/config/locales/en.yml b/config/locales/en.yml
index 8fbd4001..3dca5c46 100644
--- a/config/locales/en.yml
+++ b/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
diff --git a/config/locales/languages.yml b/config/locales/languages.yml
new file mode 100644
index 00000000..268cdd7e
--- /dev/null
+++ b/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
diff --git a/docs/README.md b/docs/README.md
index e45b4d71..72330116 100644
--- a/docs/README.md
+++ b/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
diff --git a/docs/api_requests.md b/docs/api_requests.md
new file mode 100644
index 00000000..d601c929
--- /dev/null
+++ b/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
+```
diff --git a/docs/languages.md b/docs/languages.md
index 0a19c3e3..adbe0f29 100644
--- a/docs/languages.md
+++ b/docs/languages.md
@@ -1,13 +1,20 @@
# Languages
By default, Orchid assumes you are developing an English-only application, but
-supports the use of multiple languages. The setup generator called with `rails
+supports the use of multiple languages. By default, only English and Spanish
+are supported out of the box, but you may configure any languages you require.
+
+The setup generator called with `rails
g(enerate) setup` will prompt for your default language and list of all
-languages you would like your application to use.
+languages you would like your application to use. Once generated, you may alter
+the existing Spanish and English text, or create translations for other
+languages.
- [Alter Existing Translations](#alter-existing-translations)
-- [Add More Translations](#add-more-translations)
+- [Additional Text](#additional-text)
- [Languages Other than English and Spanish](#languages-other-than-english-and-spanish)
+ - [Adding the Language Toggle](#adding-the-language-toggle)
+ - [Adding Translations](#adding-translations)
- [Facets](#translating-facets)
- [Views](#views)
- [Modify Languages After Creation](#modify-languages-after-creation)
@@ -21,16 +28,16 @@ Check out `/config/locales`. You should see yml files named by language
codes. You may edit these files to change strings as desired for things such as
your site title, home page text, etc.
-## Add More Translations
-
-When adding new views, you will need to make sure that all textual content is
-translatable to all the languages of your site.
+## Additional Test
-For shorter text or simple paragraphs, you may define your terms in a locale
-file and instruct Rails to look for it.
+When adding new views and features, you will need to make sure that all textual
+content is translatable to all the languages of your site. If you are adding a
+large amount of text, you will want to consider using multiple [views](#views)
+or partials, one for each language.
-You may add your new translations to the bottom of an existing file or create a
-new file in the `locales` directory.
+For shorter text and simple HTML, you use a locale file. Add your new
+translations to the bottom of an existing file or create a new file in the
+`locales` directory.
**All new files must start with the language key or Rails will not find the
appropriate text.** An example locales file might look like:
@@ -53,11 +60,50 @@ the app can't find a translation of the string.
## Languages Other than English and Spanish
-Most of the navigation, buttons, and general wording throughout Orchid has been
-pulled out into strings in `config/locales/en.yml` and `config/locales/es.yml`.
-Translate each entry of the YAML file into your needed language(s).
-You may toggle between languages in the application and view the
-language differences as you go.
+Orchid supports English and Spanish internationalization out of the box.
+However, in many cases, you may need to add other languages.
+
+### Adding the Language Toggle
+
+When multiple languages are supported, Orchid displays a toggle which allows
+users to select their preferred website language.
+
+If adding a language which is not English or Spanish, you will need
+to add the text of this toggle. Copy `config/locales/languages.yml` to that
+same location in your app. You will need to add your language's name to the
+`&langs` definition, and make it available to your language's locales configuration.
+
+For example, if you were adding Japanese, your
+`config/locales/languages.yml` file would be:
+
+```yaml
+langs: &langs
+ en: English
+ es: Español
+ ja: 日本語
+
+en:
+ languages:
+ <<: *langs
+
+es:
+ languages:
+ <<: *langs
+
+ja:
+ languages:
+ <<: *langs
+```
+
+### Adding Translations
+
+Most of the navigation, buttons, and general wording throughout Orchid have been
+pulled out into strings in `config/locales/[language].yml`.
+
+Locate the yaml file for the language you will be translating. If it does not
+yet exist, copy an existing `[language].yml` file.
+
+Translate each entry of the YAML file into the new language.
```yaml
# config/locales/af.yml
diff --git a/docs/overrides.md b/docs/overrides.md
index b2b2ad3c..392aab6a 100644
--- a/docs/overrides.md
+++ b/docs/overrides.md
@@ -7,6 +7,21 @@ This is not always a recommended workflow, however, as it duplicates a lot of
code and makes it more difficult to update your app. Below are some instructions
for common portions which may need to be overridden.
+- [Settings](#settings)
+- [Controllers](#controllers)
+ - [API Requests](#api-requests)
+- [Helpers](#helpers)
+- [Views and Assets](#views-and-assets)
+- [Routes](#routes)
+
+## Settings
+
+Options such as which filters appear on your search and browse page,
+number of results per page, the location of the image server, languages, and
+more are part of the application's configuration.
+
+Please refer to the [settings documentation](/docs/settings.md) for more information.
+
## Controllers
It is possible to override the behavior of specific actions within controllers.
@@ -34,6 +49,15 @@ scratch.
Be aware that any instance variables in the original Orchid action may still
be expected by the corresponding view.
+Customizing a section controller? Check out the
+[sections documentation](/docs/sections.md#controller).
+
+### API Requests
+
+When overriding a controller, you may find it useful to alter the API request.
+Please see the documentation for [API Requests](/docs/api_requests.md) for
+more information.
+
## Helpers
To override Orchid helper behavior, check out the structure in `app/helpers`.
diff --git a/docs/sections.md b/docs/sections.md
index 5b01efc7..0c8e159f 100644
--- a/docs/sections.md
+++ b/docs/sections.md
@@ -10,6 +10,7 @@ feature a specific musician and only searches their documents. Orchid is on it!
- [Config](#config)
- [Routes](#routes)
+- [Controller](#controller)
- [Canonical Links](#canonical-links)
- [Links](#links)
- [Templates](#templates)
@@ -106,6 +107,23 @@ scope '/writings/letters', defaults: { section: "letters" } do
end
```
+## Controller
+
+When creating your own section, you are not required to add a new controller,
+as all of the sections are powered by the ItemsController class out of the box.
+
+However, you may find it helpful to add a controller if you have custom actions
+or views. In order to still have access to controller methods and view helpers,
+you will need to set up your controller to inherit the ItemsController:
+
+```ruby
+class InthenewseventsController < ItemsController
+end
+```
+
+This means you may still use instance variables such as `@items_api` when
+creating custom queries.
+
## Canonical Item Links
If one uses a section which segregates items but they are still included by the
diff --git a/lib/generators/setup_generator.rb b/lib/generators/setup_generator.rb
index e247241c..137b9ab1 100755
--- a/lib/generators/setup_generator.rb
+++ b/lib/generators/setup_generator.rb
@@ -85,12 +85,12 @@ def copy_configs_and_locales
lang_default = prompt_for_value("Primary Language", "en")
config_set("public", "language_default", lang_default)
- langs = prompt_for_value("All Languages (separated with a pipe: en|es|cz)",
+ langs = prompt_for_value("All languages, including primary (separated with a pipe: en|es|cz)",
"en")
- config_set("public", "ALL_LANGUAGES", langs)
+ config_set("public", "languages", langs)
- langs = [] if langs.blank?
- Array(langs).each do |lang|
+ all_langs = langs.blank? ? [] : langs.split("|")
+ all_langs.each do |lang|
# for each language which is not english, create a locale file
next if lang == "en"
copy_locale(lang)
diff --git a/lib/orchid/version.rb b/lib/orchid/version.rb
index 8d5f8598..0d67baed 100644
--- a/lib/orchid/version.rb
+++ b/lib/orchid/version.rb
@@ -1,3 +1,3 @@
module Orchid
- VERSION = '3.1.0'
+ VERSION = '3.1.1'
end