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

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks and API provided by the Blazy module.
   6  */
   7
   8 /**
   9  * @defgroup blazy_api Blazy API
  10  * @{
  11  * Information about the Blazy usages.
  12  *
  13  * Modules may implement any of the available hooks to interact with Blazy.
  14  * Blazy may be configured using the web interface using formatters, or Views.
  15  * However below is a few sample coded ones as per Blazy RC2+.
  16  *
  17  * A single image sample.
  18  * @code
  19  * function my_module_render_blazy() {
  20  *   $settings = [
  21  *     // URI is stored in #settings property so to allow traveling around video
  22  *     // and lightboxes before being passed into theme_blazy().
  23  *     'uri' => 'public://logo.jpg',
  24  *
  25  *     // Explicitly request for Blazy.
  26  *     // This allows Slick lazyLoad to not load Blazy.
  27  *     'lazy' => 'blazy',
  28  *
  29  *     // Optionally provide an image style:
  30  *     'image_style' => 'thumbnail',
  31  *   ];
  32  *
  33  *   $build = [
  34  *     '#theme'    => 'blazy',
  35  *     '#settings' => $settings,
  36  *
  37  *     // Or below for clarity:
  38  *     '#settings' => ['uri' => 'public://logo.jpg', 'lazy' => 'blazy'],
  39  *
  40  *     // Pass custom attributes into the same #item_attributes property as
  41  *     // Blazy formatters so to respect external modules like RDF, etc. without
  42  *     // extra property. The regular #attributes property is reserved by Blazy
  43  *     // container which holds either IMG, icons, or iFrame. Meaning Blazy is
  44  *     // not just IMG.
  45  *     '#item_attributes' => [
  46  *       'alt'   => t('Thumbnail'),
  47  *       'title' => t('Thumbnail title'),
  48  *       'width' => 120,
  49  *     ],
  50  *
  51  *     // Finally load the library, or include it into a parent container.
  52  *     '#attached' => ['library' => ['blazy/load']],
  53  *   ];
  54  *
  55  *   return $build;
  56  * }
  57  * @endcode
  58  * @see \Drupal\blazy\Blazy::buildAttributes()
  59  * @see \Drupal\blazy\Dejavu\BlazyDefault::imageSettings()
  60  *
  61  * A multiple image sample.
  62  *
  63  * For advanced usages with multiple images, and a few Blazy features such as
  64  * lightboxes, lazyloaded images, or iframes, including CSS background and
  65  * aspect ratio, etc.:
  66  *   o Invoke blazy.manager, and or blazy.formatter.manager, services.
  67  *   o Use \Drupal\blazy\BlazyManager::getImage() method to work with images and
  68  *     pass relevant settings which request for particular Blazy features
  69  *     accordingly.
  70  *   o Use \Drupal\blazy\BlazyManager::attach() to load relevant libraries.
  71  * @code
  72  * function my_module_render_blazy_multiple() {
  73  *   // Invoke the plugin class, or use a DI service container accordingly.
  74  *   $manager = \Drupal::service('blazy.manager');
  75  *
  76  *   $settings = [
  77  *     // Explicitly request for Blazy library.
  78  *     // This allows Slick lazyLoad, or text formatter, to not load Blazy.
  79  *     'blazy' => TRUE,
  80  *
  81  *     // Supported media switcher options dependent on available modules:
  82  *     // colorbox, media (Image to iframe), photobox.
  83  *     'media_switch' => 'media',
  84  *   ];
  85  *
  86  *   // Build images.
  87  *   $build = [
  88  *     // Load images via $manager->getImage().
  89  *     // See above ...Formatter::buildElements() for consistent samples.
  90  *   ];
  91  *
  92  *   // Finally attach libraries as requested via $settings.
  93  *   $build['#attached'] = $manager->attach($settings);
  94  *
  95  *   return $build;
  96  * }
  97  * @endcode
  98  * @see \Drupal\blazy\Plugin\Field\FieldFormatter\BlazyFormatterTrait::buildElements()
  99  * @see \Drupal\blazy\Plugin\Field\FieldFormatter\BlazyVideoFormatter::buildElements()
 100  * @see \Drupal\gridstack\Plugin\Field\FieldFormatter\GridStackFileFormatterBase::buildElements()
 101  * @see \Drupal\slick\Plugin\Field\FieldFormatter\SlickFileFormatterBase::buildElements()
 102  * @see \Drupal\blazy\BlazyManager::getImage()
 103  * @see \Drupal\blazy\Dejavu\BlazyDefault::imageSettings()
 104  *
 105  *
 106  * Pre-render callback sample to modify/ extend Blazy output.
 107  * @code
 108  * function my_module_pre_render(array $image) {
 109  *   $settings = isset($image['#settings']) ? $image['#settings'] : [];
 110  *
 111  *   // Video's HREF points to external site, adds URL to local image.
 112  *   if (!empty($settings['box_url']) && !empty($settings['embed_url'])) {
 113  *     $image['#url_attributes']['data-box-url'] = $settings['box_url'];
 114  *   }
 115  *
 116  *   return $image;
 117  * }
 118  * @endcode
 119  * @see hook_blazy_alter()
 120  * @}
 121  */
 122
 123 /**
 124  * @addtogroup hooks
 125  * @{
 126  */
 127
 128 /**
 129  * Alters Blazy attachments to add own library, drupalSettings, and JS template.
 130  *
 131  * @param array $load
 132  *   The array of loaded library being modified.
 133  * @param array $settings
 134  *   The available array of settings.
 135  *
 136  * @ingroup blazy_api
 137  */
 138 function hook_blazy_attach_alter(array &$load, array $settings = []) {
 139   if (!empty($settings['photoswipe'])) {
 140     $load['library'][] = 'my_module/load';
 141
 142     $manager = \Drupal::service('blazy.manager');
 143     $template = ['#theme' => 'photoswipe_container'];
 144     $load['drupalSettings']['photoswipe'] = [
 145       'options' => $manager->configLoad('options', 'photoswipe.settings'),
 146       'container' => $manager->getRenderer()->renderPlain($template),
 147     ];
 148   }
 149 }
 150
 151 /**
 152  * Alters available lightboxes for Media switch select option at Blazy UI.
 153  *
 154  * @param array $lightboxes
 155  *   The array of lightbox options being modified.
 156  *
 157  * @see https://www.drupal.org/project/blazy_photoswipe
 158  *
 159  * @ingroup blazy_api
 160  */
 161 function hook_blazy_lightboxes_alter(array &$lightboxes) {
 162   $lightboxes[] = 'photoswipe';
 163 }
 164
 165 /**
 166  * Alters Blazy output to support a custom lightbox.
 167  *
 168  * @param array $image
 169  *   The renderable array of image being modified.
 170  * @param array $settings
 171  *   The available array of settings.
 172  *
 173  * @ingroup blazy_api
 174  */
 175 function hook_blazy_alter(array &$image, array $settings = []) {
 176   if (!empty($settings['media_switch']) && $settings['media_switch'] == 'photoswipe') {
 177     $image['#pre_render'][] = 'my_module_pre_render';
 178   }
 179 }
 180
 181 /**
 182  * @} End of "addtogroup hooks".
 183  */