README

Experimental Twig extension to transform custom HTML elements into the necessary Material Design boilerplate based on the specification and recommendations at https://github.com/material-components/material-components-web

Motivation

Material Design web components can be a good rapid prototyping tool for administration/backend interfaces, if one is familiar with the options it offers. However, most, if not all, the wrapping component libraries I've found were frontend framework plugins. This library tries to wrap those components with HTML markup, while still wiring up internally the necessary JavaScript initialization, for your everyday project that uses the Twig templating language.

Quick Start

composer require webesque/twig-material-design

$twig->addExtension(
  new webesque\TwigMaterialDesign\Extension
);

Alternatively if you're using symfony add the following lines to services.yaml

webesque\TwigMaterialDesign\Extension:
  tags: ['twig.extension']

Use the following base Twig template as a starter:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  {{ material_design_includes() }}
</head>

<body class="mdc-typography">
{% apply material_design %}

  <tmd-button>Button</tmd-button>

{% endapply %}

{{ material_design_autoinit() }}
</body>
</html>

All you need to know about this extension

Developer experience

Documentation is generated from code and meant to be easily accessible, if your editor of choice supports fuzzy searching, then try to search for a specific component material component name to quickly access the documentation for the specific component.

The library tries to follow the accessibility notes/guidelines within the Material Design specification, and add the necessary aria attributes where possible. The notable exception from this is with the tabindex attribute. Within selections, menus, etc it's up to the library user to explicitly add the tabindex attribute. In the future the library might be able to this on user's behalf.

Material Design related quirks

In order to use the Material Design typography system the body of the page needs to have the mdc-typography class.

The library parses all the tags within the markup (not only the component), because it exposes typography and elevation attributes on all the HTML tags.

Implementation quirks

This library does not try to be a 1-1 mapping to the material-components-web component list. While it started that way, it was switched to higher level abstractions. Reason being that even simple components, in the 1-1 mapping scenario, required additional markup. E.g <tmd-button><tmd-label>A button</tmd-label></tmd-button> vs <tmd-button>A button</tmd-button>.

If you hit upon a scenario where this constraint prevents you from implementing/styling a component exactly as you'd like (law of leaky abstractions), I suggest you inline the original Material Design component boilerplate in that specific section of your page.

Along the same lines, there's a common pattern among a few Material Design components; where components might have subsections like: actions, content, title, text, etc. They are generally similar in structure, but might have different attributes/css classes. To avoid multiple specific thin subcomponents, generic non-component tags exist to simplify things. E.g actions, content, text, etc.

webesque / twig-material-design

Maintainers

Details