j1-template 2024.3.16 → 2024.3.18

data/lib/starter_web/pages/public/_includes/documents/photoswipe/300_caption_plugin_for_photoSwipe.asciidoc

@@ -0,0 +1,324 @@
+[role="mt-5"]
+[[photoswipe-captions-plugin]]
+=== Lightbox Captions
+
+PhotoSwipe does not support captions out of the box, but a *plugin* is available.
+The plugin can *automatically position* the text below or aside the image,
+depending on the available space for small to medium-sized captions *and* only
+for images with the default `fit` scale mode.
+
+link:https://dimsemenov.github.io/photoswipe-dynamic-caption-plugin/[Plugin demo] 
+
+For accessibility, make sure that important captions are always
+available without PhotoSwipe - either use an `alt` attribute on
+thumbnails or `aria-labelledby`.
+
+[role="mt-5"]
+[[photoswipe-captions-plugin-initialization]]
+=== Initialization
+
+The plugin has a single JS file *photoswipe-caption-plugin.min.js*
+and a single CSS file *photoswipe-caption-plugin.css*. The plugin can be
+initialized like so:
+
+[role="mt-4"]
+=== Base HTML Layout v1
+
+lorem:sentences[3]
+
+[source, html]
+----
+<!-- Slider main container (required) -->
+<div id="gallery_id" class="swiper swiper-container">
+
+  <!-- Slider wrapper element (required) -->
+  <div class="swiper-wrapper">
+    <!-- Slides (required) -->
+    <div class="swiper-slide">
+      <img src="path/to/image-1.jpg">
+      <span class="pswp-caption-content">Caption: Image 1</span>
+    </div>
+    <!-- more slides -->
+    <div class="swiper-slide">
+      <img src="path/to/image-x.jpg">
+      <span class="pswp-caption-content">Caption: Image X</span>
+    </div>
+  </div> <!-- END wrapper element -->
+  
+  <!-- Sniper Pagination (optional) -->
+  <div class="swiper-pagination"></div>
+
+  <!-- Sniper Navigation (optional) -->
+  <div class="swiper-button-prev"></div>
+  <div class="swiper-button-next"></div>
+
+  <!-- Sniper Scrollbar (optional)-->
+  <div class="swiper-scrollbar"></div>
+
+</div> <!-- END Main container -->
+----
+
+[role="mt-5"]
+=== Base HTML Layout v2
+
+lorem:sentences[3]
+
+[source, html]
+----
+<!-- Slider main container (required) -->
+<div id="gallery_id" class="swiper swiper-container">
+
+  <!-- Slider wrapper element (required) -->
+    <ul class="swiper-wrapper">
+      <!-- Slides (required) -->
+      <li class="swiper-slide">
+        <img src="path/to/image-1.jpg">
+        <span class="pswp-caption-content">Caption: Image 1</span>
+      </li>
+      <!-- more slides -->
+      <li class="swiper-slide">
+        <img src="path/to/image-x.jpg">
+        <span class="pswp-caption-content">Caption: Image X</span>
+      </li>
+    </ul> <!-- END swiper-wrapper (slides) -->
+
+  <!-- Sniper Pagination (optional) -->
+  <div class="swiper-pagination"></div>
+
+  <!-- Sniper Navigation (optional) -->
+  <div class="swiper-button-prev"></div>
+  <div class="swiper-button-next"></div>
+
+  <!-- Sniper Scrollbar (optional)-->
+  <div class="swiper-scrollbar"></div>
+
+</div> <!-- END Main container -->
+----
+
+[role="mt-5"]
+=== Extended HTML Layout
+
+lorem:sentences[3]
+
+[source, html]
+----
+<!-- Slider main container (required) -->
+<div id="gallery_id" class="swiper swiper-container">
+
+  <!-- Slider wrapper element (required) -->
+  <ul class="swiper-wrapper">
+    <!-- Slides (required) -->
+    <li class="swiper-slide">
+      <a href="path/to/image-1.jpg"
+        data-pswp-width="<max_width>"
+        data-pswp-height="<max_height>">
+        <img src="path/to/image-1.jpg" alt="Image 1">
+        <span class="pswp-caption-content">Caption: Image 1</span>
+      </a>
+    </li>
+    <!-- more slides -->
+    <li class="swiper-slide">
+      <a href="path/to/image-x.jpg"
+        data-pswp-width="<max_width>"
+        data-pswp-height="<max_height>">
+        <img src="path/to/image-x.jpg" alt="Image X">
+        <span class="pswp-caption-content">Caption: Image X</span>
+      </a>
+    </li>
+  </ul> <!-- END swiper-wrapper (slides) -->
+
+  <!-- Sniper Pagination (optional) -->
+  <div class="swiper-pagination"></div>
+
+  <!-- Sniper Navigation (optional) -->
+  <div class="swiper-button-prev"></div>
+  <div class="swiper-button-next"></div>
+
+  <!-- Sniper Scrollbar (optional)-->
+  <div class="swiper-scrollbar"></div>
+
+</div> <!-- END Main container -->
+----
+
+[role="mt-5"]
+=== Sniper Initialization (Javascript)
+
+lorem:sentences[3]
+
+[source, html]
+----
+<!-- Sniper Initialization (Javascript) -->
+<script>
+  const myLightbox = new PhotoSwipeLightbox({
+    gallerySelector: '#my_gallery',
+    pswpModule: PhotoSwipe,
+    // .. other options
+  });
+
+  const captionPlugin = new PhotoSwipeDynamicCaption(myLightbox, {
+    type: 'auto'
+  });
+
+  // init photoswipe core >>after<< the plugin is added
+  myLightbox.init();
+</script>
+----
+
+[role="mt-5"]
+[[photoswipe-captions-plugin-parameters]]
+== Parameters
+
+lorem:sentences[3]
+
+// .HTML Structure
+// [source, html]
+// ----
+// <a href="path/to/large-image.jpg" data-pswp-width="1024" data-pswp-height="768">
+//   <img src="path/to/thumbnail.jpg" alt="" />
+//   <span class="pswp-caption-content">Caption content</span>
+// </a>
+// ----
+
+// Or a function that should return *caption content*.
+
+// .Example
+// [source, js]
+// ----
+// captionContent: (slide) => {
+//   return slide.data.element.querySelector('img').getAttribute('alt');
+// }
+// ----
+
+[cols="4,2,2,4a", subs=+macros, options="header", width="100%", role="rtable mt-5"]
+|===
+|Name |Type |Default |Description \| Example
+
+|`captionContent`
+|string
+|_.pswp-caption-content_
+|Used to retrieve caption content. Can be a selector of the element from
+which caption content will be retrieved, if the element is not found, the
+plugin will try to use the thumbnail image `alt` attribute.
+
+|`type`
+|string
+|_auto_
+|Position type of the caption can be _auto_, _below_, or _aside_.
+
+* _below_, caption will always be placed below the image
+* _aside_, caption will always be placed on the right side of the
+  image
+* _auto_, the plugin will try to automatically determine the best
+  position (depending on available space)
+
+|`mobileLayoutBreakpoint`
+|number
+|600
+|Maximum window width at which mobile layout should be used, or a
+function that should return true if mobile layout should be used. 
+
+.Example
+[source, js]
+----
+mobileLayoutBreakpoint: (pswp, captionPlugin) => {
+  return (window.innerWidth < 750);
+}
+----
+
+|`horizontalEdgeThreshold`
+|number
+|20
+|When the caption `x` position is less than this value, it'll get class
+`pswp__dynamic-caption--on-hor-edge`. You may use it to apply
+different styling, such as horizontal padding.
+
+|`mobileCaptionOverlapRatio`
+|number
+|0.3
+|Ratio defines the amount of horizontal empty space before the mobile
+caption switches to an "`overlap`" layout. For example, if it's set to
+0.3 - the caption will start overlapping the image when more than 30% of
+horizontal space is not occupied by an image. If you set it to 0 - the
+caption will always overlap. If you set it to 1 - the caption will
+constantly shift the image (unless it's taller than the viewport).
+
+|`verticallyCenterImage`
+|boolean
+|`false`
+|If enabled, the image will always be vertically centered in the
+remaining space between the caption and the rest of the viewport. If set
+to false (default value) - the image will lift up only if the caption
+does not fit below.
+
+|===
+
+[role="mt-5"]
+[[photoswipe-captions-plugin-styling]]
+== Styling
+
+The caption has class `pswp__dynamic-caption`.
+
+It can be in one of these states:
+
+* Below the main image - `pswp__dynamic-caption--below`.
+* Right side of the main image - `pswp__dynamic-caption--aside`.
+* "`Mobile`" (by default just pinned to bottom) -
+`pswp__dynamic-caption--mobile`
+
+If the caption is near the left horizontal edge - it gets class
+`pswp__dynamic-caption--on-hor-edge`.
+
+Feel free to adjust styles in the *plugin CSS file* (and use media
+queries if you need to):
+
+[source, css]
+----
+.pswp__dynamic-caption--aside {
+  max-width: 300px;
+  padding: 20px 15px 20px 20px;
+  margin-top: 70px;
+}
+.pswp__dynamic-caption--below {
+  max-width: 700px;
+  padding: 15px 0 0;
+}
+.pswp__dynamic-caption--mobile {
+  background: rgba(0, 0, 0, 0.5);
+  padding: 10px 15px;
+}
+----
+
+[role="mt-5 mb-8"]
+=== How auto positioning works
+
+* Check if there is more horizontal or vertical free space around the
+  image.
+
+* If there is more free vertical space:
+** Set caption width to the width of the image
+** Add `pswp__dynamic-caption--below` class, so the size can also be
+   adjusted via CSS.
+** Measure caption height.
+** Check if the caption will fit without any adjustments to the image
+   position.
+*** If it does - just show the caption below the image.
+*** If it doesn't - reduce the pan area height by the height of the
+    caption.
+
+* If there is more horizontal space:
+** Add `pswp__dynamic-caption--aside` class, so the size can be
+   adjusted via CSS.
+** Measure caption width.
+** Check if caption will fit on the right side without any adjustments
+   of image position.
+*** If it does - just show the caption aside from the image.
+*** If it doesn't - reduce the pan area width by the width of the
+    caption.
+
+If `mobileLayoutBreakpoint` requirements are met:
+
+* Measure caption height when it occupies 100% of width.
+* Reduce pan area height to fit the caption below the image.
+* Check the amount of free horizontal space after the adjustment.
+* If there is too much horizontal space (`mobileCaptionOverlapRatio`),
+  just overlap the caption and keep the image at the default position.

data/lib/starter_web/pages/public/_includes/documents/swiper/100_swiper_features.asciidoc

@@ -0,0 +1,50 @@
+ifeval::[{swiper--features} == true]
+[role="mt-4"]
+=== Features
+
+* *Tree-shakeable*: Only modules you use will be imported into your
+  app's bundle.
+* *Mobile-friendly*: It is intended to be used in mobile websites, 
+  mobile web apps, and mobile native/hybrid apps.
+* *Library Agnostic*: Swiper doesn't require any JavaScript libraries
+  like jQuery, which makes Swiper much smaller and faster. It can be safely
+  used with libraries such as jQuery, Zepto, jQuery Mobile, etc.
+* *1:1 Touch movement*: By default, Swiper provides 1:1 touch movement
+  interaction, but this ratio can be configured through Swiper settings.
+* *Mutation Observer*: Swiper has an option to enable Mutation Observer,
+  with this feature Swiper will be automatically reinitialized and recalculate
+  all required parameters if you make dynamic changes to the DOM, or in Swiper
+  styles itself.
+* *Rich API*: Swiper comes with a very rich API. It allows creating your own
+  pagination, navigation buttons, parallax effects and many more.
+* *RTL*: Swiper is the only slider that provides 100% RTL support with
+  correct layout.
+* *Multi Row Slides Layout*: Swiper allows a multiple row slides layout,
+  with a few slides per column.
+* *Transition Effects*: Fade, Flip, 3D Cube, 3D Coverflow.
+* *Two-way Control*: Swiper may be used as controller for any number of
+  other Swipers, and even be controlled at the same time.
+* *Full Navigation Control*: Swiper comes with all required built-in
+  navigation elements, such as Pagination, Navigation arrows and Scrollbar.
+* *Flexbox Layout*: Swiper uses modern flexbox layout for slides layout,
+  which solves a lot of problems and time with size caclulations.
+  Such layout also allows configuring the Slides grid using pure CSS.
+* *Most Flexible Slides Layout Grid*: Swiper has a lot of parameters on
+  initialization to make it as flexible as possible. You can control slides
+  per view, per column, per group, space between slides, and many more.
+* *Images Lazy Loading*: Swiper Lazy Loading delays loading of images in
+  inactive/invisible slides until the user swipes to them. Such feature
+  could make the page load faster and improve Swiper performance.
+* *Virtual Slides*: Swiper comes with Virtual Slides feature that is great
+  when you have a lot of slides or content-heavy/image-heavy slides so it
+  will keep just the required amount of slides in DOM.
+* *Loop mode*
+* *Autoplay*
+* *Keyboard control*
+* *Mousewheel control*
+* *Nested sliders*
+* *History navigation*
+* *Hash navigation*
+* *Breakpoints configuration*
+* *Accessibility (A11y)*
+endif::[]

data/lib/starter_web/pages/public/_includes/documents/swiper/100_swiper_html_layout.asciidoc

@@ -0,0 +1,122 @@
+[role="mt-5"]
+== HTML Layout
+
+A HTML Layout is required to define the *slides* (images) to be
+used by a Swiper slider. Find the HTML Layout also with the
+https://swiperjs.com/swiper-api[Swiper Documentation, {browser-window--new}].
+
+[role="mt-4"]
+=== Base HTML Layout v1
+
+lorem:sentences[3]
+
+[source, html]
+----
+<!-- Slider main container (required) -->
+<div id="gallery_id" class="swiper swiper-container">
+
+  <!-- Slider wrapper element (required) -->
+  <div class="swiper-wrapper">
+    <!-- Slides (required) -->
+    <div class="swiper-slide">
+      <img src="<path_to>/image-1.jpg">
+    </div>
+    <!-- more slides -->
+    <div class="swiper-slide">
+      <img src="<path_to>/image-x.jpg">
+    </div>
+  </div> <!-- END wrapper element -->
+  
+  <!-- Sniper Pagination (optional) -->
+  <div class="swiper-pagination"></div>
+
+  <!-- Sniper Navigation (optional) -->
+  <div class="swiper-button-prev"></div>
+  <div class="swiper-button-next"></div>
+
+  <!-- Sniper Scrollbar (optional)-->
+  <div class="swiper-scrollbar"></div>
+
+</div> <!-- END Main container -->
+----
+
+[role="mt-4"]
+=== Base HTML Layout v2
+
+lorem:sentences[3]
+
+[source, html]
+----
+<!-- Slider main container (required) -->
+<div id="gallery_id" class="swiper swiper-container">
+
+  <!-- Slider wrapper element (required) -->
+    <ul class="swiper-wrapper">
+      <!-- Slides (required) -->
+      <li class="swiper-slide">
+        <img src="<path_to>/image-1.jpg">
+      </li>
+      <!-- more slides -->
+      <li class="swiper-slide">
+        <img src="<path_to>/image-x.jpg">
+      </li>
+    </ul> <!-- END swiper-wrapper (slides) -->
+
+  <!-- Sniper Pagination (optional) -->
+  <div class="swiper-pagination"></div>
+
+  <!-- Sniper Navigation (optional) -->
+  <div class="swiper-button-prev"></div>
+  <div class="swiper-button-next"></div>
+
+  <!-- Sniper Scrollbar (optional)-->
+  <div class="swiper-scrollbar"></div>
+
+</div> <!-- END Main container -->
+----
+
+[role="mt-4"]
+=== Extended HTML Layout
+
+lorem:sentences[3]
+
+[source, html]
+----
+<!-- Slider main container (required) -->
+<div id="gallery_id" class="swiper swiper-container">
+
+  <!-- Slider wrapper element (required) -->
+  <ul class="swiper-wrapper">
+    <!-- Slides (required) -->
+    <li class="swiper-slide">
+      <a href="<path_to>/image-1.jpg"
+        data-pswp-width="<max_width>"
+        data-pswp-height="<max_height>">
+        <img src="<path_to>/image-1.jpg" alt="Image 1">
+        <span class="pswp-caption-content">Caption: Image 1</span>
+      </a>
+    </li>
+    <!-- more slides -->
+    <li class="swiper-slide">
+      <a href="<path_to>/image-x.jpg"
+        data-pswp-width="<max_width>"
+        data-pswp-height="<max_height>">
+        <img src="<path_to>/image-x.jpg" alt="Image X">
+        <span class="pswp-caption-content">Caption: Image X</span>
+      </a>
+    </li>
+  </ul> <!-- END swiper-wrapper (slides) -->
+
+  <!-- Sniper Pagination (optional) -->
+  <div class="swiper-pagination"></div>
+
+  <!-- Sniper Navigation (optional) -->
+  <div class="swiper-button-prev"></div>
+  <div class="swiper-button-next"></div>
+
+  <!-- Sniper Scrollbar (optional)-->
+  <div class="swiper-scrollbar"></div>
+
+</div> <!-- END Main container -->
+----
+

data/lib/starter_web/pages/public/_includes/documents/swiper/100_swiper_initialization.asciidoc

@@ -0,0 +1,53 @@
+[role="mt-5"]
+== Initialization
+
+When the Swiper HTML layout is in place, a initialization is reqired to
+*create* a slider (instance). Find initialization also with the
+https://swiperjs.com/swiper-api[Swiper Documentation, {browser-window--new}].
+
+[source, js]
+----
+// initialize swiper instance with options
+const swiper = new Swiper(
+  swiperContainer,
+  parameters
+);
+----
+
+swiperContainer::
+HTML Element or string (with CSS Selector) of swiper a container HTML element
+(required).
+
+parameters::
+Object with Swiper parameters (ptional).
+
+.Example
+[source, js]
+----
+// Initialize a slider and create a instance variable (for later access)
+const swiper = new Swiper(
+  '.swiper',
+  {
+    speed: 400,
+    spaceBetween: 100
+  }
+);
+----
+
+[NOTE]
+====
+The method `new` returns a reference to the initialized swiper *instance*.
+====
+
+*After* swiper initialization, it is possible to access to the swiper
+instance.
+
+.Example
+[source, js]
+----
+// Create an instance variable
+const swiper = document.querySelector('.swiper').swiper;
+
+// Access the sliders instance (e.g. by a method) like so
+swiper.slideNext();
+----

data/lib/starter_web/pages/public/_includes/documents/swiper/110_swiper_common_options.asciidoc

@@ -0,0 +1,118 @@
+[role="mt-5"]
+== Common Options
+// https://swiperjs.com/types/interfaces/types_swiper_options.SwiperOptions
+
+Find a *full list* of all swiper options, aka known as *properties*, with the
+https://swiperjs.com/swiper-api#parameters[Swiper Documentation, {browser-window--new}]
+and with the *Parameters* sections below.
+
+The *properties* for a Swiper slider are extensive, covering various aspects
+of its behavior and appearance. Here's a *summary* of the key *default*
+values.
+
+
+[role="mt-4"]
+=== Base Settings
+
+[cols="3,3,6a", subs=+macros, options="header", width="100%", role="rtable mt-4"]
+|===
+|Name |Default |Description
+
+|<<options-direction>>
+|_horizontal_
+|Slides *move horizontally* by default
+
+|<<options-effect>>
+|_slide_
+|Base *sliding transition* by default
+
+|<<options-spaceBetween>>
+|0
+|No space (gutters) in between the slides by default
+
+|<<options-slidesPerView>>
+|1
+|Only one slide visible at a time by default
+
+|<<options-initialSlide>>
+|0
+|*First* slide *active initially* by default
+|<<options-centeredSlides>>
+|`false
+|*Active* slide *not centered* by default
+
+|<<options-loop>>
+|`false`
+|Continuous looping *disabled* by default
+
+|===
+
+
+[role="mt-4"]
+=== User Interaction
+
+[cols="3,3,6a", subs=+macros, options="header", width="100%", role="rtable mt-4"]
+|===
+|Name |Default |Description
+
+|<<options-allowTouchMove>>
+|`true`
+|Swiping *enabled* by default
+
+|<<options-grabCursor>>
+|`false`
+|Cursor doesn't change on hover by default
+
+|<<options-keyboard>>
+|`false`|
+Keyboard navigation *disabled* by default
+
+|<<options-mousewheel>>
+|false`|
+Mousewheel navigation *disabled* by default
+
+|<<options-pagination>>
+|*no default*
+|Pagination Elements (like bullets) *disabled* by default
+
+|<<options-navigation>>
+|*no default*
+|Navigation buttons *disabled* by default
+
+|<<options-scrollbar>>
+|*no default*
+|Scrollbar *disabled* by default
+
+|===
+
+
+[role="mt-4"]
+=== Appearance
+
+[cols="3,3,6a", subs=+macros, options="header", width="100%", role="rtable mt-4"]
+|===
+|Name |Default |Description
+
+|<<options-autoHeight>>
+|`false`
+|Slider height *doesn't adjust* to slide content by default
+
+|<<options-speed>>
+|300
+|Transition animation duration between slides in ms.
+
+|===
+
+
+[role="mt-4"]
+=== Page control
+
+[cols="3,3,6a", subs=+macros, options="header", width="100%", role="rtable mt-4"]
+|===
+|Name |Default |Description
+
+|<<options-breakpoints>>
+|*no default*
+|No *responsive breakpoints* defined by default
+
+|===