@studiometa/ui

Appearance

FigureTwicpics JSTwig ​

Use the FigureTwicpics component to display images with the Twicpics API.

Usage ​

Register the component in your JavaScript app and use the Twig template to display images.

js
import { registerComponent } from '@studiometa/js-toolkit';
import { FigureTwicpics } from '@studiometa/ui';

registerComponent(FigureTwicpics, 'Figure');
twig
<div class="card">
  {% include '@ui/Figure/FigureTwicpics.twig' with {
    src: 'https://picsum.photos/400/400',
    width: 400,
    height: 400,
    twic_domain: ''
  } only %}
</div>

With JavaScript only ​

To avoid repeating the domain and path of your Twicpics project via data-option-* attributes, you can define the domain and path getter directly by extending the FigureTwicpics class in your project.

js
import { FigureTwicpics } from '@studiometa/ui';

export default class Figure extends FigureTwicpics {
  static config = {
    ...FigureTwicpics.config,
    name: 'Figure',
  };

  get domain() {
    return 'domain.twic.pics';
  }

  get path() {
    return 'production';
  }
}

And replace the import in your app to import your local class instead of the one from the package.

diff
  import { Base, createApp } from '@studiometa/js-toolkit';
- import { FigureTwicpics } from '@studiometa/ui';
+ import { Figure } from './Figure.js';

  class App extends Base {
    static config = {
      name: 'Base',
      components: {
        Figure,
      }
    };
  }

  export default createApp(App);

WARNING

Setting the domain and path via getters in JavaScript will work with lazyloaded images. If you disable lazyloading when using the Twig template, you will need to specify the twic_domain and twic_path Twig options.

With Twig ​

If your project uses Twig as a templating language, it is recommended to define the domain and path for TwicPics in Twig. This will allow the usage of TwicPics for placeholders.

Define an override for Figure/FigureTwicpics.twig in your configured project template directory. Extend the package implementation through @ui-pkg so normal @ui/Figure/FigureTwicpics.twig includes resolve to your override:

twig
{% extends '@ui-pkg/Figure/FigureTwicpics.twig' %}

{% set twic_domain = 'my-domain.twic.pics' %}
{% set twic_path = 'my-path' %}

INFO

This approach is a replacement of defining the domain and path in JavaScript described above.

Using placeholders ​

By default, the FigureTwicpics component uses an blank SVG placeholder as the source of the image. This can be customized with the twic_placeholder parameter.

twig
{# Will display a blurred version of the image #}
{% include '@ui/Figure/FigureTwicpics.twig' with {
  twic_domain: 'org.twic.pics',
  twic_placeholder: 'preview',
} %}

{# Will display a lighter version of the image with its quality degraded to 5 #}
{% include '@ui/Figure/FigureTwicpics.twig' with {
  twic_domain: 'org.twic.pics',
  twic_placeholder: {
    quality_max: 5,
  },
} %}