j1-template 2021.0.0 → 2021.0.5

data/lib/starter_web/pages/public/learn/roundtrip/600_quicksearch.adoc

@@ -0,0 +1,417 @@
+---
+title:                                  QuickSearch
+tagline:                                full index search based on lunr
+date:                                   2020-11-08 00:00:00
+description: >
+                                        QuickSearch is based on the search engine Lunr,
+                                        fully integrated with J1 Template. Lunr is designed
+                                        to be lightweight, yet full featured to provide a
+                                        great search experience. No need for complex external,
+                                        server-sideed search engines, or commercial services
+                                        on the Internet like Google.
+
+tags:                                   [ Roundtrip, QuickSearch ]
+categories:                             [ Search ]
+
+toc:                                    true
+scrollbar:                              false
+
+permalink:                              /pages/public/learn/roundtrip/quicksearch/
+regenerate:                             false
+
+resources:                              [ lunr, rouge, lightbox, clipboard ]
+resource_options:
+  - toccer:
+      collapseDepth:                    3
+  - attic:
+      padding_top:                      400
+      padding_bottom:                   50
+      opacity:                          0.5
+      slides:
+        - url:                          /assets/images/modules/attics/banner/lunr-banner-1280x800.jpg
+          alt:                          Lunr
+---
+
+// Page Initializer
+// =============================================================================
+// Enable the Liquid Preprocessor
+:page-liquid:
+
+// Set page (local) attributes here
+// -----------------------------------------------------------------------------
+// :page--attr:                         <attr-value>
+
+//  Load Liquid procedures
+// -----------------------------------------------------------------------------
+{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
+
+// Load page attributes
+// -----------------------------------------------------------------------------
+{% include {{load_attributes}} scope="all" %}
+
+// Page content
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+// Include sub-documents
+// -----------------------------------------------------------------------------
+
+
+QuickSearch is based on the search engine Lunr, fully integrated with J1
+Template. Lunr is designed to be lightweight, yet full featured to provide a
+great search experience. No need for complex external, server-sideed search
+engines, or commercial services on the Internet like Google.
+
+Searching a website using QuickSearch is different in compare to search engines
+like Google or Microsoft Bing. Those search platforms using complex algorithm
+to provide a simple interface to the public, but using a lot of artificial
+intelligence (AI) methods in behind to make senseful results out of a handfull
+words given for a search.
+
+Nevertheless, QuickSearch, the J1 implementation of Lunr, is simple like
+searching at Google, but offers additional features to do searches more
+specific - if wanted. QuickSearch provides a easy to use query language for
+better results - anyway!
+
+== Core concepts
+
+Understanding some of the concepts and terminology that QuickSearch (Lunr)
+uses will allow users to provide powerful search functionality - to get more
+relevant search results.
+
+=== Indexing documents
+
+QuickSearch, offers searches on *all* documents of website generated by J1
+but only for this site. Advantage, no internet access is done for searches,
+because it's not needed. Searches are based on a pre-build local site
+*full-text* index loaded by the browser on a page request. The index for a
+site is generated by the (Jekyll) plugin `lunr_index.rb` located in the
+`_plugins` folder.
+
+The full-text index is always generated by Jekyll at build-time:
+
+.Index creation at buildtime
+----
+Startup the site ..
+Configuration file: ...
+
+ Incremental build: enabled
+      Generating...
+     J1 QuickSearch: creating search index ...
+     J1 QuickSearch: finished, index ready.
+     ....
+----
+
+Or, if you're running a website in development mode, the index gets refreshed
+for all files added or modified.
+
+.Index creation if files added, or modified
+----
+site:       Regenerating: n file(s) changed at ...
+site:       ...
+site:      J1 QuickSearch: creating search index ...
+site:      J1 QuickSearch: finished, index ready.
+           ...
+----
+
+=== Documents
+
+The searchable data in an index is organized as documents that contains the
+text, the words (terms), that you want to be able to search on. A document is
+a data set (JSON object) with a set of fields that are processed to create the
+result list for a search.
+
+A document data set might look like this:
+
+[source, json, role="noclip"]
+----
+{
+  "title": "Web in a Day",
+  "tagline": "meet & greet jekyll",
+  "url": "/pages/public/learn/kickstarter/web_in_a_day/meet_and_greet/",
+  "date": "2018-05-01 00:00:00 +0000",
+  "tags": [
+    "Introduction"
+  ],
+  "categories": [
+    "Jekyll",
+    "Knowledge",
+    "Tutorial"
+  ],
+  "description": "Web in a Day is the first in a series of tutorials ..."
+}
+----
+
+In this document there are several fields, like `title`, `tagline`, or
+`description` that could be used for *full-text* searches. But additional
+fields are available, like `tags` or `categories` that can be used for
+more specific searches based on `identifiers`.
+
+NOTE: The document *content* is collected by the (intrinsic) field `body`.
+To limit the size of the index data loaded by the browser, the body
+field is removed from a document. The `body` field not available as an
+*explicit* field for searches, but the *content* is fully searchable.
+
+To do a simple full-text search as well as more specific searches, the
+QuickSearch core engine Lunr offers a query language, a DSL (domain specific
+language). Find more about *QuickSearch|Lunr DSL* queries with section
+<<Searching>>.
+
+=== Scoring
+
+The relevance (the `score`) of a document is calculated based on an algorithm
+called *BM25*, along with other factors. You don’t need to worry too much about
+the details of how this technically works. To summarize: the more a search term
+occurs in a single document, the more that term will increase that document’s
+score, but the more a search term occurs in the *overall* collection of
+documents, the less that term will increase a document’s score. In other words,
+seldom words counts, and increase the score.
+
+Scoring information, generated by the BM25 algorithm, is added to the (local)
+search index. This allows a very fast calculation of the relevance of documents
+for queries.
+
+Imagine you’re website contains documents about Jekyll. The term `Jekyll` may
+occur very frequently throughout the entire website; used quite often for the
+content. So finding a document that mentions the term Jekyll isn’t very
+significant for a search.
+
+However, if you’re searching for `Jekyll Generator`, only some documents of
+the website have the word `Generator` in them, and that will bring the score
+(relevance) for documents having both words in them at a higher level,
+bring them higher up in the search results.
+
+Matching and scoring is used by all search engines; the same to J1 QuickSearch.
+You'll see for QuickSearch a similiar behavior in *sorting* search results as
+you already know from commercial internet search engines like Google: the top
+results are the more relevant ones.
+
+== Searching
+
+To access QuickSearch, a magnifier button is available in the `Quicklinks`
+area in the menu bar at the top-right of every page.
+
+.Search button (magnifier) in the quick access area
+lightbox::quicksearch-icon[ 800, {data-quicksearch-icon} ]
+
+A mouse-click on the magnifier button opens the search input and disables
+all other navigation to focus on what you're itended to do: searching.
+
+.Input bar for a QuickSearch
+lightbox::quicksearch-input[ 800, {data-quicksearch-input} ]
+
+Search queries looks like simple text. But the search `engine` under the
+hood of QuickSearch transforms the given search string (text) always into a
+search query. This supports a special syntax, the DSL, for defining more
+complex queries for better (scored) results.
+
+As always: start simple!
+
+=== Simple searches
+
+The simplest way to run a search is to pass the text (words, terms) on which
+you want to search on:
+
+[source, text]
+----
+jekyll
+----
+
+The above will return all documents that match the term `jekyll`. Searches for
+*multiple* terms (words) are also supported. If a document matches *at least*
+one of the search terms, it will show in the results. The search terms are
+combined by a logical `OR`.
+
+[source, text]
+----
+jekyll tutorial
+----
+
+The above example will match documents that contain either `jekyll` *OR*
+`tutorial`. Documents that contain _both_ will increase the score, and those
+documents be returned first.
+
+NOTE: In difference to a Google search (terms are combined at Google by a
+logical `AND`) a Quicksearch combines the terms by an `OR`.
+
+To combine search terms in a QuickSearch query by a logical *AND*, the terms
+could be prepended by a plus sign (`+`) to mark them as for the QuickSearch
+query (DSL) as *required*:
+
+[source, text]
+----
++jekyll +tutorial
+----
+
+=== Wildcards
+
+QuickSearch supports wildcards when performing searches. A wildcard is
+represented as an asterisk (`*`) and can appear anywhere in a search
+term. For example, the following will match all documents with words
+beginning with `Jek`:
+
+[source, text]
+----
+jek*
+----
+
+NOTE: Language grammar rules are not relevant for searches. To simplify an
+index, all words (terms) are transformed to lower case. As result, a word
+`Jekyll` is the same as `jekyll` from a search-engines prospective. Language
+variations of words like `Jekyll's` or plurals like `Generators` are reduced
+to their base form. For searches, don't take care of grammar rules but the
+spelling. If you're unsure about the spelling of a word, use wildcards.
+
+
+=== Fields
+
+By default, Lunr will search *all fields* in a document for the given query
+terms, and it is possible to restrict a term to a specific *field*. The
+following example searches for the term `jekyll` in the field title:
+
+[source, text]
+----
+title:jekyll
+----
+
+The search term is prefixed with the name of the field, followed by a
+colon (`:`). The field _must_ be one of the fields defined when building
+the index. Unrecognised fields will lead to an error.
+
+Field-based searches can be combined with all other term modifiers and
+wildcards, as well as other terms. For example, to search for words
+beginning with `jek` in the title *AND* the wildcard `coll*` in a document,
+the following query can be used:
+
+[source, text]
+----
++title:jek* +coll*
+----
+
+==== Available fields
+
+Beside the document *body*, an intrinsic field to create the full-text index
+out of the document *content*, some more specific fields are available for
+searches.
+
+.Available fields (all documents)
+[cols="3a,3a,6a, options="header", width="100%", role="rtable mt-3"]
+|===============================================================================
+|Name |Value |Description\|Example\|s
+
+|`title`
+|`string`
+|The headline of a document (article, post)
+
+Example\|s: QuickSearch
+[source, text]
+----
+title:QuickSearch
+----
+
+|`tagline`
+|`string`
+|The subtitle of a document (article, post)
+
+Example\|s: full index search
+
+|`tags`
+|`string`
+|Tags describe the content of a document.
+
+Example\|s: Roundtrip, QuickSearch
+
+|`categories`
+|`string`
+|Categories describe the group of documnets a document belongs to.
+
+Example\|s: Search
+
+|`description`
+|`string`
+|The description is given by the author for a document. It gives a brief
+summary what the document is all about.
+
+Example\|s: QuickSearch is based on the search engine Lunr, fully integrated
+with J1 Template  ...
+
+|===============================================================================
+
+
+////
+=== Boosts
+
+In multi-term searches, a single term may be important than others. For
+these cases Lunr supports term level boosts. Any document that matches a
+boosted term will get a higher relevance score, and appear higher up in
+the results. A boost is applied by appending a caret (`^`) and then a
+positive integer to a term.
+
+[source, javascript]
+----
+idx.search('foo^10 bar')
+----
+
+The above example weights the term “foo” 10 times higher than the term
+“bar”. The boost value can be any positive integer, and different terms
+can have different boosts:
+
+[source, javascript]
+----
+idx.search('foo^10 bar^5 baz')
+----
+
+=== Fuzzy Matches
+
+Lunr supports fuzzy matching search terms in documents, which can be
+helpful if the spelling of a term is unclear, or to increase the number
+of search results that are returned. The amount of fuzziness to allow
+when searching can also be controlled. Fuzziness is applied by appending
+a tilde (`~`) and then a positive integer to a term. The following
+search matches all documents that have a word within 1 edit distance of
+“foo”:
+
+[source, javascript]
+----
+idx.search('foo~1')
+----
+
+An edit distance of 1 allows words to match if either adding, removing,
+changing or transposing a character in the word would lead to a match.
+For example “boo” requires a single edit (replacing “f” with “b”) and
+would match, but “boot” would not as it also requires an additional “t”
+at the end.
+////
+
+=== Term presence
+
+By default, Lunr combines multiple terms together in a search with a
+logical OR. That is, a search for `jekyll collections` will match documents
+that contain `jekyll` or contain `collections` or contain both. This behaviour
+is controllable at the term level, i.e. the presence of each term in
+matching documents can be specified.
+
+By default each term is optional in a matching document, though a document
+must have at least one matching term. It is possible to specify that a term
+must be present in matching documents, or that it must be absent in matching
+documents.
+
+To indicate that a term must be *present* in matching documents the term
+could be prefixed with a plus sign (`+`) (required) and to indicate that a
+term  must be *absent* (not wanted) the term should be prefixed with a minus
+(`-`).
+
+The below example searches for documents that *must* contain `jekyll`, and
+must *not* contain the word `collection`:
+
+[source, text]
+----
++jekyll -collection
+----
+
+To simulate a logical *AND* search of documents that contains the word `jekyll`
+*AND* the word `collection`, mark both terms as required:
+
+[source, text]
+----
++jekyll +collection
+----

data/lib/starter_web/pages/public/learn/roundtrip/610_fam.adoc

@@ -1,7 +1,7 @@
 ---
 title:                                  Floating Action Menu
 tagline:                                using fam buttons
-date:                                   2020-11-08 12:00:00
+date:                                   2020-11-08 00:00:00
 description: >
                                         A floating action button (FAB) represents the primary action/s
                                         of a page. Multiple actions can be configured as a FAM, the
@@ -16,7 +16,7 @@ scrollbar:                              false
 
 image:                                  /assets/images/modules/attics/cookies-1920x1200-bw.jpg
 permalink:                              /pages/public/learn/roundtrip/fam/
-regenerate:                             true
+regenerate:                             false
 
 resources:                              [ lightbox, rouge, clipboard, fam ]
 resource_options:

data/lib/starter_web/pages/public/learn/roundtrip/_includes/attributes.asciidoc

@@ -78,6 +78,9 @@ tag::data[]
 :data-images-standalone:                          "pages/roundtrip/100_present_images/lightbox-image-1.jpg, Golden Gate Bridge with San Francisco in distance, pages/roundtrip/100_present_images/lightbox-image-2.jpg, Forest with mountains behind"
 :data-images-group:                               "pages/roundtrip/100_present_images/lightbox-image-1.jpg, Golden Gate Bridge with San Francisco in distance, pages/roundtrip/100_present_images/lightbox-image-2.jpg, Forest with mountains behind"
 
+:data-quicksearch-icon:                           "pages/roundtrip/600_quicksearch/quicksearch_icon-800x200.jpg, Search button (magnifier) in the quick access area"
+:data-quicksearch-input:                          "pages/roundtrip/600_quicksearch/quicksearch_input-800x200.jpg, Input bar for a QuickSearch"
+
 end::data[]
 
 

data/lib/starter_web/pages/public/learn/roundtrip/_includes/documents/410_bottom_info.asciidoc

@@ -1,14 +1,14 @@
-// === Bottom Info
-// Add `.modal-dialog-centered` to `.modal-dialog` to vertically center the modal.
-
-++++
-<div class="ml-2">
-  <!-- Button trigger modal -->
-  <button type="button"
-    class="btn btn-primary btn-raised"
-    data-toggle="modal"
-    data-target="#frameModalBottomSuccessDemo">
-    Launch Example
-  </button>
-</div>
-++++
+// === Bottom Info
+// Add `.modal-dialog-centered` to `.modal-dialog` to vertically center the modal.
+
+++++
+<div class="ml-2">
+  <!-- Button trigger modal -->
+  <button type="button"
+    class="btn btn-primary btn-raised"
+    data-toggle="modal"
+    data-target="#frameModalBottomSuccessDemo">
+    Launch Example
+  </button>
+</div>
+++++