Tutorial fixes for 8.0.0-alpha

README.md

@@ -2,6 +2,8 @@
 
 A Jekyll based site for tutorials on customizing Blacklight applications.
 
+Publishes to: <https://workshop.projectblacklight.org/>
+
 ## Authors
 
 **Jessie Keck**

_includes/previous_next.html

@@ -19,6 +19,9 @@
           <span class="pagination-item newer">Next</span>
         {% endif %}
       </div>
+      <div>
+        For a list of pages in the tutorial, click the menu icon on the upper left.
+      </div>
     {% else %}
       {% assign page_index = page_index | plus: 1 %}
     {% endif %}

v8.0.0.alpha/04-helper-method-overrides.md

@@ -6,7 +6,7 @@ redirect_from: /overrides/
 blacklight_version: v8.0.0.alpha
 ---
 
-Much of Blacklight is written in a way that is overridable, helper methods are no different.
+Much of Blacklight is written in a way that is overridable. Helper methods are no different.
 
 Let's take a look at the [module that is used to help with some of the layout for Blacklight](https://github.com/projectblacklight/blacklight/blob/master/app/helpers/blacklight/layout_helper_behavior.rb). This  module is mixed into the `Blacklight::BlacklightHelperBehavior` which allows us to override methods mixed in.
 
@@ -41,7 +41,7 @@ module CustomLayoutHelper
 end
 {% endhighlight %}
 
-Now we are free to override methods to meet our custom application needs. For example, lets override the `html_tag_attributes` method.
+Now we are free to override methods to meet our custom application needs. For example, let's override the `html_tag_attributes` method.
 
 {% highlight ruby %}
 # app/helpers/custom_layout_helper.rb
@@ -66,5 +66,5 @@ This overridden method adds an additional attribute `dir="rtl"` to display our p
 This is just one way that the Blacklight code can be overridden and customized. Similar patterns can be used to customize controllers and search behavior.
 
 <div class="alert alert-primary">
-  For more information about overriding helpers, <a href="https://github.com/projectblacklight/blacklight/wiki/Configuring-and-Customizing-Blacklight#custom-view-helpers">checkout the Blacklight Wiki</a>.
+  For more information about overriding helpers, <a href="https://github.com/projectblacklight/blacklight/wiki/Configuring-and-Customizing-Blacklight#custom-view-helpers">check out the Blacklight Wiki</a>.
 </div>

v8.0.0.alpha/09-general-configuration-patterns.md

@@ -14,6 +14,7 @@ The keys provided to many fields are intended to point either to a field in solr
 The following example will configure a facet with the field name `language_ssim` based on the key that was passed in.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_facet_field 'language_ssim'
 end
@@ -24,6 +25,7 @@ end
 It's typical, but not required, that the Blacklight field key matches the solr field name.  This is the case in the example above.  However, you can also configure a field to use a different solr field name, which is useful if you want to use the same field with different display characteristics, or if you want to keep Solr internals out of your URLs:
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_facet_field 'language', field: 'language_facet_ssim'
 end
@@ -33,6 +35,7 @@ end
 There are a few ways to add labels to fields (as you'll notice if you're following along the example above got a default label), but one of the ways is to add a label key direction. Many of the configurations Blacklight provides take a label option.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_facet_field 'language_ssim', label: 'Language'
 end
@@ -44,6 +47,7 @@ You can control the display of elements by passing values to `if` and `unless`.
 
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_facet_field 'language_ssim', label: 'Language', if: false
 end
@@ -56,6 +60,7 @@ You can also control display using the `if`/`unless` configurations by passing a
 In the example below, the language facet will only be displayed when a format of "Book" has been selected in the facets.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_facet_field 'language_ssim', label: 'Language', if: -> (controller, _config, _field) do
     selected_formats = controller.params.dig('f', 'format') || []
@@ -66,5 +71,5 @@ end
 ```
 
 <div class="alert alert-primary">
-  For more information about configuring Blacklight, <a href="https://github.com/projectblacklight/blacklight/wiki/Configuring-and-Customizing-Blacklight#configuration">checkout the Blacklight Wiki</a>.
+  For more information about configuring Blacklight, <a href="https://github.com/projectblacklight/blacklight/wiki/Configuring-and-Customizing-Blacklight#configuration">check out the Blacklight Wiki</a>.
 </div>

v8.0.0.alpha/10-metadata-fields.md

@@ -8,6 +8,7 @@ blacklight_version: v8.0.0.alpha
 The metadata fields that are displayed in the index (search results) and show (record view) can be configured using the `add_index_field` and `add_show_field` configuration methods in the Blacklight config.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   # Index / Search Results
   config.add_index_field 'author_tsim', label: 'Author'
@@ -21,7 +22,7 @@ The configuration patterns outlined on [General Configuration Patterns](/v8.0.0.
 
 ## Labeling via Internationalization (i18n)
 
-All the text in Blacklight's UI are configured via rails' i18n files. While you can apply a string label directly in the Blackklight config, you can also label these in your i18n config files (e.g. in `config/locales/blacklight.en.yml`).
+All the text in Blacklight's UI are configured via rails' i18n files. While you can apply a string label directly in the Blacklight config, you can also label these in your i18n config files (e.g. in `config/locales/blacklight.en.yml`).
 
 If you wanted to change the label of all `author_tsim` fields to "Creator" you can do that by adding the label to your locale file.
 
@@ -55,6 +56,7 @@ There are a few configuration options that can help you format the data using Bl
 One common customization is to update the way that Blacklight joins multiple values by default. Blacklight's rendering pipeline uses rails' [`to_sentence`](https://apidock.com/rails/Array/to_sentence) helper (with its default options) to join multiple solr field values together, and allows you to pass in alternate options using the `separator_options` configuration option.  For instance, if we wanted to separate all values by line breaks instead of the `,`s and `and` we can do that with the following configuration (the record with ID 92117465 is a good example of this in action).
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   # This field configuration would need to be added as it is not in the generated controller
   config.add_show_field 'author_addl_tsim', label: 'Additional authors', separator_options: {
@@ -68,6 +70,7 @@ end
 It's also possible to link these values using the built-in `link_to_facet` configuration option. Two of the show fields that it might make sense to do this with (and are indexed appropriately for faceting) are the format and language fields on the show view.
 
 ```diff
+# app/controllers/catalog_controller.rb
 - config.add_show_field 'format', label: 'Format'
 - config.add_show_field 'language_ssim', label: 'Language'
 + config.add_show_field 'format', label: 'Format', link_to_facet: true
@@ -85,6 +88,7 @@ The field values can also be mapped using field configuration. There are two eas
 Accessors are handy when the transformation you want to make is based entirely on the data from the field (or document). One thing you might do is map names given as "last name, first name" into "first name last name" [^1]. The most basic accessor configuration is using the explicit accessor configuration:
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   # Index / Search Results
   config.add_index_field 'author_tsim', label: 'Author', accessor: :author_name
@@ -120,6 +124,7 @@ end
 Alternatively, you can use the `values` parameter to provide document values [^2]. This is a good choice if the value varies based on the request (e.g. the values are internationalized using the user's profile, or an administrator sees additional data, etc):
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   # Index / Search Results
   config.add_index_field 'JSON', label: 'Solr Document', values: ->(field_config, document, _) {
@@ -133,6 +138,7 @@ end
 The field values can also be rendered using a custom viewcomponent. This is a good choice if you want to render a field value in a more complex way than the default rendering pipeline. With a custom view component, you can render the field value in any way you want.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 config.add_show_field 'JSON', label: 'Solr Document', component: DetailsComponent
 ```
 

v8.0.0.alpha/11-facet-fields.md

@@ -10,6 +10,7 @@ Blacklight provides facets to help a user filter search results.
 Facet fields can be configured using the `add_facet_field` configuration method:
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_facet_field 'format', label: 'Format'
 end
@@ -20,6 +21,7 @@ Solr calculates the number of hits for each format value. Blacklight displays th
 If there are many facet values, you can use `limit` to control how many appear on the search results page.
 
 ```diff
+# app/controllers/catalog_controller.rb
 - config.add_facet_field 'subject_ssim', label: 'Topic'
 + config.add_facet_field 'subject_ssim', label: 'Topic', limit: 5
 ```
@@ -28,19 +30,22 @@ Additional facet values are available in a modal popup.
 
 You can control whether the facet is displayed expanded by default:
 ```diff
+# app/controllers/catalog_controller.rb
 - config.add_facet_field 'format', label: 'Format'
 + config.add_facet_field 'format', label: 'Format', collapse: false
 ```
 
 You can also sort the values alphabetically [^1]:
 ```diff
+# app/controllers/catalog_controller.rb
 - config.add_facet_field 'format', label: 'Format', collapse: false
 + config.add_facet_field 'format', label: 'Format', collapse: false, sort: 'alpha', limit: -1
 ```
 
 If the facet data is mutually exclusive, you might consider using `single` to allow the user to toggle between values easily:
 
 ```diff
+# app/controllers/catalog_controller.rb
 - config.add_facet_field 'pub_date_ssim', label: 'Publication Year'
 + config.add_facet_field 'pub_date_ssim', label: 'Publication Year', single: true
 ```
@@ -51,6 +56,7 @@ If the facet data is mutually exclusive, you might consider using `single` to al
 Blacklight also has built-in support for other types of Solr faceting. Query facets are good for providing facets based on dynamic data not directly present in the index. You can specify the "values" of a query facet and the applicable Solr query using the `query` parameter:
 
 ```ruby
+# app/controllers/catalog_controller.rb
 config.add_facet_field 'example_query_facet_field', label: 'Publish Date', query: {
    years_5: { label: 'within 5 Years', fq: "pub_date_ssim:[#{Time.zone.now.year - 5 } TO *]" },
    years_10: { label: 'within 10 Years', fq: "pub_date_ssim:[#{Time.zone.now.year - 10 } TO *]" },
@@ -106,21 +112,30 @@ For this example, we want to customize the display of the facet, so we'll need t
 
 ```erb
 <%= render(@layout.new(facet_field: @facet_field)) do |component| %>
-  <% component.with(:label) do %>
+  <% component.with_label do %>
     <%= @facet_field.label %>
   <% end %>
-  <% component.with(:body) do %>
+  <% component.with_body do %>
+    <%= helpers.render(Blacklight::FacetFieldInclusiveConstraintComponent.new(facet_field: @facet_field)) %>
     <ul class="facet-values list-unstyled">
-      <%= render_facet_limit_list @facet_field.paginator, @facet_field.key %>
+      <%= render facet_items %>
     </ul>
+    <%# backwards compatibility, ugh %>
+    <% if @layout == Blacklight::FacetFieldNoLayoutComponent && !@facet_field.in_modal? && @facet_field.modal_path %>
+      <div class="more_facets">
+        <%= link_to t("more_#{@facet_field.key}_html", scope: 'blacklight.search.facets', default: :more_html, field_name: @facet_field.label),
+          @facet_field.modal_path,
+          data: { blacklight_modal: 'trigger' } %>
+      </div>
+    <% end %>
   <% end %>
 <% end %>
 ```
 
-and then make a nice visible change:
+and then make a nice visible change (the label disappears):
 
 ```diff
-<% component.with(:label) do %>
+  <% component.with_label do %>
 -   <%= @facet_field.label %>
 +   -> <%= @facet_field.label %> <-
 <% end %>
@@ -137,6 +152,7 @@ Blacklight uses the `Blacklight::SearchState` to map a user's query parameters t
 Here, we'll map the language field to a single-valued `language` parameter instead of the default `f[format][]`:
 
 ```ruby
+# app/controllers/catalog_controller.rb
 config.add_facet_field 'language_ssim', filter_class: SimpleFilterClass
 ```
 
@@ -166,7 +182,7 @@ class SimpleFilterClass < Blacklight::SearchState::FilterField
     new_state.reset(params)
   end
 
-  # Facet values set int he URL
+  # Facet values set in the URL
   def values(except: [])
     Array(search_state.params[key])
   end
@@ -184,7 +200,7 @@ end
 
 
 <div class="alert alert-primary">
-  For more information about configuring facets in Blacklight, <a href="https://github.com/projectblacklight/blacklight/wiki/Configuration---Facet-Fields">checkout the Blacklight Wiki</a>.
+  For more information about configuring facets in Blacklight, <a href="https://github.com/projectblacklight/blacklight/wiki/Configuration---Facet-Fields">check out the Blacklight Wiki</a>.
 </div>
 
 [^1]: This is sorted by Solr based on the indexed term; Solr offers no control over direction, lexical vs natural sort order, etc.

v8.0.0.alpha/12-search-fields.md

@@ -5,7 +5,7 @@ permalink: /v8.0.0.alpha/search_fields/
 blacklight_version: v8.0.0.alpha
 ---
 
-Blacklight provides a UI element to choose a which "search fields" to execute the search against when multiple search field options are configured.  This is often used to provide a `Title`, `Author`, etc. search in addition to the default `All fields`.  You can think of these as different request handlers (`qt` parameter) in solr, however; it's not uncommon to use a single request handler and configure the solr_parameters directly in the search field configuration.
+Blacklight provides a UI element to choose which "search fields" to execute the search against when multiple search field options are configured.  This is often used to provide a `Title`, `Author`, etc. search in addition to the default `All fields`.  You can think of these as different request handlers (`qt` parameter) in solr, however; it's not uncommon to use a single request handler and configure the solr_parameters directly in the search field configuration.
 
 <div class="image-well">
   <img src="/public/images/blacklight-7-search-fields.png" alt="Blacklight search fields dropdown" />
@@ -15,6 +15,7 @@ Blacklight provides a UI element to choose a which "search fields" to execute th
 If there aren't any search fields configured (or one default one like below) the `qt` parameter set in the Blacklight config's `default_solr_parameters` will be used and there will be no search field dropdown presented to the user.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_search_field 'all_fields', label: 'All Fields'
 end
@@ -23,6 +24,7 @@ end
 Adding an new search field to the dropdown can be accomplished by using the `add_search_field` configuration option.  By default, the key passed to `add_search_field` will be passed to solr as the `qt` parameter.  In the example below, this would use the `title` request handler by passing `qt=title` when querying solr (when the user chooses "Title" for the search field dropdown).
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_search_field 'all_fields', label: 'All Fields'
   config.add_search_field 'title', label: 'Title'
@@ -32,6 +34,7 @@ end
 It's possible to use a different request handler than the key passed to `add_search_field`.  This way the `search_field` parameter in the application URL will remain `title` while the solr request handler that maps to remains know to the application configuration only (allowing you to change the request handler without breaking existing urls/bookmarks).
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_search_field 'all_fields', label: 'All Fields'
   config.add_search_field 'title', label: 'Title' do |field|
@@ -43,6 +46,7 @@ end
 A common pattern is to configure `solr_parameters` directly in the `add_search_field` configuration (and use the default search results handler).  You will likely want to pass `qf` and `pf` values that are defined in your default request handler.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_search_field 'all_fields', label: 'All Fields'
   config.add_search_field 'title', label: 'Title' do |field|

v8.0.0.alpha/13-sort-fields.md

@@ -15,6 +15,7 @@ Blacklight provides a UI element to choose a sort order for results when multipl
 Sort options can be configured using the `add_sort_field` configuration method.  The following configuration won't display because there is only one sort option to choose from.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_sort_field 'score desc', label: 'relevance'
 end
@@ -23,6 +24,7 @@ end
 Even though this will not display a sort option, it still controls the default sort behavior of search results.  It's often useful to supply sub sorts, even for a default score based relevancy search result as facet based results will all have the same score.  We can update the default sort of our results by updating the sort field configuration and adding pub date and title sub-sorts.  With the configuration below a facet only search (or simply an empty query) will be returned sorted.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_sort_field 'score desc, pub_date_si desc, title_si asc', label: 'relevance'
 end
@@ -31,6 +33,7 @@ end
 Adding additional sort fields is relatively straight forward. As above with the relevancy sort, it is most likely a good idea to provide sub sorts so when documents have the same relevancy score they are sorted using other criteria.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_sort_field 'score desc, pub_date_si desc, title_si asc', label: 'relevance'
   config.add_sort_field 'pub_date_si desc, title_si asc', label: 'year'
@@ -40,6 +43,7 @@ end
 The first value passed to `add_sort_field` will be both the sort value sent to solr as well as the parameter sent through the application url. It's possible to obscure the solr fields and their sort direction from the url by passing a key as the first parameter and passing the sort configuration explicitly as the `sort` key.
 
 ```ruby
+# app/controllers/catalog_controller.rb
 configure_blacklight do |config|
   config.add_sort_field 'relevance', sort: 'score desc, pub_date_si desc, title_si asc', label: 'relevance'
   config.add_sort_field 'year', sort: 'pub_date_si desc, title_si asc', label: 'year'