fewagency/macropiche

This package is abandoned and no longer maintained. No replacement package was suggested.

HTML display of view-templates (of a pattern library)

Maintainers

Details

github.com/bjuppa/macropiche

Source

Issues

Installs: 553

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 5

Forks: 0

Open Issues: 1

v3.2 2017-05-15 09:01 UTC

Requires

  • php: >=5.4.0

Requires (Dev)

MIT 019210268788d8fdcc45861af91162df6cca376a

  • Bjorn Nilsved <bjorn.nilsved.woop@fewagency.se>

templatelibrarypatterncomponentshtmlsamplesheetatomicsnippet

This package is auto-updated.

Last update: 2023-04-17 23:11:17 UTC

README

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

Installation

composer require fewagency/macropiche

Background

Some reading on display patterns and atomic design - thinking that macropiche is designed to support:

Reading on more advanced use of pattern libraries:

Usage

The helper function can be used within any PHP file or PHP-based template using echo or <?=.

/**
* @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)

The $context is usually an array of variable names and values to populate the template.

Examples

The examples contain a quick test php file to get you started and show the macropiche() helper method used in a PHP file.

Styling and scripting

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 macropiche elements:

  • 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 macropiche elements. It's based on transparent midtone gray to suit dark and light backgrounds alike.

Syntax highlighting

The <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

If 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 macropiche_blade_view() that should return an instance of Illuminate\Contracts\View\Factory (or similar - it's relaxed to work with Blade-packages that don't explicitly implement the interface). Examples of usage with duncan3dc/blade and jenssegers/blade can be found in examples/test-blade-duncan3dc.php and examples/test-blade-jenssegers.php respectively.

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.

Usage with Twig templates

macropiche currently supports HTML, PHP and Blade template files. We have support for Twig next in the feature pipeline!

<samp>!

The <samp> element is used to display the processed output, within <pre><code class="language-html">. It's not often one gets the opportunity to properly use <samp>, 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 <samp> element, 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!

Alternatives

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.

Authors

I, Björn Nilsved, created this package while working at FEW.