How to develop and deploy a Skeleton template

New webpack project

Initiate a new webpack project (see webpack Getting Started guide) :

mkdir webpack-demo
cd webpack-demo
npm init -y
npm install webpack --save-dev
npm install webpack-cli --save-dev

Open this project in your favorite IDE. Create a 'src' folder and a index.js file in it. Content of the index.js:

console.log('Hello world');

Than run the command:

npx webpack --mode development

A new javascript file has been compiled in the dist folder.

Update the Apache configuration

The content of the dist folder are the assets of your web site. It will contain all JS, CSS, images, fonts, ... of your website template. A good way to make it available in your development environment is to update your Apache VirtualHost config to define an alias:

<VirtualHost *:80>
    ServerName site-ems.test
    ServerAlias www.site-ems.test

    DocumentRoot /Users/theus/git/website/public
    DirectoryIndex /index.php

    <Directory /Users/theus/git/website/public>
        AllowOverride None
        Order Allow,Deny
        Allow from All
        FallbackResource /index.php
    </Directory>

    Alias "/bundles/emsch-assets" "/Users/theus/git/webpack-demo/dist"

    <Directory /Users/theus/git/website/public>
        AllowOverride None
        Order Allow,Deny
        Allow from All
        FallbackResource disabled
    </Directory>


    <Directory /var/www/project/public/bundles>
        FallbackResource disabled
    </Directory>

    ErrorLog /var/log/apache2/project_error.log
    CustomLog /var/log/apache2/project_access.log combined

    # set the value of the environment variables used in the application:

    ###> symfony/framework-bundle ###
    SetEnv APP_ENV "dev"
    SetEnv APP_SECRET "ThisIsNotASecret"
....
</VirtualHost>

In this example our Skeleton project is located in /Users/theus/git/website/public and the webpack distribution files in /Users/theus/git/webpack-demo/dist. In this example we will deploy the Skeleton assets in the /bundles/emsch-assets folder. You can defined the one you want. But as the Skeleton is a Symfony project locate that folder in the bundles root directory make sens.

Edit your hosts file to add this line if is not already the case:

127.0.0.1       site-ems.test www.site-ems.test

So in theory you website should be visible at http://site-ems.test/ and your first asset http://site-ems.test/bundles/emsch-assets/main.js

Go to your elasticms an edit your base.html.twig template and add this line in your javascript section:

<!-- jQuery first, then Popper.js, then Bootstrap JS -->
<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js" integrity="sha384-UO2eT0CpHqdSJQ6hJty5KVphtPhzWj9WO1clHTMGa3JDZwrnQq4sF86dIHNDz0W1" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous"></script>
<script src="{{ asset('bundles/emsch-assets/main.js') }}"></script>

If you publish your template and reload the website at http://site-ems.test/ you should see qn Hello worl in your brozser console.

Install jQuery and Bootstrap

In you command prompt:

npm install --save bootstrap
npm install --save jquery -D
npm install --save popper.js -D

And re-run npx:

npx webpack --mode development

Than update your base.html.twig template:

{% extends '@EMSCH/template/variables.twig' %}
{% trans_default_domain trans_default_domain %}

{% block request %}
<!doctype html>
{%- set environment = app.request.get('_environment', 'live') -%}
<html lang="en" data-trans-default-domain="{{ trans_default_domain|e('html_attr') }}" data-environment="{{ environment|e('html_attr') }}">
  <head>
    <!-- Required meta tags -->
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

    {#<!-- Compiled CSS -->#}
    <link href="{{ asset('bundles/emsch-assets/css/index.css') }}" rel="stylesheet">

    <title>
        {%- if 'live' != environment %}
            {{ environment|upper }}:&nbsp;
        {%- endif -%}
        {%- block title %}Hello, world!{% endblock title %} | {{ 'site.name'|trans -}}
    </title>
  </head>
  <body>
    ....
    <!-- Optional JavaScript -->
    <script src="{{ asset('bundles/emsch-assets/js/index.js') }}"></script>
  </body>
</html>

You are now able to develop the web design that you want. You can also easily fork the webpack-demo-skeleton project which is a pre-configured webpack project.

Hint, you can use the watch parameter to avoid to re-run npx each time that you modify a source file:

npx webpack --mode development --watch

Deploy on the production server

Alright is now time to deploy it on the production environment. If you go to your production template environment you more likely see that the design is broken. And indeed on the production server there is nothing behind the /assets/emsch-assets base url.

First all all rebuid you Skeleton assets in production mode:

npx webpack --mode production

Go in your project's dist folder and archive its content into a zip file. Beware, not the dist folder itself!

Go to your elasticsms admin and create a draft for any content type having a file field. Ideally not an indexed file field. And upload the just created zip file. We don't care about that just created draft document, we'll discard it right away. Just get the zip's hash signature before discarding it, by clicking on :

The uploaded file info modal

Still in your elasticms admin interface, edit your variables.twig template and add those lignes:

{% set assetsHash = '1308ade92d3a76560604d5a3a000ef18d8ef153c' %}
{{ emsch_assets(assetsHash) }}

Go back in your production template website and refresh the page. That refresh is longer than usual. Go on your server and check the Skeleton bundles foler: /opt/web/sites/skeleton/public/bunldes you'll see a 1308ade92d3a76560604d5a3a000ef18d8ef153c folder and in it you'll see the content of your first Skeleton template archive. You'll also see a symlink  corresponding to the template translation domain key (instance id + template). So now you must update the template environment VirtualHost config:

<VirtualHost *:80>
    ServerName www.elasticms.eu
    ServerAlias elasticms.eu

    ServerAdmin admin@skeleton

    DocumentRoot /opt/web/sites/skeleton/public
    DirectoryIndex /index.php
    FallbackResource /index.php

    # Skeleton assets aliases
    Alias "/template/bundles/emsch-assets" "/opt/web/sites/skeleton/public/bundles/emseu_v4_template"

    # Environment aliases
    Alias "/preview" "/opt/web/sites/skeleton/public"
    Alias "/template" "/opt/web/sites/skeleton/public"
    Alias "/staging" "/opt/web/sites/skeleton/public"
....

If you have define environment aliases notice that the order of the alias directives has an importance. Restart your Apache server than reload your production template page: tadaaa!

Go back in your VirtualHost config and define the Skeleton aliases for you other environments:

# Skeleton assets aliases
Alias "/template/bundles/emsch-assets" "/opt/web/sites/skeleton/public/bundles/emseu_v4_template"
Alias "/staging/bundles/emsch-assets" "/opt/web/sites/skeleton/public/bundles/emseu_v4_staging"
Alias "/preview/bundles/emsch-assets" "/opt/web/sites/skeleton/public/bundles/emseu_v4_preview"
Alias "/bundles/emsch-assets" "/opt/web/sites/skeleton/public/bundles/emseu_v4_live"

Restart again your Apache server than your are now able to publish your templates (and the associated Skeleton assets archive) in every environment.