document image lightboxes

2sxc Docs Generator/2sxc Docs.code-workspace

@@ -15,6 +15,9 @@
       "FIPS",
       "Imageflow",
       "inpage",
+      "Lightbox",
+      "lightboxed",
+      "Lightboxes",
       "Linq",
       "Mobius",
       "NVARCHAR",

2sxc Docs Generator/pages/basics/images/guide/index.md

@@ -48,7 +48,10 @@ the designer must activate it on the field. Otherwise the feature is not availab
 
 **Important**: The config-button is only available...
 
-1. ...IF it has been enabled
+<!-- 1. ...IF it has been enabled -->
+1. If the Razor template uses the automatic APIs to render the image
+    1. When using the new Typed code, using the `something.Img("Image")` API (see [Img(...)](xref:ToSic.Sxc.Data.ITypedItem.Img*) and [Picture(...)](xref:ToSic.Sxc.Data.ITypedItem.Picture*))
+    1. or using the [IImageService](xref:ToSic.Sxc.Services.IImageService) (older way)
 1. ...and IF the file is an image
 1. ...and IF the file "belongs" to the item being edited  
     _If the file is a general file from another item or from the root folder, the metadata is not available._
@@ -59,15 +62,32 @@ the designer must activate it on the field. Otherwise the feature is not availab
 When a user edits the image settings in the UI, the data is stored as [metadata](xref:Basics.Metadata.Index) for this image.
 This is important, because generating a perfect `<img>` or `<picture>` tag requires this information.
 
-## Part 3: Dynamic Field
+## Part 3: Razor Code to Generate HTML for Images
+
+### Part 3a: Modern Typed Code
+
+When using modern typed code, the object containing the data is an [ITypedItem](xref:ToSic.Sxc.Data.ITypedItem)
+or something which inherits from it.
+In this case, the API will take care of almost everything.
+Just use one of these methods to create the HTML:
+
+* `thing.Img("Image")` - for a simple `<img>` tag
+* `thing.Picture("Image")` - for a `<picture>` tag
+
+### Part 3b: Legacy Code (older APIs)
+
+The older API used the [IImageService](xref:ToSic.Sxc.Services.IImageService) to generate the HTML.
+This in turn needed a [IField](xref:ToSic.Sxc.Data.IField) object to figure out what to do.
+
+#### Part 3b Legacy Code - Dynamic Field
 
 If a content item stores the image on a property `.Image` then something like `Content.Image` would return `/Portal/0/Adam/some-image.jpg`.
 In this case, the [IImageService](xref:ToSic.Sxc.Services.IImageService) cannot find the metadata.
 
 This is why we need to give it the entire field, not just the value. This is done using `Content.Field("Image")`
 and will get your code a [IDynamicField](xref:ToSic.Sxc.Data.IField).
 
-## Part 4: ImageService
+#### Part 3b Legacy Code - ImageService
 
 The [IImageService](xref:ToSic.Sxc.Services.IImageService) will take all the known information and generate an `<img>` or a `<picture>` tag.
 
@@ -86,9 +106,9 @@ Some Tutorials to learn this
 * [](xref:Tut.Img.Picture)
 * [](xref:Tut.Img.Guide)
 
-## Part 5: Settings and Recipes
+## Part 4: Settings and Recipes
 
-**Settings** are preconfigured parameters how the image is to be resized.
+**Settings** are pre configured parameters how the image is to be resized.
 They are stored at App, Site, Global or Preset level.
 
 By default the configuration called `Content` is used for images in the Content of the page.
@@ -113,28 +133,18 @@ You can also generate your own recipes:
 * inherit/expand an existing recipe like this: `.Recipe(originalRecipe, ...)`
 
 
-## Part 6: Link.Image(...) API
+## Good to Know: Link.Image(...) API
 
 In the rare cases where you just need a URL and not the full HTML, check out the [Link.Image(...) API](xref:NetCode.DynamicCode.Objects.Link.Image).
 
 It is not as powerful as the ImageService but if you only need a URL it may be what you need.
 
 🎓 [](xref:Tut.Img.LinkImage)
 
-<!--
-## Part 3: Special In-Page Toolbar (WIP ca. v13.13)
-
-TODO:
-
----
-
-
-TODO: we're still working on these docs
-
--->
 
 ---
 
 ## History
 
 1. Guide created for v13.10
+1. Updated for v16 which introduced the new Typed API

2sxc Docs Generator/pages/basics/images/lightbox/index.md

@@ -0,0 +1,74 @@
+---
+uid: Basics.Images.Lightbox.Index
+---
+
+<img src="~/assets/features/image-resizer.svg" class="feature">
+
+# Image Lightbox (new v17)
+
+[!include[](~/pages/basics/stack/_shared-float-summary.md)]
+<style>  .context-box-summary .image-resizer    { visibility: visible; } </style>
+
+Images should often show a lightbox when clicked.
+This is especially important for galleries, but also for single images.
+
+2sxc 17 introduces the ability that images can be "lightboxed" according to editor input.
+
+Previously only image where the Razor code explicitly set a lightbox would be shown this way.
+
+> [!IMPORTANT]
+> This feature requires the new Typed APIs (v17+) to be used,
+> as the Razor code must generate the HTML to make this happen.
+>
+> This include the [Img(...)](xref:ToSic.Sxc.Data.ITypedItem.Img*),
+> [Picture(...)](xref:ToSic.Sxc.Data.ITypedItem.Picture*)
+> and [Html(...)](xref:ToSic.Sxc.Data.ITypedItem.Html*) APIs.
+
+## Lightboxes for Images, Pictures and Media in HTML Contents
+
+The automatic lightbox feature is available for images, pictures and images/pictures in HTML contents.
+
+<div class="gallery">
+  <img src="./assets/blog-app-showing-images.jpg">
+  <img src="./assets/blog-app-lightbox.jpg">
+<div>
+
+## Three Places to Enabled/Disable/Configure Lightboxes
+
+Not every image should be lightboxed, so there are three places to control this:
+
+1. In the code, the API which creates the image can be told to use (or not use) a lightbox <!-- note: 2dm, not really sure if there is a clear way to do this! -->
+1. At the Field Configuration level (usually done by the admin) to set the default for this field.
+1. On each specific image
+
+## Field Configuration
+
+When configuring the field, the admin can set the default for the field, which can be overridden by the editor when editing the content.
+For example, the [Blog App](xref:App.Blog) has Lightboxes enabled on all posts in the latest version like this:
+
+<div class="gallery">
+  <img src="./assets/blog-app-go-to-fields.jpg">
+  <img src="./assets/blog-app-content-defaults.jpg">
+  <img src="./assets/blog-app-auto-gallery.jpg">
+<div>
+
+This will configure the field so all images are lightboxed by default, and treated as a gallery together.
+
+## Configuration per Image
+
+In most cases the field-configuration is all you need.
+But the editor can choose to override this on a per-image basis.
+For example, he/she could configure a lightbox where the field didn't auto-configure it,
+could change the gallery-behavior and/or could disable the lightbox for a specific image.
+
+<div class="gallery">
+  <img src="./assets/blog-app-configure-single-image.jpg">
+<div>
+
+
+---
+
+## History
+
+1. Introduced ca. 2sxc 17
+1. Better documented in 2sxc 18.03

2sxc Docs Generator/pages/basics/images/toc.yml

@@ -3,4 +3,6 @@
 - name: Image Resizer
   topicUid: Basics.ImageResizer.Index
 - name: Image Perfection
-  topicUid: Basics.Images.Perfection.Index
+  topicUid: Basics.Images.Perfection.Index
+- name: Image Lightboxes
+  topicUid: Basics.Images.Lightbox.Index

docs/basics/images/guide/index.html

@@ -251,8 +251,14 @@ <h2 id="part-1-edit-ui--ux">Part 1: Edit UI / UX</h2>
 the designer must activate it on the field. Otherwise the feature is not available.</p>
 <img src="../../../pages/basics/images/guide/assets/image-configuration.jpg" class="full-width" width="100%">
 <p><strong>Important</strong>: The config-button is only available...</p>
+<!-- 1. ...IF it has been enabled -->
 <ol>
-<li>...IF it has been enabled</li>
+<li>If the Razor template uses the automatic APIs to render the image
+<ol>
+<li>When using the new Typed code, using the <code>something.Img(&quot;Image&quot;)</code> API (see <a class="xref" href="../../../api/dot-net/ToSic.Sxc.Data.ITypedItem.html#ToSic_Sxc_Data_ITypedItem_Img_">Img(...)</a> and <a class="xref" href="../../../api/dot-net/ToSic.Sxc.Data.ITypedItem.html#ToSic_Sxc_Data_ITypedItem_Picture_">Picture(...)</a>)</li>
+<li>or using the <a class="xref" href="../../../api/dot-net/ToSic.Sxc.Services.IImageService.html">IImageService</a> (older way)</li>
+</ol>
+</li>
 <li>...and IF the file is an image</li>
 <li>...and IF the file &quot;belongs&quot; to the item being edited<br>
 <em>If the file is a general file from another item or from the root folder, the metadata is not available.</em>
@@ -261,12 +267,25 @@ <h2 id="part-1-edit-ui--ux">Part 1: Edit UI / UX</h2>
 <h2 id="part-2-image-metadata">Part 2: Image Metadata</h2>
 <p>When a user edits the image settings in the UI, the data is stored as <a class="xref" href="../../metadata/index.html">metadata</a> for this image.
 This is important, because generating a perfect <code>&lt;img&gt;</code> or <code>&lt;picture&gt;</code> tag requires this information.</p>
-<h2 id="part-3-dynamic-field">Part 3: Dynamic Field</h2>
+<h2 id="part-3-razor-code-to-generate-html-for-images">Part 3: Razor Code to Generate HTML for Images</h2>
+<h3 id="part-3a-modern-typed-code">Part 3a: Modern Typed Code</h3>
+<p>When using modern typed code, the object containing the data is an <a class="xref" href="../../../api/dot-net/ToSic.Sxc.Data.ITypedItem.html">ITypedItem</a>
+or something which inherits from it.
+In this case, the API will take care of almost everything.
+Just use one of these methods to create the HTML:</p>
+<ul>
+<li><code>thing.Img(&quot;Image&quot;)</code> - for a simple <code>&lt;img&gt;</code> tag</li>
+<li><code>thing.Picture(&quot;Image&quot;)</code> - for a <code>&lt;picture&gt;</code> tag</li>
+</ul>
+<h3 id="part-3b-legacy-code-older-apis">Part 3b: Legacy Code (older APIs)</h3>
+<p>The older API used the <a class="xref" href="../../../api/dot-net/ToSic.Sxc.Services.IImageService.html">IImageService</a> to generate the HTML.
+This in turn needed a <a class="xref" href="../../../api/dot-net/ToSic.Sxc.Data.IField.html">IField</a> object to figure out what to do.</p>
+<h4 id="part-3b-legacy-code---dynamic-field">Part 3b Legacy Code - Dynamic Field</h4>
 <p>If a content item stores the image on a property <code>.Image</code> then something like <code>Content.Image</code> would return <code>/Portal/0/Adam/some-image.jpg</code>.
 In this case, the <a class="xref" href="../../../api/dot-net/ToSic.Sxc.Services.IImageService.html">IImageService</a> cannot find the metadata.</p>
 <p>This is why we need to give it the entire field, not just the value. This is done using <code>Content.Field(&quot;Image&quot;)</code>
 and will get your code a <a class="xref" href="../../../api/dot-net/ToSic.Sxc.Data.IField.html">IDynamicField</a>.</p>
-<h2 id="part-4-imageservice">Part 4: ImageService</h2>
+<h4 id="part-3b-legacy-code---imageservice">Part 3b Legacy Code - ImageService</h4>
 <p>The <a class="xref" href="../../../api/dot-net/ToSic.Sxc.Services.IImageService.html">IImageService</a> will take all the known information and generate an <code>&lt;img&gt;</code> or a <code>&lt;picture&gt;</code> tag.</p>
 <p>This can be used in its default implementation just using <code>.Img(Content.Field)</code> or <code>.Picture(...)</code>.
 In this case is uses the default <code>Content</code> settings (see below).</p>
@@ -282,8 +301,8 @@ <h2 id="part-4-imageservice">Part 4: ImageService</h2>
 <li><a class="xref" href="https://2sxc.org/dnn-tutorials/en/razor/tut/img-picture">ImageService Picture Tutorial</a></li>
 <li><a class="xref" href="https://2sxc.org/dnn-tutorials/en/razor/tut/img-tips">ImageService Guide</a></li>
 </ul>
-<h2 id="part-5-settings-and-recipes">Part 5: Settings and Recipes</h2>
-<p><strong>Settings</strong> are preconfigured parameters how the image is to be resized.
+<h2 id="part-4-settings-and-recipes">Part 4: Settings and Recipes</h2>
+<p><strong>Settings</strong> are pre configured parameters how the image is to be resized.
 They are stored at App, Site, Global or Preset level.</p>
 <p>By default the configuration called <code>Content</code> is used for images in the Content of the page.
 Other settings also exist, such as <code>Lightbox</code> or <code>Screen</code>.
@@ -302,25 +321,15 @@ <h2 id="part-5-settings-and-recipes">Part 5: Settings and Recipes</h2>
 <li>create a new recipe like this: <code>.Recipe(&quot;2x, 3x&quot;)</code> - this is only meant to create a quick recipe with a few variants.</li>
 <li>inherit/expand an existing recipe like this: <code>.Recipe(originalRecipe, ...)</code></li>
 </ul>
-<h2 id="part-6-linkimage-api">Part 6: Link.Image(...) API</h2>
+<h2 id="good-to-know-linkimage-api">Good to Know: Link.Image(...) API</h2>
 <p>In the rare cases where you just need a URL and not the full HTML, check out the <a class="xref" href="../../../net-code/dynamic-code/objects/link.image.html">Link.Image(...) API</a>.</p>
 <p>It is not as powerful as the ImageService but if you only need a URL it may be what you need.</p>
 <p>🎓 <a class="xref" href="https://2sxc.org/dnn-tutorials/en/razor/tut/img-custom">Image Resizer Parameters with Link.Image</a></p>
-<!--
-## Part 3: Special In-Page Toolbar (WIP ca. v13.13)
-
-TODO:
-
----
-
-
-TODO: we're still working on these docs
-
--->
 <hr>
 <h2 id="history">History</h2>
 <ol>
 <li>Guide created for v13.10</li>
+<li>Updated for v16 which introduced the new Typed API</li>
 </ol>
 
 </article>