Merge branch 'main' into nuclia

CHANGES.rst

@@ -3,10 +3,19 @@ Changelog
 
 This changelog is only very rough. For the full changelog please refer to https://github.com/plone/training/commits/master
 
+
+- Scroll sidebar to active navigation element. @ksuess
+- Enhance orientation: Add chapter title and training title in sticky top bar. @ksuess
+- Enhance orientation: Add breadcrumbs to search results. @ksuess
+
+
+
 1.2.5 (unreleased)
 ------------------
 
-- Full rework of volto hands-on training to be up to date with changes to Volto during the last year [jackahl]
+- Overhaul Mastering Plone Development [ksuess]
+
+- Update Volto hands-on training with changes to during the last year [jackahl]
 
 - Language tweaks to WSGI training [polyester]
 

docs/_static/custom.css

@@ -1,11 +1,11 @@
 html[data-theme=light], html[data-theme=dark] {
-    --sbt-color-announcement: #3f0000;
+  --sbt-color-announcement: #3f0000;
 }
 a:hover {
-    --pst-color-link-hover: var(--pst-color-link);
+  --pst-color-link-hover: var(--pst-color-link);
 }
 .bd-header-announcement__content > a {
-    color: #66e5ff;
+  color: #66e5ff;
 }
 /*:root {*/
 /*  --highlight-searchresult-color: #b9ee9e;*/
@@ -179,6 +179,10 @@ a:hover {
 /*  margin-bottom: 1em;*/
 /*}*/
 
+#search-results .breadcrumbs .pathseparator {
+  padding: 0 .5em;
+}
+
 /*ul.search li span.highlighted {*/
 /*  background-color: var(--highlight-searchresult-color);*/
 /*}*/
@@ -253,6 +257,12 @@ a:hover {
 /*  white-space: nowrap;*/
 /*}*/
 
+/* Fix title in sticky header on mobile */
+.header-article-item-chapter-title {
+  overflow-y: hidden;
+  max-height: 100%;
+}
+
 /*!* submenu *!*/
 /*.bd-toc {*/
 /*  box-shadow: 0 .2rem .5rem rgba(0, 0, 0, .05), 0 0 .0625rem rgba(0, 0, 0, .1);*/

docs/_static/patch_scrollToActive.js

@@ -0,0 +1,30 @@
+/**
+ * Scroll to active navigation element
+ */
+
+
+var sbRunWhenDOMLoaded = (cb) => {
+  console.debug("*** sbRunWhenDOMLoaded", cb);
+    if (document.readyState != "loading") {
+      cb();
+    } else if (document.addEventListener) {
+      document.addEventListener("DOMContentLoaded", cb);
+    } else {
+      document.attachEvent("onreadystatechange", function () {
+        if (document.readyState == "complete") cb();
+      });
+    }
+  };
+
+  var scrollToActive = () => {
+    let active_navigation_item = [...document.querySelectorAll("li.current.active")].pop();
+    if (active_navigation_item) {
+      active_navigation_item.scrollIntoView();
+
+      let article = [...document.querySelectorAll("article")].pop();
+      article.scrollIntoView({inline: "start" });
+    }
+  };  
+
+  sbRunWhenDOMLoaded(scrollToActive);
+

docs/_static/searchtools.js

@@ -10,6 +10,32 @@
  */
 "use strict";
 
+var title_repository = 'Plone training';
+
+
+/**
+ * Return array with titles of ancestors of file.
+ * @param {number} idx - The index of the result item in global list of files
+ * @returns array
+ */
+function _getParentTitles(idx, docNames, titles) {
+  let path = docNames[idx]
+  let parentpathtokens = path.split('/').slice(0, -1);
+
+  let parentTitles = parentpathtokens.map((el, index) => {
+    let foo = `${parentpathtokens.slice(0, index+1).join('/')}`
+    let parentId = docNames.indexOf(foo);
+    if (parentId === -1) {
+      foo = `${parentpathtokens.slice(0, index+1).join('/')}/index`
+      parentId = docNames.indexOf(foo);
+    }
+    let title = parentId === -1 ? title_repository : titles[parentId];
+    return title
+  })
+
+  return parentTitles
+}
+
 /**
  * Simple result scoring code.
  */
@@ -57,6 +83,35 @@ const _removeChildren = (element) => {
 const _escapeRegExp = (string) =>
   string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
 
+
+function _getBreadcrumbs(item, linkUrl) {
+  // No breadcrumbs for top level pages
+  if (item[0].split('/')[1] == 'index') {
+    return null
+  }
+  let parentTitles = item[6];
+
+  let parentDefaultTitles = [
+    "Plone trainings",
+    "Training for Plone developers"
+  ];
+  parentTitles = Array.isArray(parentTitles) ? parentTitles : parentDefaultTitles;      
+  let pathTokens = item[0].split('/')
+    .slice(0, -1);
+  let pathArray = pathTokens.map((el, index) => {
+    return {
+      "path": pathTokens.slice(0, index+1).join('/'),
+      "title": parentTitles[index]
+    }
+  })
+  let markup = pathArray
+    .map((el, idx) => {
+        return `<a href="/${el.path}">${el.title}</a>` 
+      })
+  markup.push(`<span class="lastbreadcrumb">${item[1]}</span>`)
+  return markup.join('<span class="pathseparator">&gt;</span>');
+}
+
 const _displayItem = (item, searchTerms) => {
   const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
   const docUrlRoot = DOCUMENTATION_OPTIONS.URL_ROOT;
@@ -82,6 +137,16 @@ const _displayItem = (item, searchTerms) => {
     requestUrl = docUrlRoot + docName + docFileSuffix;
     linkUrl = docName + docLinkSuffix;
   }
+
+  let breadcrumbs = _getBreadcrumbs(item, linkUrl);
+  if (breadcrumbs) {
+    let breadcrumbsNode = document.createElement("div");  
+    breadcrumbsNode.innerHTML = breadcrumbs;
+    breadcrumbsNode.classList.add("breadcrumbs");
+    listItem.appendChild(breadcrumbsNode);
+  }
+
+  // Title links to chapter
   let linkEl = listItem.appendChild(document.createElement("a"));
   linkEl.href = linkUrl + anchor;
   linkEl.dataset.score = score;
@@ -100,6 +165,7 @@ const _displayItem = (item, searchTerms) => {
       });
   Search.output.appendChild(listItem);
 };
+
 const _finishSearch = (resultCount) => {
   Search.stopPulse();
   Search.title.innerText = _("Search Results");
@@ -108,10 +174,12 @@ const _finishSearch = (resultCount) => {
       "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories."
     );
   else
-    Search.status.innerText = _(
-      `Search finished, found ${resultCount} page(s) matching the search query.`
-    );
+    // Search.status.innerText = _(
+    //   `Search finished, found ${resultCount} page(s) matching the search query.`
+    // );
+    Search.status.innerText = `${resultCount} page(s) found.`
 };
+
 const _displayNextItem = (
   results,
   resultCount,
@@ -277,14 +345,11 @@ const Search = {
       localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" "))
     }
 
-    // console.debug("SEARCH: searching for:");
-    // console.info("required: ", [...searchTerms]);
-    // console.info("excluded: ", [...excludedTerms]);
-
     // array of [docname, title, anchor, descr, score, filename]
     let results = [];
     _removeChildren(document.getElementById("search-progress"));
 
+    // query matches title
     const queryLower = query.toLowerCase();
     for (const [title, foundTitles] of Object.entries(allTitles)) {
       if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) {
@@ -297,6 +362,7 @@ const Search = {
             null,
             score,
             filenames[file],
+            _getParentTitles(file, docNames, titles),
           ]);
         }
       }
@@ -337,11 +403,7 @@ const Search = {
         return condition
       })
     }
-
-    // Enrich item with parent training title
-    // for (i = 0; i < results.length; i++)
-    //   results[i][6] = results[i][6] || 'TODO training title';
-
+
     // now sort the results by score (in opposite order of appearance, since the
     // display function below uses pop() to retrieve items) and then
     // alphabetically
@@ -372,10 +434,6 @@ const Search = {
 
     results = results.reverse();
 
-    // for debugging
-    //Search.lastresults = results.slice();  // a copy
-    // console.info("search results:", Search.lastresults);
-
     // print the results
     _displayNextItem(results, results.length, searchTerms);
   },
@@ -465,6 +523,7 @@ const Search = {
     const scoreMap = new Map();
     const fileMap = new Map();
 
+
     // perform the search on the required terms
     searchTerms.forEach((word) => {
       const files = [];
@@ -540,6 +599,7 @@ const Search = {
 
       // select one (max) score for the file.
       const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w]));
+
       // add result to the result list
       results.push([
         docNames[file],
@@ -548,6 +608,7 @@ const Search = {
         null,
         score,
         filenames[file],
+        _getParentTitles(file, docNames, titles)
       ]);
     }
     return results;

docs/_templates/chapter-title.html

@@ -0,0 +1 @@
+<span class="header-article-item-chapter-title">{{ title|striptags|e }}{%- for parent in parents %} – {{ parent.title }}{%- endfor %}</span>

docs/_templates/components/search-field.html

@@ -44,6 +44,7 @@
         ['advanced-python','Advanced Python'],
         ['angular','Angular'],
         ['gatsby','Gatsby'],
+        ['contributing', 'Contributing'],
         ] %}
         <option value="{{id}}">{{ title }}</option>
       {% endfor %}

docs/_templates/search.html

@@ -1,7 +1,6 @@
 {%- extends "page.html" %}
 {# Over-ride the body to be custom search structure we want #}
 {% block docs_body %}
-{% set title = _('Search') %}
   <div class="bd-search-container">
     <h1>{{ _("Search") }}</h1>
     <noscript>
@@ -29,7 +28,11 @@ <h1>{{ _("Search") }}</h1>
     }
   </script>
 {% endblock docs_body %}
-
+{# Below sections just re-create the behavior of Sphinx default search #}
+{# Page metadata #}
+{%- block htmltitle -%}
+  <title>{{ _("Search") }} - {{ title or docstitle }}</title>
+{%- endblock htmltitle -%}
 {# Manually include the search JS that Sphinx includes #}
 {% block scripts -%}
   {{ super() }}

docs/conf.py

@@ -140,8 +140,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = [
-]
+exclude_patterns = []
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -154,6 +153,9 @@
 html_favicon = "_static/favicon.ico"
 
 html_css_files = ["custom.css", ("print.css", {"media": "print"})]
+html_js_files = [
+    "patch_scrollToActive.js",
+]
 
 html_extra_path = [
     "robots.txt",
@@ -179,6 +181,7 @@
     "use_edit_page_button": True,
     "use_issues_button": True,
     "use_repository_button": True,
+    "article_header_start": ["toggle-primary-sidebar", "chapter-title"],
 }
 
 
@@ -238,7 +241,8 @@ def source_replace(app, docname, source):
 
 # Dict of replacements.
 source_replacements = {
-    "{PLONE_BACKEND_VERSION}": "6.0.0b3",
+    "{PLONE_BACKEND_VERSION}": "6.0.7",
+    "{VOLTO_FRONTEND_VERSION}": "17.0.0-alpha.27",
 }
 
 

docs/contributing/writing-docs-guide.md

@@ -117,7 +117,7 @@ From [Web Accessibility In Mind (WebAIM)](https://webaim.org/techniques/alttext/
 Accessibility is part of the [Plone brand and identity](https://plone.org/accessibility).
 
 ````md
-```{image} /_static/standards.png
+```{image} _static/standards.png
 :alt: XKCD "Standards" comic strip
 ```
 ````

docs/effective-volto/about_effective_volto.md

@@ -23,7 +23,7 @@ Tiberiu Ichim
 
 Víctor Fernández de Alba
 
-: Víctor is CTO at kitconcept GmbH, a Plone solution provider from Bonn, Germany. Member of the Plone Community since 2006, author of a Plone book, co-author of Plone 5’s multilingual feature and its default theme Barceloneta. He is the Plone 6 Volto Release Manager, member of the Volto Team and Plone REST API contributor. He was also organizer of the Barcelona Plone Conference in 2017, sprints and other Plone events in Barcelona and Bonn and he is deeply involved in several Plone Community Teams including the Plone Foundation Board of directors.
+: Víctor is CTO at kitconcept GmbH, a Plone solution provider from Bonn, Germany. Member of the Plone Community since 2006, currently he's the Release Manager of Plone Volto and Volto Team leader. Author of a Plone book, co-author of Plone 5’s multilingual feature and its default theme Barceloneta. He is the Plone 6 Volto Release Manager, member of the Volto Team and Plone REST API contributor. He was also organizer of the Barcelona Plone Conference in 2017, sprints and other Plone events in Barcelona and Bonn and he is deeply involved in several Plone Community Teams.
 
 ## License
 

docs/effective-volto/addons/asyncconnect.md

@@ -14,7 +14,8 @@ components, making it an isomorphic application.
 
 How does that work? In simplified pseudocode, it works like this:
 
-- in server.jsx we have code like `react-dom.renderToString(<Router/>)`
+- in Volto's `server.jsx` we convert the React component tree to an HTML string
+  with `react-dom.renderToString(<Router routes={routes} />)`
 - the Router renders its declared components, which is the `App` and its
   direct child, the `View` component
 
@@ -68,12 +69,13 @@ prefetch a `footer-links` page from the backend and include it with every SSR:
   ];
 ```
 
-Note: this example is a low-tech "frontend-er only" solution. In real life you
-will probably want to devise a mechanism where that footer-links information is
+Note: this example is a low-tech "frontend only" solution. In real life you
+will probably want to create a mechanism where that footer-links information is
 automatically included with every content request.
 
-Notice the extender mechanism, we register a "modifier" for the current list of
-"async connect dispatch actions".
+As you can see from the above example, the configuration registration is done
+by using a "modifier" of all the other registered asyncPropsExtender, so we
+can even change that list of extenders, with something like:
 
 ```
 config.settings.asyncPropsExtenders = [