This is the future home of the ALPS codebase. The pattern library is built off of Pattern Lab, and a tool based on atomic design.
If you want to make changes, feel free to fork the repository and create a pull request.
Questions or issues can be filed as tickets on this repository and will be handled using the GitHub system.
This repository contains the front-end code for the Seventh Day Adventist project. Pattern Lab is the tool used for pattern template building and pattern library compilation.
-
run
composer install
-
Install node globally (
node >= v12)
-
run
npm install
(may need to be run assudo
) -
run
npm run dev
This creates all patterns, the styleguide, and the pattern lab site as well as a local server for development.
The 7 Column Grid is used on the page layout and all blocks
.l-grid
Grid wrapper to make child divs flex.l-grid--7-col
7 Column grid wrapper.l-grid-item--x-col
Span x number of columns on mobile (<=500px).l-grid-item--s--x-col
Span x number of columns at small breakpoint (>500px).l-grid-item--m--x-col
Span x number of columns at medium breakpoint (>700px).l-grid-item--l--x-col
Span x number of columns at large breakpoint (>900px).l-grid-item--xl--x-col
Span x number of columns at xxlarge breakpoint (>1300px)
.l-grid-wrap
Span grid 100% of the viewport width.l-grid-wrap--x-of-7
Span grid x number of columns
Shifts the grid over 1 column
.u-shift--right--1-col--at-medium
Shift grid over to right 1 column at medium breakpoint (>700px).u-shift--left--1-col--at-medium
Shift grid over to left 1 column at medium breakpoint (>700px).u-shift--left--1-col--at-large
Shift grid over to left 1 column at large breakpoint (>900px).u-shift--left--1-col--at-xxlarge
Shift grid over to left 1 column at xxlarge breakpoint (>1300px)
Positions the content in the Blocks or Page Header
.u-flex--align-center
Flex align center.u-flex--align-end
Flex align end.u-flex--justify-center
Justify content center.u-flex--justify-end
Justify content end.u-text-align--center
Text align center.u-text-align--right
Text align right.u-text-align--left
Text align left
Apply class for theme color. Each theme has 5 color variations. Replace the {$key} with a value.
Color Keys {$key}
darker
dark
base
light
lighter
Color Classes
.u-theme--color--{$key}
Text Color.u-theme--link-hover--{$key}
Link Color.u-theme--background-color--{$key}
Background Color.u-theme--border-color--{$key}
Border Color.u-theme--border-color--{$key}--left
Left Border Color.u-theme--border-color--{$key}--right
Right Border Color.u-theme--border-color--{$key}--Top
Top Border Color.u-theme--border-color--{$key}--Bottom
Bottom Border Color
.u-theme--path-fill--{$key}
SVG Fill Cover
In order to play nice with environments outside of Pattern Lab, we use the default Twig include syntax over the Pattern Lab shorthand.
Don't do this:
{% include 'templates-home' %}
Do this:
{% include '@templates/[email protected]' %}
To export the patterns to the Adventist Identity Guideline System, run the following grunt export command: grunt style-guide-export
. All patterns will be copied over to the igs-guidelines repo, which should be located in the same root folder as ALPS , when this gets run. This command will clean up the files, removing any flags that are unneeded in the igs-guidelines repo.
For Drupal projects utilizing ALPS twig files, you'll need to run the pattern export command in order to generate the Drupal-specific file naming.
- Create a directory named "drupal-patterns" in
/source/
- run
grunt export-drupal-patterns
- this will copy all patterns from the/source/_patterns/
directory and rename the.twig
file extensions to.html.twig
- Separation of presentation, content, and behavior.
- Markup should be well-formed, semantically correct, and generally valid (if possible).
- Javascript should progressively enhance the experience.
- Always keep performance at top of mind when coding.
The CSS in this project follows Harry Robert's itcss architecture. CSS/SCSS Coding Best Practices should be the referenced standards guide when writing sane, manageable, scalable CSS.
All commit messages should abide by the following criteria:
- Begin with a one line summary. It should be short (50 chars or less).
- This should be followed by a longer description if necessary.
- The first two items should be separated by an empty line.
- All lines should be wrapped at approximately 72 characters.
- Reference an issue in your commits whenever possible. Use the Github standard
gh-34
for ticket#34
. - If you forget to reference the issue in your commit, and the commit has already been pushed, reference the commit hash in a comment on the ticket.
Make sure you are running your terminal/command line session as administrator. This could mean sudo
, or opening the window with a right-click option.
The Standard Edition for Twig gives developers and designers a clean and stable base from which to develop a Twig-based pattern library.
The Standard Edition for Twig comes with the following components:
pattern-lab/core
: GitHub, Packagistpattern-lab/patternengine-twig
: documentation, GitHub, Packagistpattern-lab/styleguidekit-assets-default
: GitHub, Packagistpattern-lab/styleguidekit-twig-default
: GitHub, Packagist
There are two methods for downloading and installing the Standard Edition for Twig:
The fastest way to get started with the Standard Edition for Twig is to download the pre-built version from the releases page. The pre-built project comes with the Base StarterKit for Twig installed by default.
Please note: Pattern Lab uses Composer to manage project dependencies. To upgrade the Standard Edition for Twig or to install plug-ins you'll need to install Composer. We recommend that you install it globally.
Pattern Lab uses Composer to manage project dependencies.
Please follow the directions for installing Composer on the Composer website. We recommend you install it globally.
Use Composer's create-project
command to install the Standard Edition for Twig into a location of your choosing. In Terminal type:
cd install/location/
composer create-project pattern-lab/edition-twig-standard your-project-name && cd $_
This will install the Standard Edition for Twig into a directory called your-project-name
in install/location/
. During the set-up process you will be asked to install an appropriate StarterKit. You will be automatically dropped into the project directory after the process is finished.
To update Pattern Lab please refer to each component's GitHub repository. The components are listed at the top of the README.
These are some helpful commands you can use on the command line for working with Pattern Lab.
To list all available commands type:
php core/console --help
To list the options for a particular command type:
php core/console --help --[command]
To generate the front-end for Pattern Lab type:
php core/console --generate
To watch for changes and re-generate the front-end for Pattern Lab type:
php core/console --watch
You can use PHP's built-in web server to review your Pattern Lab project in a browser. In a seperate window type:
php core/console --server
Then open http://localhost:8080 in your browser.
To install a near-empty StarterKit as a starting point for your project type:
php core/console --starterkit --init
To install a specific StarterKit from GitHub type:
php core/console --starterkit --install <starterkit-vendor/starterkit-name>
The Twig PatternEngine allows you to use Twig as the template language for Pattern Lab PHP. Once the PatternEngine is installed you can use Twig-based StarterKits and StyleguideKits.
The Twig PatternEngine comes pre-installed with the Pattern Lab Standard Edition for Twig. Please start there for all your Twig needs.
Pattern Lab PHP uses Composer to manage project dependencies with Pattern Lab Editions. To add the Twig PatternEngine to the dependencies list for your Edition you can type the following in the command line at the base of your project:
composer require pattern-lab/patternengine-twig
See Packagist for information on the latest release.
This document is broken into three parts:
Twig provides access to two features that may help you extend your patterns, macros and layouts viatemplate inheritance. The Twig PatternEngine also supports the pattern partial syntax to make including one pattern within another very easy.
Pattern includes take advantage of the pattern partial syntax as a shorthand for referencing patterns from across the system without needing to rely on absolute paths. The format:
{% include "[patternType]-[patternName]" %}
For example, let's say we wanted to include the following pattern in a molecule:
source/_patterns/00-atoms/03-images/02-landscape-16x9.twig
The pattern type is atoms (from 00-atoms
) and the pattern name is landscape-16x9 from (from 02-landscape-16x9.twig
). Pattern sub-types are never used in this format and any digits for re-ordering are dropped. The shorthand partial syntax for this pattern would be:
{% include "atoms-landscape-16x9" %}
The requirements for using macros with Pattern Lab:
- Files must go in
source/_macros
- Files must have the extension
.macro.twig
(this can be modified in the config) - The filename will be used as the base variable name in Twig templates
Please note: ensure that there is no overlap between the keys for your macros and the keys for your data attributes. A macro with the name forms.macro.twig
will conflict with a root key with the name forms
in your JSON/YAML. Both are accessed via {{ forms }}
in Twig.
An example of a simple macro called forms.macro.twig
in source/_macros
:
{% macro input(name) %}
<input type="radio" name="{{ name }}" value="Dave" /> {{ name }}
{% endmacro %}
Would be used like this in a pattern:
{{ forms.input("First name") }}
How to use Template Inheritance with Pattern Lab:
- Files must have the extension
.twig
. - Files can be extended either by using Pattern Lab's normal shorthand syntax (e.g,
{% extends 'templates-extended-layout'%}
). - Files can optionally go in
source/_layouts
in order to hide them from the list of patterns and then you can just use the filename as reference (e.g.,{% extends 'extended-layout'%}
). - Files that are in the same directory can also just use the file name without the shorthand syntax (however, it must include the extension). So if
file1.twig
andfile2.twig
were in same directory, you could place this code infile2.twig
:{% extends 'file1.twig' %}
.
An example of a simple layout called base.twig
in source/_layouts
:
<!DOCTYPE html>
<html>
<head>
{% block head %}
<link rel="stylesheet" href="style.css" />
<title>{% block title %}{% endblock %} - My Webpage</title>
{% endblock %}
</head>
<body>
<div id="content">{% block content %}{% endblock %}</div>
<div id="footer">
{% block footer %}
© Copyright 2011 by <a href="http://domain.invalid/">you</a>.
{% endblock %}
</div>
</body>
</html>
Would be used like this in a pattern:
{% extends "base.twig" %}
{% block title %}Index{% endblock %}
{% block head %}
{{ parent() }}
<style type="text/css">
.important { color: #336699; }
</style>
{% endblock %}
{% block content %}
<h1>Index</h1>
<p class="important">
Welcome on my awesome homepage.
</p>
{% endblock %}
All uses of extends
above also work with includes
, embed
and most likely many other Twig Tags. Let us know if you run into interesting or unexpected use cases!
Twig comes with a number of ways to extend the underlying template parser. You can you can add extra tags, filters, tests, and functions. The Twig PatternEngine tries to simplify these extensions by allowing you to create files in specific folders and then auto-load the extensions for you. Learn more about:
You can also:
The requirements for using filters with Pattern Lab:
- Files must go in
source/_twig-components/filters
- Files must have the extension
.filter.php
(this can be modified in the config) - The filter must set the variable
$filter
- Only one filter per file (e.g. can only set
$filter
once per file)
An example function called rot13.filter.php
in source/_twig-components/filters
:
<?php
$filter = new Twig_SimpleFilter('rot13', function ($string) {
return str_rot13($string);
});
?>
This filter would be used like this in a pattern:
{{ bar|rot13 }}
The requirements for using functions with Pattern Lab:
- Files must go in
source/_twig-components/functions
- Files must have the extension
.function.php
(this can be modified in the config) - The function must set the variable
$function
- Only one function per file (e.g. can only set
$function
once per file)
An example function called boo.function.php
in source/_twig-components/functions
:
<?php
$function = new Twig_SimpleFunction('boo', function ($string) {
return $string." boo! ";
});
?>
This function would be used like this in a pattern:
{{ boo("ghost says what?") }}
The requirements for using tests with Pattern Lab:
- Files must go in
source/_twig-components/tests
- Files must have the extension
.test.php
(this can be modified in the config) - The test must set the variable
$test
- Only one test per file (e.g. can only set
$test
once per file)
An example of a simple test called red.test.php
in source/_twig-components/tests
:
<?php
$test = new Twig_SimpleTest('red', function ($value) {
if (isset($value["color"]) && $value["color"] == 'red') {
return true;
}
return false;
});
?>
This test would be used like this in a pattern:
{% if shirt is red %}
Why did I ever sign-up with Starfleet?
{% endif %}
Where the JSON for the data to set shirt
would be:
"shirt": {
"color": "red"
}
Reminder: all data in Pattern Lab is stored as an array and not as an object. So $object->attribute
won't work in tests.
The requirements for using tags with Pattern Lab:
- Files must go in
source/_twig-components/tags
- Files must have the extension
.tag.php
(this can be modified in the config) - The filename must be reflected in class names. (e.g.
Project_{filename}_Node
andProject_{filename}_TokenParser
) - Only one tag per file
Tags are the most complicated extension to set-up with Pattern Lab. Three steps are needed to define a new tag in Twig:
- Defining a Token Parser class (responsible for parsing the template code)
- Defining a Node class (responsible for converting the parsed code to PHP)
- Registering the tag.
Pattern Lab takes care of the registering for you based on the file name.
An example of a simple tag called setdupe.tag.php
in source/_twig-components/tags
that mimics the default set
tag. Please note all of the locations where class names incorporate the filename, setdupe
.
<?php
// these files are loaded three times and we can't re-set a class
if (!class_exists("Project_setdupe_Node")) {
class Project_setdupe_Node extends Twig_Node {
public function __construct($name, Twig_Node_Expression $value, $line, $tag = null) {
parent::__construct(array('value' => $value), array('name' => $name), $line, $tag);
}
public function compile(Twig_Compiler $compiler) {
$compiler
->addDebugInfo($this)
->write('$context[\''.$this->getAttribute('name').'\'] = ')
->subcompile($this->getNode('value'))
->raw(";\n");
}
}
}
// these files are loaded three times and we can't re-set a class
if (!class_exists("Project_setdupe_TokenParser")) {
class Project_setdupe_TokenParser extends Twig_TokenParser {
public function parse(Twig_Token $token) {
$parser = $this->parser;
$stream = $parser->getStream();
$name = $stream->expect(Twig_Token::NAME_TYPE)->getValue();
$stream->expect(Twig_Token::OPERATOR_TYPE, '=');
$value = $parser->getExpressionParser()->parseExpression();
$stream->expect(Twig_Token::BLOCK_END_TYPE);
return new Project_setdupe_Node($name, $value, $token->getLine(), $this->getTag());
}
public function getTag() {
return 'setdupe';
}
}
}
?>
This tag would be used like this in a pattern:
{% setdupe name = "Ziggy" %}
{{ name }}
To use dump()
set twigDebug
in config/config.yml
to true
.
You can modify the default date and interval formats for Twig by editing the twigDefaultDateFormat
and twigDefaultIntervalFormat
in config/config.yml
. Set them to an empty string to use Twig's default formats. Please note: both must be set for this feature to work.
To disable extensions that you're no longer using simply add an underscore to the beginning of a filename and then re-generate your site. For example, the enabled rot13 filter:
source/_twig-components/filters/rot13.filter.php
And the disabled rot13 filter:
source/_twig-components/filters/_rot13.filter.php
Then re-generate your Pattern Lab site with:
php core/console --generate
If you're building a plugin that will be parsing Twig files you have access to three loaders. It's recommended that you use these instead of accessing Twig directly as these loaders will work with other PatternEngines.
The string loader takes a simple string and compiles it. To use:
$data = array("hello" => "world");
$string = "If I say hello you say {{ hello }}.";
$stringLoader = \PatternLab\Template::getStringLoader();
$output = $stringLoader->render(array("string" => $string, "data" => $data));
print $output; // outputs "If I say hello you say world."
The filesystem loader will look for templates in the configured StyleguideKit directory and compile them. The template location for the filesystem loader can't be modified. To use:
$data = array(...);
$filesystemLoader = \PatternLab\Template::getFilesystemLoader();
$output = $filesystemLoader->render(array("template" => "viewall", "data" => $data));
print $output; // outputs the viewall view from the configured styleguidekit
The pattern loader looks for patterns and allows the use of the Pattern Lab-specific partial syntax. To use:
$data = array(...);
$patternContent = file_get_contents("path/to/pattern");
$patternEngineBasePath = \PatternLab\PatternEngine::getInstance()->getBasePath();
$patternLoaderClass = $patternEngineBasePath."\Loaders\PatternLoader";
$patternLoader = new $patternLoaderClass($options);
$code = $patternLoader->render(array("pattern" => $patternContent, "data" => $data));
print $output; // outputs the given pattern