Pinto

Appearance

Discovery ​

List enums are the entry point for component discovery.

These enums act as lists of your components.

Other than component discovery, they also provide a unified way to provide metadata about all the components contained within, via ObjectListInterface interface.

ObjectListTrait trait does the heavy work of implementing most of the required methods of ObjectListInterface. The remaining unimplemented methods determine the absolute directory of HTML templates, CSS, and Javascript files.

Practical example:

php
namespace Drupal\my_module\Pinto;

enum PintoList implements \Pinto\List\ObjectListInterface {
  
  #[Definition(Button::class)]
  case Button;
  
  #[Definition(Card::class)]
  case Card;
  
  #[Definition(Carousel::class)]
  case Carousel;
  
  #[Definition(CarouselSlide::class)]
  case CarouselSlide;
  
}

TIP

See also Discovery in Quick Start.

Lists enums ​

Lists are enums that implement ObjectListInterface and are by default found under the Pinto namespace.

php
namespace Drupal\my_module\Pinto;

enum PintoList implements \Pinto\List\ObjectListInterface {}

Tip: Custom Namespace

Namespaces are configurable by modifying pinto.namespaces parameter. See Discovery.

Tip: Backed Enums

A list enum does not need to be backed. To make a list backed, add the backing type as in:

php
enum PintoList: string implements ObjectListInterface {}

Cases ​

Each enum case is an item representing a component and associated assets (CSS & Javascript). Each case is comparable to the top level keys of a hook_theme() implementation.

Each case has an associated #[Definition] attribute, where the argument is a class-string reference to a PHP component. Unless it is an asset-only enum.

php
namespace Drupal\my_module\Pinto;

use Pinto\Attribute\Definition;

enum PintoList implements ObjectListInterface {
  #[Definition(Button::class)]
  case Button;
}
php
namespace Drupal\my_module\Pinto;

class Button {}

Attributes

Other than the #[Definition] attribute, enum cases can also have the following attributes applied:

  • Object types
  • Assets
    • \Pinto\Attribute\DependencyOn
    • \Pinto\Attribute\Asset\Css
    • \Pinto\Attribute\Asset\Js
    • \Pinto\Attribute\Asset\ExternalCss
    • \Pinto\Attribute\Asset\ExternalJs

Asset attributes ​

#[Css], #[Js], #[ExternalCss], #[ExternalJs], and [#DependencyOn] are used for associating CSS and Javascript assets along with resolvable dependencies. These attributes are covered in depth in Object Assets.

Slots attribute ​

If promoted properties slots are often used, and without manually defined slots, a #[Slots] attribute can be added on the enum to echo to all components which belong to it.

php
namespace Drupal\my_module\Pinto;
#[Slots(bindPromotedProperties: true)]
enum PintoList: string implements ObjectListInterface {}

Defining #[Slots] attribute on a component overrides the #[Slots] on the related enum or enum case.

Internals

Logic for determining which component type, i.e #[Slots] that takes effect for a component is determined in \Pinto\ObjectType\ObjectTypeDiscovery::definitionForThemeObject.

Traits ​

The ObjectListInterface interface requires a number of methods to be implemented, including:

php
interface ObjectListInterface {
  assets(): iterable|AssetInterface[];
  attachLibraries(): string[];
  build(wrapper: callable, component: component): callable;
  cssDirectory(): string;
  definitions(): DefinitionCollection;
  jsDirectory(): string;
  libraries(): array[];
  libraryName(): string;
  name(): string;
  templateDirectory(): string;
  templateName(): string;
}

Common trait ​

The \Pinto\List\ObjectListTrait trait is provided as a convenience to implement most methods. Each of these trait methods can be overridden as needed.

php
namespace Drupal\my_module\Pinto;
enum PintoList: string implements ObjectListInterface {
  use \Pinto\List\ObjectListTrait; 
}

Which leaves only a few methods which need to be implemented by an enum: templateDirectory, cssDirectory, and jsDirectory.

Single Directory Components ​

The behavior of SDC can be replicated using Single Directory trait.

The SDC trait implements all required methods of ObjectListInterface.