added carousel component (#104)

docs/components-carousel.md

@@ -0,0 +1,89 @@
+# Components
+
+This theme ships some components (as twig macros) that hide the complexity of rendering the same elements over and over again with the correct HTML.
+
+See Tabler documentation at https://preview.tabler.io/carousel.html
+
+## Carousel
+
+### Parameters
+`carousel()` macro, waits for 2 parameters:
+
+| Parameter | Description                |   Type    | Default |
+|:---------:|:---------------------------|:---------:|:-------:|
+|   items   | Array of [Item](#Step)     |  `array`  |  `[]`   |
+|  options  | [Options](#Options) object | `object`  |  `{}`   |
+
+#### Item
+
+`item()` parameter requires either the `image` or `customContent` parameter:
+
+|   Parameter   | Description                                    |     Type     | Default |
+|:-------------:|------------------------------------------------|:------------:|:-------:|
+|     image     | Path to an image                               |   `string`   |         |
+| customContent | Custom html content. overrides `image` if set. | `html (raw)` | `null`  |
+|     title     | Item title.                                    |   `string`   | `null`  |
+|  description  | Item description.                              |   `string`   | `null`  |
+
+#### Options
+
+|       Parameter       | Description                                                              |   Type    |       Default       |
+|:---------------------:|--------------------------------------------------------------------------|:---------:|:-------------------:|
+|          id           | Custom `id` to apply to the carousel                                     |  `mixed`  |   `rand(Number)`    |
+|      extraClass       | Add extra classes on steps container                                     | `string`  |   _empty string_    |
+|       interval        | Interval in milliseconds to change the slides                            |   `int`   |        5000         |
+|         touch         | Support touch input (see Bootstrap docs)                                 | `boolean` |       `true`        |
+|         pause         | Auto stop sliding (see Bootstrap docs)                                   |  `mixed`  |       `false`       |
+|         wrap          | Restart again (see Bootstrap docs)                                       | `boolean` |       `true`        |
+|       controls        | Show controls                                                            | `boolean` |       `false`       |
+|  captionCustomClass   | Apply custom class to caption                                            | `string`  | `d-none d-md-block` |
+|   captionBackground   | Show caption background                                                  | `boolean` |       `true`        |
+|      indicators       | Show indicators                                                          | `boolean` |       `true`        |
+|    indicatorsType     | Set indicators type (allowed values: `dots`, `thumbs`)                   | `string`  |   _empty string_    |
+|    indicatorsRatio    | Set indicators ratio (see Tabler docs)                                   | `string`  |   _empty string_    |
+| indicatorsOrientation | Set indicators orientation (see Tabler docs, allowed values: `vertical`) | `string`  |   _empty string_    |
+
+Links:
+
+- [Tabler docs](https://preview.tabler.io/docs/carousel.html) 
+- [Bootstrap docs](https://getbootstrap.com/docs/5.2/components/carousel/#options) 
+
+### Usage
+
+```twig
+{% from '@Tabler/components/carousel.html.twig' import carousel %}
+
+{% set items = [
+    {
+        'image': 'https://via.placeholder.com/640x360/1485bc/ffffff?text=Image+0',
+    },
+    {
+        'customContent': '<h1>Hello World</h1>',
+    },
+    {
+        'image': 'https://via.placeholder.com/640x360/9dbf00/ffffff?text=Image+1',
+        'title': 'SOME Fancy Title',
+        'description': 'Lorem Ipsum NO HTML',
+    },
+    {
+        'image': 'https://via.placeholder.com/640x360/bc147a/ffffff?text=Image+2',
+    },
+    {
+        'image': 'https://via.placeholder.com/640x360/1454bc/ffffff?text=Image+3',
+    }
+] %}
+
+{% set options = {
+    'interval': false,
+    'controls': true,
+    'indicators': true,
+    'indicatorsType': 'thumbs',
+    'indicatorsOrientation': 'vertical',
+} %}
+
+{ { carousel(items, options) } }
+```
+
+## Next steps
+
+Please go back to the [Tabler bundle documentation](index.md) to find out more about using the theme.

docs/index.md

@@ -12,14 +12,15 @@ If you cannot find the needed information in this list of topics, please create
 
 Components (Twig macros):
 
-* [Buttons](components-buttons.md)
-* [Timeline](components-timeline.md)
 * [Breadcrumb](components-breadcrumb.md)
+* [Buttons](components-buttons.md)
+* [Callout](components-callout.md)
+* [Carousel](components-carousel.md)
 * [Status](components-status.md)
-* [Status Dot](components-status-dot.md)
+* [Status dot](components-status-dot.md)
 * [Status indicator](components-status-indicator.md)
 * [Steps](components-steps.md)
-* [Callout](components-callout.md)
+* [Timeline](components-timeline.md)
 
 Components (Twig Embeds):
 * [Modal](embeds-modal.md)

templates/components/carousel.html.twig

@@ -0,0 +1,86 @@
+{% macro carousel(items, options) %}
+    {% set _id = options.id ?? ('carousel-' ~ random(0, 999)) %}
+    {% set _extraClass = options.extraClass ?? '' %}
+
+    {% set _interval = options.interval ?? 5000 %}
+    {% set _touch_enabled = options.touch ?? true %}
+    {% set _pause = options.pause ?? false %}
+    {% set _wrap = options.wrap ?? true %}
+
+    {% set _show_controls = options.controls ?? false %}
+
+    {% set _caption_class = options.captionCustomClass ?? 'd-none d-md-block' %}
+    {% set _show_caption_background = options.captionBackground ?? true %}
+
+    {% set _show_indicators = options.indicators ?? true %}
+    {% set _indicators_type = options.indicatorsType ?? '' %}
+    {% set _indicators_ratio = options.indicatorsRatio ?? '' %}
+    {% set _indicators_orientation = options.indicatorsOrientation ?? 'horizontal' %}
+
+    <div id="{{ _id }}" class="carousel slide {{ _extraClass }}" data-bs-ride="carousel"
+         data-bs-interval="{{ _interval == false ? 'false' : _interval }}"
+         data-bs-touch="{{ _touch_enabled ? 'true' : 'false' }}"
+         data-bs-pause="{{ _pause == true ? 'true' : 'hover' }}" data-bs-wrap="{{ _wrap ? 'true' : 'false' }}">
+        {% if _show_indicators %}
+            {{ _self.carousel_indicators(items, _id, _indicators_type, _indicators_orientation, _indicators_ratio) }}
+        {% endif %}
+        {% if _show_controls %}
+            <button class="carousel-control-prev" type="button" data-bs-target="#{{ _id }}" data-bs-slide="prev">
+                <span class="carousel-control-prev-icon" aria-hidden="true"></span>
+            </button>
+            <button class="carousel-control-next" type="button" data-bs-target="#{{ _id }}" data-bs-slide="next">
+                <span class="carousel-control-next-icon" aria-hidden="true"></span>
+            </button>
+        {% endif %}
+        <div class="carousel-inner">
+            {% for item in items %}
+                {% set _has_custom = item.customContent is defined %}
+                <div class="carousel-item {% if loop.first %}active{% endif %}">
+                {% if _has_custom %}
+                    {# This is useless: breaks contents and no additional value as making everything same size is cumbersome #}
+                    {{ item.customContent | raw }}
+                {% else %}
+                    <img src="{{ item.image }}" class="d-block w-100" alt="{% if item.title is defined %}{{ item.title }}{% endif %}">
+                    {% if item.title is defined or item.description is defined %}
+                        {% if _show_caption_background %}
+                            <div class="carousel-caption-background {{ _caption_class }}"></div>
+                        {% endif %}
+                        <div class="carousel-caption {{ _caption_class }}">
+                            {% if item.title %}
+                                <h3>{{ item.title }}</h3>
+                            {% endif %}
+                            {% if item.description %}
+                                {{ item.description }}
+                            {% endif %}
+                        </div>
+                    {% endif %}
+                {% endif %}
+                </div>
+            {% endfor %}
+        </div>
+    </div>
+{% endmacro %}
+
+{% macro carousel_indicators(items, id, type, orientation, ratio) %}
+    {% set _typeClass = '' %}
+    {% if type == 'dots' %}{% set _typeClass = 'carousel-indicators-dot' %}{% endif %}
+    {% if type == 'thumbs' %}{% set _typeClass = 'carousel-indicators-thumb' %}{% endif %}
+
+    {% set _orientationClass = '' %}
+    {% if orientation == 'vertical' %}{% set _orientationClass = 'carousel-indicators-vertical' %}{% endif %}
+    {% set _ratio = 'ratio ' ~ (ratio == '' ? 'ratio-1x1' : ratio) %}
+
+    <div class="carousel-indicators {{ _typeClass }} {{ _orientationClass }}">
+        {% for item in items %}
+            {% set _item_class = loop.first ? 'active' : '' %}
+            {% set _item_style = '' %}
+            {% if type == 'thumbs' %}
+                {% set _item_image = item.image ?? '' %}
+                {% set _item_class = _item_class ~ ' ' ~ _ratio %}
+                {% set _item_style = 'background-image: url(\'' ~ _item_image ~ '\');' %}
+            {% endif %}
+            <button type="button" data-bs-target="#{{ id }}" data-bs-slide-to="{{ loop.index - 1 }}"
+                    class="{{ _item_class }}" style="{{ _item_style }}"></button>
+        {% endfor %}
+    </div>
+{% endmacro %}