diff --git a/docs/components-carousel.md b/docs/components-carousel.md new file mode 100644 index 0000000..d3dea13 --- /dev/null +++ b/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': '

Hello World

', + }, + { + '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. diff --git a/docs/index.md b/docs/index.md index b3cb689..3136a42 100644 --- a/docs/index.md +++ b/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) diff --git a/templates/components/carousel.html.twig b/templates/components/carousel.html.twig new file mode 100644 index 0000000..17956d8 --- /dev/null +++ b/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' %} + + +{% 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) %} + + +{% endmacro %}