FED Scripts

This package is a collection of Node.js scripts and tools for assisting with front end development.

• TWIG templating compilation
• Iconfont (SVG icons)
• Image compression
• Favicon/Metadata generation

Scripts folder

Custom node scripts (tasks) are located in the /scripts/ directory. This includes custom scripts for the Twig.js compilation, Iconfont generation, favicons/meta etc. These tasks are referenced in the package.json file for each of the main build scripts, i.e -

"scripts": {
        "twig": "node scripts/twig.js",
        "twig-watch": "node scripts/twig.js -w",
        "razor": "node scripts/razor.js",
        "razor-watch": "node scripts/razor.js -w",
        "iconfont": "node scripts/iconfont.js",
        "iconfont-watch": "node scripts/iconfont.js -w",
        "assets": "node scripts/assets.js",
        "assets-watch": "node scripts/assets.js -w",
        "favicons": "node scripts/favicons.js",
        "build-cms": "node scripts/cms.js"
    },

Twig

Twig is a simple and easy to read templating language used to both generate static html flats and build templates for .twig supporting CMSs.

The boiler plate includes a script for a javascript Twig compiler (https://github.com/twigjs/twig.js/wiki) which will automatically interpret .twig files in the /src/twig/ directory.

Full documentation for Twig can be found at https://twig.symfony.com/doc/2.x/ with https://twig.symfony.com/doc/2.x/templates.html being the most relevant doc for the sake of front end templating.

Twig syntax highlighting is available for most IDEs to help with development:

• Atom via the PHP-twig for atom
• Visual Studio Code via the Twig pack
• Sublime Text via the Twig bundle
• Notepad++ via the Notepad++ Twig Highlighter

Twig structure

By default all twig files in the root twig directory /src/twig will be compiled and exported as html files to the /public directory where they will be served by the local dev server from. These same compiled html files in the /public directory are then prepped for production and moved to the /build folder on running the build task outlined in the build process.

Atomic design

The twig file breakup is based around the concept of atomic design, which is essentially breaking down templates and pages into components with varying levels of granularity.

There are a few resources available around the web to go into more depth on the concepts involved in atomic design but for a bit of an overview you can refer to this post -
http://bradfrost.com/blog/post/atomic-web-design/

/src/twig/

Files at the root of the twig folder should be viewed as representations of pages (cms output) and ideally only represent data and not templates themselves.

An example of this can be seen in the /src/twig/twig.twig file which extends the default.twig template in the /src/twig/templates/ directory -

{% extends "./templates/default.twig" %}

This file also contains an example of a data variable mockup which is a representation of page content, below is an example of the data variable with latestNews being an array of article cards -

{% set data = {
    latestNews: [
        {
            'title': 'First Card',
            'link': {
                'text': 'This is link text!',
                'href': '/'
            }
        },
        {
            'title': 'Second Card',
            'button': {
                'text': 'Next',
                'className': 'button--next'
            }
        },
        {
            'title': 'Third Card',
            'id': '34dse33'
        }
    ]
} %}

The view block is the area of the twig.twig page that will be extended into the default.twig template. Below you can see an include to a latest news component is what is going to be extended into the default.twig template -

{% block view %}

    {% include './organisms/latest-news.twig' %}

{% endblock %}

Inside the default.twig template we can see the view block is positioned in between a nav and footer include -

{# Master Template with head #}
{% extends twigDir ~ "templates/master.twig" %}

{# 'page' block is included in body of master.twig #}
{% block page %}

    {% include twigDir ~ 'organisms/nav.twig' %}

    {% block view %}{% endblock %}

    {% include twigDir ~ 'organisms/footer.twig' %}

{% endblock %}

The default template is then extended into a master.twig template which contains the highest level html including the html, head and body tags -

<body>
    <div class="page page--{{ bodyClass }}">
        {% block page %}{% endblock %}
    </div>
</body>

/src/twig/constants/global.twig

The global.twig file represents data that is site wide or global (social links, site domains, global ctas etc)

/src/twig/templates/

The templates directory of the twig folder should contain all page/content type templates such as news detail page template, a blog article template as well as the higher level templates (default.twig, master.twig).

/src/twig/organisms/

Organisms are the next highest level of template and represent the highest level of component. An example of this would be a full width pagination component (article cards and pagination) or a full width carousel or video player.

Here is an example of the /src/twig/organisms/latest-news.twig organism -

<div class="latest-news">
    <div class="container-fluid center-xs">
        <h2>
            Latest News
        </h2>
        <div class="row">
            {% for card in latestNews %}
                <div class="col-xs-12 col-sm-4">
                    {% include twigDir ~ 'molecules/card.twig' with card  %}
                </div>
            {% endfor %}
        </div>
    </div>
</div>

/src/twig/molecules/

Molecules fall as the next level of component after organisms and organisms may contain multiple molecules. An example of a molecule could be a an article card with a poster image, title, description and cta. This molecule could then make up one of the multiple article cards in a article pagination organism.

Here is an example of the /src/twig/molecules/card.twig molecule -

<div class="card">
    {{ title }}

    {% if link %}
    <a href="{{ link.href }}" class="card-link">
        {{ link.text }}
    </a>
    {% endif %}

    {% if id %}
    <div class="card-id">
        {{ id }}
    </div>
    {% endif %}

    <p>
        {% include twigDir ~ 'atoms/button.twig' with button only %}
    </p>
</div>

/src/twig/atoms/

Atoms are essentially the lowest level of component and will belong to both molecules and organisms. Examples of atoms could include buttons, publish details (author, date, category), image tiles etc

An example of the /src/twig/atoms/button.twig atom -

<button class="button {{ className }}">
    {{ text ?: 'Submit' }}
    <span class="icon icon-chevron-right"></span>
</button>

Iconfont

An svg Iconfont task is setup to watch and compile svg icons from the /public/assets/icons/ directory to an Iconfont as part of the yarn start process.

The font is output at the /public/assets/fonts/ folder and automatically deployed to the /build and cms build directories on running the build process.

The Iconfont css is already included via the /src/scss/index.scss file.

For more configuration and editing of the Iconfont script please check the /scripts/iconfont.js file.

Image compression

As outlined in the build process, building will run an image compression task on all images within the public/build directories.

Image compression is taken care of by the imagemin-webpack-plugin webpack plugin.

This plugin is essentially a wrapper around Imagemin and thus most imagemin properties and setup and can be configured. Configuration is handled in the /config/webpack.config.prod.js file under the ImageminPlugin plugin section.

Favicon generation

A script is included to generate favicons, webapp icons, manifest and meta tags. Configuration for the favicons script can be found at /scripts/favicons.js.

By default the script will target the image at /public/assets/images/favicon.png to generate the favicon and all web app icons. A large res source image should be used here to cater to large app and splash screen icons.

This task must be run manually each time you wish to update the favicon or meta fields with the following command -

yarn favicons

This will not only generate the favicon, icons and the manifest.json in the /public/meta/ folder but also create a favicons.twig partial in the /src/twig/templates/ folder. The favicons.twig partial contains all the generated meta tags and fields relating to the favicon, icons and manifest references allowing you to then include it in a high level twig template such as the master.twig -

<head>
    <base href="/" />
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <meta name="description" content="{{ documentDescription }}">
    <script src="https://cdnjs.cloudflare.com/ajax/libs/modernizr/2.8.3/modernizr.min.js"></script>

    {% include twigDir ~ 'templates/favicons.twig' %}

    <title>
        {{ documentTitle }}
    </title>
</head>