Blazy API in Blazy 7

Same name and namespace in other branches

1. 8.2 blazy.api.php \blazy_api
2. 8 blazy.api.php \blazy_api

Information about the Blazy usages.

Modules may implement any of the available hooks to interact with Blazy. Blazy may be configured using the web interface using formatters, or Views. However below is a few sample coded ones.

Calling theme_blazy() directly is useless. Please use the provided API below. Most heavy liftings are performed at BlazyManager::preRender() where they belong to. At Blazy 8.x-1.x, it is still possible to call theme_blazy(), but this will be removed later at Blazy 8.x-2.x+. The only reason is supporting direct call has produced a few duplicated lines. As we are perfecting Blazy API for both simple and complex needs, we strive to minimize dups.

A single image sample.

function my_module_render_blazy() {

  // URI is required, set it via settings array or image object.
  // Using image as an object, not array, is simply to reflect a D8 backport.
  // Create an optional fake image object containing image metadata:
  $item = new \stdClass();
  $item->width = 640;
  $item->height = 360;
  $item->alt = t('Awesome image');
  $item->uri = 'public://logo.jpg';

  // Or convert an existing image or file entity image array into an object:
  $file = file_load(123);
  $item = (object) $file;

  // Provides info for Blazy to do its job via $settings array.
  $settings = [
    // URI is stored in #settings property so to allow traveling around video
    // and lightboxes before being passed into theme_blazy().
    'uri' => 'public://logo.jpg',
    // Explicitly request for Blazy.
    // This allows Slick lazyLoad to not load Blazy.
    // This `lazy` defines the HTML output, and makes sense for Slick
    // which has extra lazyload names: ondemand, anticipated, etc
    'lazy' => 'blazy',
    // In order to attach the Blazy library an sich, call for `blazy`:
    'blazy' => TRUE,
    // Optionally provide an image style. Valid URI is a must:
    'image_style' => 'thumbnail',
    // Optionally require one of Blazy media_switch features depending on
    // the available module, of course:
    // colorbox, photobox, photoswipe, media (Image to iframe), and set its
    // value to TRUE to load its own library.
    // This `media_switch` defines the HTML output, CSS classes, link, etc.
    'media_switch' => 'colorbox',
    // The below `colorbox` key is to load the colorbox library.
    // We do this separately as relying on `media_switch` alone to load
    // library may conflict with Blazy filter set globally once.
    // It will negate each other.
    // With media_switch defining HTML, and colorbox for library, it allows
    // us to have multiple media_switch, and relevant libraries loaded on the
    // same page.
    'colorbox' => TRUE,
  ];

  // Pass $data containing $item and $settings into BlazyManager::getBlazy().
  // It was poorly named BlazyManager::getImage() at D8 while Blazy may also
  // contain Media video with iframe element. Probably getMedia() is cool,
  // but let's stick to getBlazy() for now as Blazy also works without Image
  // nor Media video, such as with just a DIV element for CSS background.
  $data = [
    'item' => $item,
    'settings' => $settings,
  ];
  $build = blazy()
    ->getBlazy($data);

  // Finally load the library, or include it into a parent container.
  // Or make Blazy available wherever needed at /admin/config/media/blazy.
  // Just dump the provided $settings as the argument, or refine it as needed
  //   $build['#attached'] = blazy()->attach($settings);
  return $build;
}

A multiple image sample.

For advanced usages with multiple images, and a few Blazy features such as lightboxes, lazyloaded images, or iframes, including CSS background and aspect ratio, etc.: o Invoke blazy(), and or blazy('formatter'), services. o Use blazy()->getBlazy() method to work with images and pass relevant settings which request for particular Blazy features accordingly. o Use blazy()->attach($attach) to load relevant libraries. Where $attach can contain any of supported blazy libraries: colorbox, photobox, media (Image to iframe), blazy, grid, column, etc. Just set the value to TRUE to require one.

function my_module_render_blazy_multiple() {

  //   $settings = [];
  // Build images.
  $build = [];

  // Finally attach libraries as requested via $settings.
  $build['#attached'] = blazy()
    ->attach($settings);
  return $build;
}

Pre-render callback sample to modify/ extend Blazy output.

function my_module_pre_render(array $image) {
  $settings = isset($image['#settings']) ? $image['#settings'] : [];

  // Video's HREF points to external site, adds URL to local image.
  if (!empty($settings['box_url']) && !empty($settings['embed_url'])) {
    $image['#url_attributes']['data-box-url'] = $settings['box_url'];
  }
  return $image;
}

See also

\Drupal\blazy\BlazyManagerBase::attach().

\Drupal\blazy\BlazyDefault::imageSettings()

the above my_module_render_blazy() for details.

\Drupal\blazy\Plugin\Field\FieldFormatter\BlazyManagerTrait::buildElements()

\Drupal\blazy\Plugin\Field\FieldFormatter\BlazyVideoFormatter::buildElements()

\Drupal\gridstack\Plugin\Field\FieldFormatter\GridStackFileFormatterBase::buildElements()

\Drupal\slick\Plugin\Field\FieldFormatter\SlickFileFormatterBase::buildElements()

\Drupal\blazy\BlazyManager::getBlazy()

hook_blazy_alter()

File

./blazy.api.php, line 8

Hooks and API provided by the Blazy module.

Functions