www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/slick/slick.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks and API provided by the Slick module.
   6  */
   7
   8 /**
   9  * @defgroup slick_api Slick API
  10  * @{
  11  * Information about the Slick usages.
  12  *
  13  * Modules may implement any of the available hooks to interact with Slick.
  14  *
  15  * Slick may be configured using the web interface via sub-modules.
  16  * However below is a few sample coded ones. The simple API is to achieve
  17  * consistent markups working for various skins, and layouts for both coded
  18  * and sub-modules implementations.
  19  *
  20  * The expected parameters are:
  21  *   - items: A required array of slick contents: text, image or media.
  22  *   - options: An optional array of key:value pairs of custom JS options.
  23  *   - optionset: An optional optionset object to avoid multiple invocations.
  24  *   - settings: An array of key:value pairs of HTML/layout related settings
  25  *     which may contain optionset ID if no optionset above is provided.
  26  *
  27  * @see \Drupal\slick\Plugin\Field\FieldFormatter\SlickImageFormatter
  28  * @see \Drupal\slick_views\Plugin\views\style\SlickViews
  29  *
  30  * @section sec_quick Quick sample #1
  31  *
  32  * Returns the renderable array of a slick instance.
  33  * @code
  34  * function my_module_render_slick() {
  35  *   // Invoke the plugin class, or use a DI service container accordingly.
  36  *   $slick = \Drupal::service('slick.manager');
  37  *
  38  *   // Access the formatter service for image-related methods:
  39  *   $formatter = \Drupal::service('slick.formatter');
  40  *
  41  *   $build = [];
  42  *
  43  *   // Caption contains: alt, data, link, overlay, title.
  44  *   // Each item has keys: slide, caption, settings.
  45  *   $items[] = [
  46  *     // Use $formatter->getImage($element) to have lazyLoad where $element
  47  *     // contains:
  48  *     // item: Drupal\image\Plugin\Field\FieldType\ImageItem.
  49  *     'slide'   => '<img src="https://drupal.org/files/One.gif" />',
  50  *     'caption' => ['title' => t('Description #1')],
  51  *   ];
  52  *
  53  *   $items[] = [
  54  *     'slide'   => '<img src="https://drupal.org/files/Two.gif" />',
  55  *     'caption' => ['title' => t('Description #2')],
  56  *   ];
  57  *
  58  *   $items[] = [
  59  *     'slide'   => '<img src="https://drupal.org/files/Three.gif" />',
  60  *     'caption' => ['title' => t('Description #3')],
  61  *   ];
  62  *
  63  *   // Pass the $items to the array.
  64  *   $build['items'] = $items;
  65  *
  66  *   // If no optionset name is provided via $build['settings'], slick will
  67  *   // fallback to 'default'.
  68  *   // Optionally override 'default' optionset with custom JS options.
  69  *   $build['options'] = [
  70  *     'autoplay' => TRUE,
  71  *     'dots'     => TRUE,
  72  *     'arrows'   => FALSE,
  73  *   ];
  74  *
  75  *   // Build the slick.
  76  *   $element = $slick->build($build);
  77  *
  78  *   // Prepare $variables to pass into a .twig.html file.
  79  *   $variables['slick'] = $element;
  80  *
  81  *   // Render the slick at a .twig.html file.
  82  *   // {{ slick }}
  83  *   // Or simply return the $element if a renderable array is expected.
  84  *   return $element;
  85  * }
  86  * @endcode
  87  * @see \Drupal\slick\SlickManager::build()
  88  * @see template_preprocess_slick_wrapper()
  89  * @see template_preprocess_slick()
  90  *
  91  * @section sec_detail Detailed sample #2
  92  *
  93  * This can go to some hook_preprocess() of a target html.twig, or any relevant
  94  * PHP file.
  95  *
  96  * The goal is to create a vertical newsticker, or tweets, with pure text only.
  97  * First, create an unformatted Views block, says 'Ticker' containing ~ 10
  98  * titles, or any data for the contents -- using EFQ, or static array will do.
  99  *
 100  * Returns the renderable array of a slick instance.
 101  * @code
 102  * function my_module_render_slick_detail() {
 103  *   // Invoke the plugin class, or use a DI service container accordingly.
 104  *   $slick = \Drupal::service('slick.manager');
 105  *
 106  *   // Access the formatter service for image related methods:
 107  *   $formatter = \Drupal::service('slick.formatter');
 108  *
 109  *   $build = [];
 110  *
 111  *   // 1.
 112  *   // Optional $settings, can be removed.
 113  *   // Provides HTML settings with optionset name and ID, none of JS related.
 114  *   // To add JS key:value pairs, use #options below instead.
 115  *   // @see \Drupal\slick\SlickDefault for most supported settings.
 116  *   $build['settings'] = [
 117  *     // Optional optionset name, otherwise fallback to default.
 118  *     // 'optionset' => 'blog',
 119  *     // Optional skin name fetched from hook_slick_skins_info(), else none.
 120  *     // 'skin' => 'fullwidth',
 121  *     // Define the main ID. The rest are managed by the module.
 122  *     // If you provide ID, be sure unique per instance as it is cached.
 123  *     // Leave empty to be provided by the module.
 124  *     'id' => 'slick-ticker',
 125  *
 126  *     // Define cache max-age, default to -1 (Cache::PERMANENT) to permanently
 127  *     // cache the results. Hence a 1 hour is passed. Be sure it is an integer!
 128  *     'cache' => 3600,
 129  *   ];
 130  *
 131  *   // 3.
 132  *   // Obligatory #items, as otherwise empty slick.
 133  *   // Prepare #items, note the 'slide' key is to hold the actual slide
 134  *   // which can be pure and simple text, or any image/media file.
 135  *   // Meaning $rows can be text only, or image/audio/video, or a combination
 136  *   // of both.
 137  *   // To add caption/overlay, use 'caption' key with the supported sub-keys:
 138  *   // alt, data, link, overlay, title for complex content.
 139  *   // Sanitize each sub-key content accordingly.
 140  *   // @see template_preprocess_slick_slide() for more info.
 141  *   $items = [];
 142  *   foreach ($rows as $key => $row) {
 143  *     // Each item has keys: slide, caption, settings.
 144  *     $items[] = [
 145  *       'slide' => $row,
 146  *
 147  *       // Optional caption contains: alt, data, link, overlay, title.
 148  *       // If the above slide is an image, to add text caption, use:
 149  *       'caption' => ['title' => 'some-caption data'],
 150  *
 151  *       // Optional slide settings to manipulate layout, can be removed.
 152  *       // Individual slide supports some useful settings like layout, classes,
 153  *       // etc.
 154  *       // Meaning each slide can have different layout, or classes.
 155  *       // @see src/Plugin/Field/README.txt
 156  *       'settings' => [
 157  *
 158  *         // Optionally add a custom layout, can be a static uniform value, or
 159  *         // dynamic one based on the relevant field value.
 160  *         // @see src/Plugin/Field/README.txt for the supported layout keys.
 161  *         'layout' => 'bottom',
 162  *
 163  *         // Optionally add a custom class, can be a static uniform class, or
 164  *         // dynamic one based on the relevant field value.
 165  *         'class' => 'slide--custom-class--' . $key,
 166  *       ],
 167  *     ];
 168  *   }
 169  *
 170  *   // Pass the $items to the array.
 171  *   $build['items'] = $items;
 172  *
 173  *   // 4.
 174  *   // Optional specific JS options, to re-use one optionset, can be removed.
 175  *   // Play with speed and options to achieve desired result.
 176  *   // @see config/install/slick.optionset.default.yml
 177  *   $build['options'] = [
 178  *     'arrows'    => FALSE,
 179  *     'autoplay'  => TRUE,
 180  *     'vertical'  => TRUE,
 181  *     'draggable' => FALSE,
 182  *   ];
 183  *
 184  *   // 5.
 185  *   // Build the slick with the arguments as described above.
 186  *   $element = $slick->build($build);
 187  *
 188  *   // Prepare $variables to pass into a .twig.html file.
 189  *  $variables['slick'] = $element;
 190  *
 191  *   // Render the slick at a .twig.html file.
 192  *   // {{ slick }}
 193  *   // Or simply return the $element if a renderable array is expected.
 194  *   return $element;
 195  * }
 196  * @endcode
 197  * @see \Drupal\slick\SlickManager::build()
 198  * @see template_preprocess_slick_wrapper()
 199  *
 200  * @section sec_asnavfor AsNavFor sample #3
 201  *
 202  * The only requirement for asNavFor is optionset and optionset_thumbnail IDs:
 203  * @code
 204  * $build['settings']['optionset'] = 'optionset_name';
 205  * $build['settings']['optionset_thumbnail'] = 'optionset_thumbnail_name';
 206  * @endcode
 207  *
 208  * The rest are optional, and will fallback to default:
 209  *   - $build['settings']['optionset_thumbnail'] = 'optionset_thumbnail_name';
 210  *     Defined at the main settings.
 211  *
 212  *   - $build['settings']['id'] = 'slick-asnavfor';
 213  *     Only main display ID is needed. The thumbnail ID will be
 214  *     automatically created: 'slick-asnavfor-thumbnail', including the content
 215  *     attributes accordingly. If none provided, will fallback to incremented
 216  *     ID.
 217  *
 218  * See the HTML structure below to get a clear idea.
 219  *
 220  * 1. Main slider:
 221  * @code
 222  *   <div id="slick-asnavfor" class="slick">
 223  *     <div class="slick__slider slick-initialized slick-slider">
 224  *       <div class="slick__slide"></div>
 225  *     </div>
 226  *   </div>
 227  * @endcode
 228  * 2. Thumbnail slider:
 229  * @code
 230  *   <div id="slick-asnavfor-thumbnail" class="slick">
 231  *     <div class="slick__slider slick-initialized slick-slider">
 232  *       <div class="slick__slide"></div>
 233  *     </div>
 234  *   </div>
 235  * @endcode
 236  * The asnavfor targets are the 'slick-initialized' attributes, and managed by
 237  * the module automatically when using SlickManager::build().
 238  *
 239  * Returns the renderable array of slick instances.
 240  * @code
 241  * function my_module_render_slick_asnavfor() {
 242  *   // Invoke the plugin class, or use a DI service container accordingly.
 243  *   $slick = \Drupal::service('slick.manager');
 244  *
 245  *   // Access the formatter service for image related methods:
 246  *   $formatter = \Drupal::service('slick.formatter');
 247  *
 248  *   $build = [];
 249  *
 250  *   // 1. Main slider ---------------------------------------------------------
 251  *   // Add the main display items.
 252  *   $build['items'] = [];
 253  *
 254  *   $images = [1, 2, 3, 4, 6, 7];
 255  *   foreach ($images as $key) {
 256  *     // Each item has keys: slide, caption, settings.
 257  *     $build['items'][] = [
 258  *
 259  *       // Use $formatter->getImage($element) to have lazyLoad where $element
 260  *       // contains:
 261  *       // item: Drupal\image\Plugin\Field\FieldType\ImageItem.
 262  *       'slide'   => '<img src="/path/to/image-0' . $key . '.jpg">',
 263  *
 264  *       // Main caption contains: alt, data, link, overlay, title keys which
 265  *       // serve the purpose to have consistent markups and skins without
 266  *       // bothering much nor remembering what HTML tags and where to place to
 267  *       // provide for each purpose cosnsitently. CSS will do layout regardless
 268  *       // HTML composition.
 269  *       // If having more complex caption data, use 'data' key instead.
 270  *       // If the common layout doesn't satisfy the need, just override twig.
 271  *       'caption' => ['title' => 'Description #' . $key],
 272  *     ];
 273  *   }
 274  *
 275  *   // Optionally override the optionset.
 276  *   $build['options'] = [
 277  *     'arrows'        => FALSE,
 278  *     'centerMode'    => TRUE,
 279  *     'centerPadding' => '',
 280  *   ];
 281  *
 282  *   // Satisfy the asnavfor main settings.
 283  *   // @see \Drupal\slick\SlickDefault for most supported settings.
 284  *   $build['settings'] = [
 285  *     // The only required is 'optionset_thumbnail'.
 286  *     // Define both main and thumbnail optionset names at the main display.
 287  *     'optionset' => 'optionset_main_name',
 288  *     'optionset_thumbnail' => 'optionset_thumbnail_name',
 289  *
 290  *     // The rest is optional, just FYI.
 291  *     'id' => 'slick-asnavfor',
 292  *     'skin' => 'skin-main-name',
 293  *     'skin_thumbnail' => 'skin-thumbnail-name',
 294  *   ];
 295  *
 296  *   // 2. Thumbnail slider ----------------------------------------------------
 297  *   // The thumbnail array is grouped by 'thumb'.
 298  *   $build['thumb'] = ['items' => []];
 299  *   foreach ($images as $key) {
 300  *     // Each item has keys: slide, caption, settings.
 301  *     $build['thumb']['items'][] = [
 302  *       // Use $formatter->getThumbnail($settings) where $settings contain:
 303  *       // uri, image_style, height, width, alt, title.
 304  *       'slide'   => '<img src="/path/to/image-0' . $key . '.jpg">',
 305  *
 306  *       // Thumbnail caption accepts direct markup or custom renderable array
 307  *       // without any special key to be simple as much as complex.
 308  *       // Think Youtube playlist with scrolling nav: thumbnail, text, etc.
 309  *       'caption' => ['#markup' => 'Description #' . $key],
 310  *     ];
 311  *   }
 312  *
 313  *   // Optionally override 'optionset_thumbnail_name' with custom JS options.
 314  *   $build['thumb']['options'] = [
 315  *     'arrows'        => TRUE,
 316  *     'centerMode'    => TRUE,
 317  *     'centerPadding' => '10px',
 318  *
 319  *     // Be sure to have multiple slides for the thumbnail, otherwise nonsense.
 320  *     'slidesToShow'  => 5,
 321  *   ];
 322  *
 323  *   // Build the slick once.
 324  *   $element = $slick->build($build);
 325  *
 326  *   // Prepare variables to pass into a .twig.html file.
 327  *   $variables['slick'] = $element;
 328  *
 329  *   // Render the slick at a .twig.html file.
 330  *   // {{ slick }}
 331  *   // Or simply return the $element if a renderable array is expected.
 332  *   return $element;
 333  * }
 334  * @endcode
 335  * @see \Drupal\slick\SlickManager::build()
 336  * @see template_preprocess_slick_wrapper()
 337  *
 338  * @section sec_skin Registering Slick skins
 339  *
 340  * To register a skin, implement hook_slick_skins_info() in a module file, and
 341  * defines skins at the registered class which implements SlickSkinInterface.
 342  *
 343  * The class must implement \Drupal\slick\SlickSkinInterface, and it has 3
 344  * supported methods: ::skins(), ::dots(), ::arrows() to have skin options for
 345  * main/thumbnail/overlay/nested displays, dots, and arrows skins respectively.
 346  * The declared skins will be available for custom coded, or UI selections.
 347  *
 348  * @see \Drupal\slick\SlickSkinInterface
 349  * @see \Drupal\slick_example\SlickExampleSkin
 350  * @see \Drupal\slick_extras\SlickExtrasSkin
 351  *
 352  * Add the needed methods accordingly.
 353  * This can be used to register skins for the Slick. Skins will be
 354  * available when configuring the Optionset, Field formatter, or Views style,
 355  * or custom coded slicks.
 356  *
 357  * Slick skins get a unique CSS class to use for styling, e.g.:
 358  * If your skin name is "my_module_slick_carousel_rounded", the CSS class is:
 359  * slick--skin--my-module-slick-carousel-rounded
 360  *
 361  * A skin can specify CSS and JS files to include when Slick is displayed,
 362  * except for a thumbnail skin which accepts CSS only.
 363  *
 364  * Each skin supports 5 keys:
 365  * - name: The human readable name of the skin.
 366  * - description: The description about the skin, for help and manage pages.
 367  * - css: An array of CSS files to attach.
 368  * - js: An array of JS files to attach, e.g.: image zoomer, reflection, etc.
 369  * - group: A string grouping the current skin: main, thumbnail.
 370  * - provider: A module name registering the skins.
 371  *
 372  * @section sec_skins Defines the Slick main and thumbnail skins
 373  *
 374  * @code
 375  * public function skins() {
 376  *   $theme_path = base_path() . drupal_get_path('theme', 'my_theme');
 377  *
 378  *   return [
 379  *     'skin_name' => [
 380  *       // Human readable skin name.
 381  *       'name' => 'Skin name',
 382  *
 383  *       // Description of the skin.
 384  *       'description' => t('Skin description.'),
 385  *
 386  *       // Group skins to reduce confusion on form selection: main, thumbnail.
 387  *       'group' => 'main',
 388  *
 389  *       // Optional module name to prefix the library name.
 390  *       'provider' => 'my_module',
 391  *
 392  *       // Custom assets to be included within a skin, e.g.: Zoom, Reflection,
 393  *       // Slicebox, etc.
 394  *       'css' => [
 395  *         'theme' => [
 396  *           // Full path to a CSS file to include with the skin.
 397  *           $theme_path . '/css/my-theme--slider.css' => [],
 398  *           $theme_path . '/css/my-theme--carousel.css' => [],
 399  *         ],
 400  *       ],
 401  *       'js' => [
 402  *         // Full path to a JS file to include with the skin.
 403  *         $theme_path . '/js/my-theme--slider.js' => [],
 404  *         $theme_path . '/js/my-theme--carousel.js' => [],
 405  *         // To act on afterSlick event, or any other slick events,
 406  *         // put a lighter weight before slick.load.min.js (0).
 407  *         $theme_path . '/js/slick.skin.menu.min.js' => ['weight' => -2],
 408  *       ],
 409  *
 410  *       // Alternatively, add extra library dependencies for re-usable
 411  *       // libraries. These must be registered as module libraries first.
 412  *       // Use above CSS and JS directly if reluctant to register libraries.
 413  *       'dependencies' => [
 414  *         'my_module/d3',
 415  *         'my_module/slicebox',
 416  *         'my_module/zoom',
 417  *       ],
 418  *
 419  *       // Add custom options to be merged into [data-slick] attribute.
 420  *       // Below is a sample of Slicebox options merged into Slick options.
 421  *       // These options later can be accessed in the custom JS acccordingly.
 422  *       'options' => [
 423  *         'orientation'     => 'r',
 424  *         'cuboidsCount'    => 7,
 425  *         'maxCuboidsCount' => 7,
 426  *         'cuboidsRandom'   => TRUE,
 427  *         'disperseFactor'  => 30,
 428  *         'itemAnimation'   => TRUE,
 429  *         'perspective'     => 1300,
 430  *         'reflection'      => TRUE,
 431  *         'effect'          => ['slicebox', 'zoom'],
 432  *       ],
 433  *     ],
 434  *   ];
 435  * }
 436  * @endcode
 437  *
 438  * @section sec_dots Defines Slick dot skins
 439  *
 440  * The provided dot skins will be available at sub-module UI form.
 441  * A skin dot named 'hop' will have a class 'slick-dots--hop' for the UL.
 442  *
 443  * The array is similar to the self::skins(), excluding group, JS.
 444  * @code
 445  * public function dots() {
 446  *   // Create an array of dot skins.
 447  *   return [];
 448  * }
 449  * @endcode
 450  *
 451  * @section sec_arrows Defines Slick arrow skins
 452  *
 453  * The provided arrow skins will be available at sub-module UI form.
 454  * A skin arrow 'slit' will have a class 'slick__arrow--slit' for the NAV.
 455  *
 456  * The array is similar to the self::skins(), excluding group, JS.
 457  *
 458  * @return array
 459  *   The array of the arrow skins.
 460  * @code
 461  * public function arrows() {
 462  *   // Create an array of arrow skins.
 463  *   return [];
 464  * }
 465  * @endcode
 466  * @}
 467  */
 468
 469 /**
 470  * @addtogroup hooks
 471  * @{
 472  */
 473
 474 /**
 475  * Registers a class that should hold skin definitions.
 476  *
 477  * @deprecated, will be removed anytime when a core solution is available.
 478  * @see #2233261
 479  * Postponed till D9.
 480  *
 481  * @see slick_hook_info()
 482  * @see slick_example.module
 483  * @see slick_extras.module
 484  * @see \Drupal\slick\SlickSkinInterface
 485  * @see sec_skin
 486  *
 487  * @ingroup slick_api
 488  */
 489 function hook_slick_skins_info() {
 490   return '\Drupal\my_module\MyModuleSlickSkin';
 491 }
 492
 493 /**
 494  * Modifies overridable options to re-use one optionset.
 495  *
 496  * @see \Drupal\slick\Form\SlickAdmin::getOverridableOptions()
 497  *
 498  * @ingroup slick_api
 499  */
 500 function hook_slick_overridable_options_info_alter(&$options) {
 501   // Adds RTL option to Slick field formatters, or Slick Views UI.
 502   $options['rtl'] = t('RTL');
 503 }
 504
 505 /**
 506  * @} End of "addtogroup hooks".
 507  */