carousel component

CHANGELOG.md

@@ -7,6 +7,8 @@
      - MySQL's [`JSON_TABLE`](https://dev.mysql.com/doc/refman/8.0/en/json-table-functions.html) table-valued function, that allows easily iterating over json structures
      - MySQL's [`CALL`](https://dev.mysql.com/doc/refman/8.0/en/call.html) statements, to call stored procedures.
      - PostgreSQL `^@` starts-with operator
+ - New [carousel](https://sql.ophir.dev/documentation.sql?component=carousel#component) component to display a carousel of images.
+ - For those who write [custom components](https://sql.ophir.dev/custom_components.sql), a new `@component_index` variable is available in templates to get the index of the current component in the page. This makes it easy to generate unique ids for components.
 
 ## 0.18.2 (2024-01-29)
 

examples/official-site/custom_components.sql

@@ -111,6 +111,14 @@ and SQLPage adds a few more:
 - `each_row`: iterates over the rows of a query result
 - `typeof`: returns the type of a value (`string`, `number`, `boolean`, `object`, `array`, `null`)
 
+### Attributes
+
+In addition to the parameters you pass to your components in your SQL queries,
+SQLPage adds the following attributes to the context of your components:
+
+ - `@component_index` : the index of the current component in the page. Useful to generate unique ids or classes.
+ - `@row_index` : the index of the current row in the current component. Useful to implement special behavior on the first row, for instance.
+
 ## Overwriting the default components
 
 You can overwrite the default components, including the `shell` component,

examples/official-site/sqlpage/migrations/34_carousel.sql

@@ -0,0 +1,136 @@
+INSERT INTO component (name, description, icon, introduced_in_version)
+VALUES (
+        'carousel',
+        'A carousel is used to display multiple pieces of visual content without taking up too much space.',
+        'carousel-horizontal',
+        '0.18.3'
+    );
+INSERT INTO parameter (
+        component,
+        name,
+        description,
+        type,
+        top_level,
+        optional
+    )
+VALUES
+    (
+        'carousel',
+        'title',
+        'A name to display at the top of the carousel.',
+        'TEXT',
+        TRUE,
+        TRUE
+    ),
+    (
+        'carousel',
+        'indicators',
+        'Style of image indicators (square or dot).',
+        'TEXT',
+        TRUE,
+        TRUE
+    ),
+    (
+        'carousel',
+        'vertical',
+        'Whether to use the vertical image indicators.',
+        'BOOLEAN',
+        TRUE,
+        TRUE
+    ),
+    (
+        'carousel',
+        'controls',
+        'Whether to show the control links to go previous or next item.',
+        'BOOLEAN',
+        TRUE,
+        TRUE
+    ),
+    (
+        'carousel',
+        'width',
+        'Width of the component, between 1 and 12. Default is 12.',
+        'NUMBER',
+        TRUE,
+        TRUE
+    ),
+        (
+        'carousel',
+        'auto',
+        'Whether to automatically cycle through the carousel items. Default is false.',
+        'BOOLEAN',
+        TRUE,
+        TRUE
+    ),
+    (
+        'carousel',
+        'center',
+        'Whether to center the carousel.',
+        'BOOLEAN',
+        TRUE,
+        TRUE
+    ),
+    (
+        'carousel',
+        'fade',
+        'Whether to apply the fading effect.',
+        'BOOLEAN',
+        TRUE,
+        TRUE
+    ),
+    (
+        'carousel',
+        'image',
+        'The URL (absolute or relative) of an image to display in the carousel.',
+        'URL',
+        FALSE,
+        FALSE
+    ),
+    (
+        'carousel',
+        'title',
+        'Add caption to the slide.',
+        'TEXT',
+        FALSE,
+        TRUE
+    ),
+    (
+        'carousel',
+        'description',
+        'A short paragraph.',
+        'TEXT',
+        FALSE,
+        TRUE
+    ),
+    (
+        'carousel',
+        'description_md',
+        'A short paragraph formatted using markdown.',
+        'TEXT',
+        FALSE,
+        TRUE
+    );
+-- Insert example(s) for the component
+INSERT INTO example(component, description, properties)
+VALUES (
+        'carousel',
+        'A basic example of carousel',
+        JSON(
+            '[
+                {"component":"carousel","name":"cats1","title":"Famous Database Animals"},
+                {"image":"https://upload.wikimedia.org/wikipedia/commons/thumb/d/d7/Elefantes_africanos_de_sabana_%28Loxodonta_africana%29%2C_Elephant_Sands%2C_Botsuana%2C_2018-07-28%2C_DD_114-117_PAN.jpg/2560px-Elefantes_africanos_de_sabana_%28Loxodonta_africana%29%2C_Elephant_Sands%2C_Botsuana%2C_2018-07-28%2C_DD_114-117_PAN.jpg"},
+                {"image":"https://upload.wikimedia.org/wikipedia/commons/thumb/9/99/Penguin_Island_panorama_with_ferry_and_dolphins_in_foreground%2C_March_2023_06.jpg/1280px-Penguin_Island_panorama_with_ferry_and_dolphins_in_foreground%2C_March_2023_06.jpg"}
+                ]'
+        )
+    ),
+    (
+        'carousel',
+        'An advanced example of carousel with controls',
+        JSON(
+            '[
+                {"component":"carousel","name":"cats2","title":"Cats","width":6,"center":true,"controls":true,"auto":true},
+                {"image":"https://upload.wikimedia.org/wikipedia/commons/thumb/2/29/Cat_Sphynx._Kittens._img_11.jpg/1024px-Cat_Sphynx._Kittens._img_11.jpg","title":"A first cat","description":"The cat (Felis catus), commonly referred to as the domestic cat or house cat, is the only domesticated species in the family Felidae."},
+                {"image":"https://upload.wikimedia.org/wikipedia/commons/thumb/e/ec/Cat_close-up_2004_b.jpg/1280px-Cat_close-up_2004_b.jpg","title":"Another cat"}
+                ]'
+        )
+    );

examples/official-site/sqlpage/migrations/32_shared_id_class_attributes.sql → examples/official-site/sqlpage/migrations/99_shared_id_class_attributes.sql

@@ -17,7 +17,8 @@ FROM (VALUES
     ('timeline', FALSE),
     -- ('title', TRUE),
     ('tracking', TRUE),
-    ('text', TRUE)
+    ('text', TRUE),
+    ('carousel', TRUE)
 );
 
 INSERT INTO parameter(component, top_level, name, description, type, optional) 
@@ -47,6 +48,7 @@ FROM (VALUES
     ('timeline', TRUE),
     ('timeline', FALSE),
     -- ('title', TRUE),
-    ('tracking', TRUE)
+    ('tracking', TRUE),
+    ('carousel', TRUE)
 );
 

sqlpage/templates/carousel.handlebars

@@ -0,0 +1,40 @@
+<div class="card my-2 col-md-{{default width 12}}{{#if center}} mx-auto{{/if}} {{class}}" {{#if id}}id="{{id}}"{{/if}}>
+    <div class="card-body">
+        {{#if title}}
+            <div class="d-flex align-items-center">
+                <div class="subheader">{{title}}</div>
+            </div>
+        {{/if}}
+        <div id="_sqlpage_carousel_{{@component_index}}" class="carousel slide{{#if fade}} carousel-fade{{/if}}" {{#if auto}}data-bs-ride="carousel"{{/if}}>
+            <div class="carousel-indicators{{#if indicators}} carousel-indicators-{{indicators}}{{/if}}{{#if vertical}} carousel-indicators-vertical{{/if}}">
+                {{#each_row}}
+                    <button type="button" data-bs-target="#_sqlpage_carousel_{{@../component_index}}" data-bs-slide-to="{{@row_index}}" {{#if (eq @row_index 0)}}class="active"{{/if}}></button>
+                    {{#delay}}
+                        {{flush_delayed}}
+                        <div class="carousel-item {{#if (eq @row_index 0)}}active{{/if}}">
+                            <img class="d-block w-100" alt="{{image}}" src="{{image}}" />
+                            {{#if title}}
+                            <div class="carousel-caption-background d-none d-md-block"></div>
+                            <div class="carousel-caption d-none d-md-block">
+                                <h5>{{title}}</h5>
+                                {{#if description_md}}<p>{{{markdown description_md}}}</p>{{else}}{{#if description}}<p>{{description}}</p>{{/if}}{{/if}}
+                            </div>
+                            {{/if}}
+                        </div>
+                    {{/delay}}
+                {{/each_row}}
+            </div>
+            <div class="carousel-inner">{{flush_delayed}}</div>
+        </div>
+    </div>
+    {{#if controls}}
+        <a class="carousel-control-prev" data-bs-target="#_sqlpage_carousel_{{@component_index}}" role="button" data-bs-slide="prev">
+            <span class="carousel-control-prev-icon" aria-hidden="true"></span>
+            <span class="visually-hidden">Previous</span>
+        </a>
+        <a class="carousel-control-next" data-bs-target="#_sqlpage_carousel_{{@component_index}}" role="button" data-bs-slide="next">
+            <span class="carousel-control-next-icon" aria-hidden="true"></span>
+            <span class="visually-hidden">Next</span>
+        </a>
+    {{/if}}
+</div>