HTML display of view-templates (of a pattern library)
PHP tool for display of view-templates in HTML.
If you're building a pattern/component library, this simple tool will display its parts to designers, developers, and clients for collaboration! It's basically one helper function that you can place anywhere within your PHP:
<?= macropiche('path/to/template') ?>
This will render an HTML
<div> containing simple markup of:
- the file path
- the original file contents
- the processed file output as code/markup (unless equal to original file content)
- the processed file output as HTML
composer require fewagency/macropiche
Some reading on display patterns and atomic design - thinking that
macropiche is designed to support:
Reading on more advanced use of pattern libraries:
The helper function can be used within any PHP file or PHP-based template using
/** * @param $file string Relative or absolute path to template/view file * @param $context array|mixed Optional data for the template parser * @return string HTML */ function macropiche($file, $context = null)
$context is usually an array of variable names and values to populate the template.
The HTML generated by
macropiche has CSS classes following the
BEM approach for CSS naming so you may style elements anyway you want.
You should import your project's styles (and scripts) to your document to showcase your templates.
But the assets of this package also include some simple stylesheets that you may import
(or draw inspiration from) to style the actual
- assets/css/code-toggle.css uses the (empty) "source"-anchor to toggle visibility of the code display sections.
- assets/css/optional-style.css is a discreet style that is only applied to the
macropicheelements. It's based on transparent midtone gray to suit dark and light backgrounds alike.
<code> elements (wrapped in
<pre>) have classes indicating the language of their contents that you can use
for syntax highlighting, e.g.
language-php for PHP code.
This is useful with code syntax highlighters like Prism.
Why not use
the same configuration the Laravel docs use?
Generated Prism files can also be found among the assets of this package for quick use.
Usage with Laravel Blade templates
macropiche is used within a Laravel environment that has a
view() helper available, it will be used as the rendering
engine for the templates it seems to support.
In other situations you may declare your own helper called
that should return an instance of
(or similar - it's relaxed to work with Blade-packages that don't explicitly implement the interface).
Examples of usage with
jenssegers/blade can be found in
With Blade factories that implement the
getFinder() method (like the one built into Laravel)
it's possible to reference templates with the Blade dot-syntax relative the Blade views folder
instead of supplying full or relative paths to
macropiche currently supports
PHP and Blade template files.
We have support for Twig next in the feature pipeline!
<samp> element is used to display the processed output, within
It's not often one gets the opportunity to properly use
this type of package must be one of the few useful applications for that poor tag!
For those of you that have not yet read
the specification for the
I highly recommend it!
<p>The computer said <samp>Too much cheese in tray two</samp> but I didn't know what that meant.</p>
...and if someone knows who wrote that hilarious official usage example, or where it came from, please get in touch and tell me!
There are of course other ways of building your HTML component library for display, some examples:
They all generate a full website, whereas this package aims to provide a simpler toolset for displaying templates within your existing project.
I, Björn Nilsved, created this package while working at FEW.