Developer Guide: Editing CSS and JavaScript

From Mothership
Jump to: navigation, search

CSS files and JavaScript files are known in Mothership's codebase as assets and are largely treated the same way. Mothership compresses these files in a process called 'minification', which merges the individual files into one single file, removing unnecessary white space and code comments in the process.

Adding a JavaScript file

To add a JavaScript file, first ensure that it exists within the /app/site/resources/assets/js directory. You will then need to add it to the main template to ensure that it gets included in the site.

Open the /app/site/resources/view/templates/blocks/javascript.html.twig file, and it should look like this:

{% javascripts
    '@Mothership:Site::resources/assets/js/jquery.1.11.1.min.js'
    '@Mothership:Site::resources/assets/js/jquery.gallery.js'
    '@Mothership:Site::resources/assets/js/jquery.menu.js'
    '@Mothership:Site::resources/assets/js/jquery.carousel.js'
    '@Mothership:Site::resources/assets/js/jquery.offcanvas.js'
    '@Mothership:Site::resources/assets/js/jquery.basket.js'
    '@Mothership:Site::resources/assets/js/jquery.setup.js'

    output='/assets/js/ms-site-*.js'
%}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

This file is telling Mothership all of the JavaScript files it wants to include, and minify them into one file. Each item in the list at the top of the file represents a JavaScript file. The @Mothership:Site:: tells Mothership that it exists within the main site module, and then the rest is the path from within that module. So to add a file with a path of /app/site/resources/assets/js/my-javascript-file.js, you simply amend this file to include it in the list:

{% javascripts
    '@Mothership:Site::resources/assets/js/jquery.1.11.1.min.js'
    '@Mothership:Site::resources/assets/js/jquery.gallery.js'
    '@Mothership:Site::resources/assets/js/jquery.menu.js'
    '@Mothership:Site::resources/assets/js/jquery.carousel.js'
    '@Mothership:Site::resources/assets/js/jquery.offcanvas.js'
    '@Mothership:Site::resources/assets/js/jquery.basket.js'
    '@Mothership:Site::resources/assets/js/jquery.setup.js'
    '@Mothership:Site::resources/assets/js/my-javascript-file.js'

    output='/assets/js/ms-site-*.js'
%}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

Adding a CSS file

Adding a CSS file is a very similar process to adding a JavaScript file. Ensure that it exists within the /app/site/resources/assets/css directory, and then add it to the main template.

Open the /app/site/resources/view/templates/blocks/stylesheets.html.twig, and it should look like this:

{% stylesheets
    '@Mothership:Site::resources/assets/css/basic.css'
    '@Mothership:Site::resources/assets/css/layout.css'
    '@Mothership:Site::resources/assets/css/fonts.css'
    '@Mothership:Site::resources/assets/css/account.css'
    '@Mothership:Site::resources/assets/css/styles.css'
    '@Mothership:Site::resources/assets/css/mobile.css'

    output='/assets/css/ms-site-*.css'
    filter='csscogulerewrite,?cssmin'
%}
    <link rel="stylesheet" href="{{ asset_url }}">
{% endstylesheets %}

{% stylesheets
    '@Mothership:Site::resources/assets/css/ie9.css'

    output='/assets/css/ie9.css'
    filter='csscogulerewrite,?cssmin'
%}
    <!--[if lte IE 9]>
        <link rel="stylesheet" href="{{ asset_url }}">
    <![endif]-->
{% endstylesheets %}

Unlike the javascripts.html.twig, this file creates two CSS files - one vanilla stylesheet, and one to show up if the user is using Internet Explorer 9. Much like with JavaScript files, the CSS files are listed at the top of the stylesheets block, ensuring that these get minified into one file and included in the page view. The @Mothership:Site:: tells Mothership that the file exists in the main site module. To add a file that exists at /app/site/resources/assets/css/my-stylesheet.css, simply add it to the list:

{% stylesheets
    '@Mothership:Site::resources/assets/css/basic.css'
    '@Mothership:Site::resources/assets/css/layout.css'
    '@Mothership:Site::resources/assets/css/fonts.css'
    '@Mothership:Site::resources/assets/css/account.css'
    '@Mothership:Site::resources/assets/css/styles.css'
    '@Mothership:Site::resources/assets/css/mobile.css'
    '@Mothership:Site::resources/assets/css/my-stylesheet.css'

    output='/assets/css/ms-site-*.css'
    filter='csscogulerewrite,?cssmin'
%}
    <link rel="stylesheet" href="{{ asset_url }}">
{% endstylesheets %}

Adding a CSS file for older versions of browsers

CSS files for inclusion in older versions of browsers only need to exist in separate minified files, and therefore different stylesheets blocks. The syntax for this is almost identical to the vanilla block, except the include tag is wrapped in HTML if comments. So if we wanted to add a file that allowed backwards compatibility for Internet Explorer 8, called ie8.css, you would simply add:

{# Open the stylesheets block and the file to the list: #} 
{% stylesheets
    '@Mothership:Site::resources/assets/css/ie8.css'

    output='/assets/css/ie8.css'
    filter='csscogulerewrite,?cssmin'
%}
    {# Wrap the include in an if statement #}
    <!--[if lte IE 8]>
        <link rel="stylesheet" href="{{ asset_url }}">
    <![endif]-->
{% endstylesheets %}

Applying your changes

If you are adding new files, you will need to run bin/cog asset:dump in your terminal from the base directory. This will copy the new files into the public directory.

If you are editing existing files, you may find that the changes do not take effect immediately. Mothership currently needs to be told to minify the assets, and there are two main ways to do this:

Automatic asset generation

It is possible to minify your assets automatically, by editing the config/asset.yml and setting the auto-generate option to true. This will automatically minify all assets required for that particular page on page load. This is useful if you are making changes to the CSS and JavaScript files regularly, but cause page loads to be very slow.

Note: Automatic asset generation will only work if the environment is set to local

Manual asset generation

To manually minify the assets, run sudo bin/cog asset:generate. This is useful if you are only making small changes to the site, or are downloading recently made changes from Github. Running the task can take a long time as it will minify all assets across the whole site.