How to setup pyrocms theme and VUE.JS development environment

By: William
Category: PyroCMS

The following post, is a work in progress

This post is a work in progress. I will be updating it. Since I am almost certain there are errors here. Send me an email at william@williamastrom.se and ill make sure to correct them.

Step #1 - Pull in PyroCMS

composer create-project pyrocms/pyrocms pixney.dev

Step #2 - Create your .env file

APP_ENV=local
APP_DEBUG=true
APP_KEY=zfesbnTkXvooWVcsKMw2r4SmPVNGbFoS
DB_DRIVER=mysql
DB_HOST=localhost
DB_DATABASE=pixney2017
DB_USERNAME=homestead
DB_PASSWORD=secret
APPLICATION_NAME=pixney
APPLICATION_REFERENCE=pixney
APPLICATION_DOMAIN=localhost
ADMIN_EMAIL=william@pixney.com
ADMIN_USERNAME=admin
ADMIN_PASSWORD=password
LOCALE=en
TIMEZONE=UTC

Step three : Install

php artisan install --ready

Create personal theme

The example name of the theme here is thidrandi because i am copy and pasting things over from a site i am currently working on: Pixney.

Naming themes can be hard:) This is a true viking approach: Great name generator

Run the following artisan command to scaffold your theme:

php artisan make:addon pixney.theme.thidrandi

Delete stuff we don't need

When you scaffold the theme, a lot of files are included that we don't need if we set things up according to this example, so let's delete them. In your theme directory: addons/pixney/pixney/thidrandi-theme/resources/ delete :- fonts - js - scss

Configure elixir

There are cleaner and better approaches to this, but i'll just keep this short and effective.

Install elixir: npm install

Extra : Svgs

When you develop websites, you should limit the number of necessary http requests to make sure you develop a fast loading website. This is easily done by concatenation of your css and javascript files. But you should also stay away from using images or the img element when it is not necessary. Try to use svgs (inline) for icons and things like that. Don't include svgs this way: <img src="viking.svg"> - that doesn't save a http request!

But inlining svgs can easily turn out to be messy. To avoid that, i am always using a tool called SVGSTORE. It creates a svg sprite of all your svgs keeping your html documents clean and easy to read.

We are going to create a svg sprite. Doing so, we need to install and use svgstore:

npm install --save-dev gulp-svgstore gulp-svgmin path gulp-cheerio

We will need to reference these in our gulpfile. But for now, let's move along.

Place all your original SVGS, in dev/svgs. Then run gulp svgstore (we will setup this task below) and it will create a svg sprite file for you and store it in resources/svg. Copy and paste this svg sprite at the bottom of your html / twig file. To reference an svg this way you simply do: <svg class="logo"><use xlink:href="#pixneylogo" /></svg>.

Gulpfile

To be able to use elixir we need to set it up to make sure it works with our theme. Per default laravel uses other directories within your resources directory for sass and javascript files. We want to keep this to our pyrocms theme directory instead.

Within the resources directory of our PyroCMS theme, i create another folder and call it dev.

Once that is done, i copy the js files from the original laravel structure into our theme: cp -R resources/assets/js addons/pixney/pixney/thidrandi-theme/resources/dev/

This is how my directory structure looks:

addons/pixney/pixney/thidrandi-theme
 - resources
   - css
   - dev 
     - js
     - sass
     - svgs     // This is where i keep all my original svgs
     - vendor
   - js
   - lang
   - svg        // Svg location after running svgstore
   - views 
 - src

Within our gulpfile, we need to make sure elixir knows about our theme path and where to do its magic. Below we are letting elixir know to compile our sass from resources/dev/sass, our js from resources/dev/js our svgs from resources/dev/svgs and then output the results to resources/css, resources/js and resources/svg :

const elixir = require('laravel-elixir');

Elixir.config.assetsPath = 'addons/pixney/pixney/thidrandi-theme/resources/dev/';
Elixir.config.publicPath = 'addons/pixney/pixney/thidrandi-theme/resources';

Great! Now lets add the reference to our gulp stuff we added earlier. Since you hopefully know what we are doing, ill show you my finished gulpfile:

const elixir = require('laravel-elixir');
Elixir.config.assetsPath = 'addons/pixney/pixney/thidrandi-theme/resources/dev/';
Elixir.config.publicPath = 'addons/pixney/pixney/thidrandi-theme/resources';
require('laravel-elixir-vue-2');
var svgstore        = require('gulp-svgstore');
var svgmin          = require('gulp-svgmin');
var path            = require('path');
var cheerio         = require('gulp-cheerio');


// SVG SPRITES -----------------------------------------------------------------
gulp.task('svgstore', function () {
    return gulp
        .src('addons/pixney/pixney/thidrandi-theme/resources/dev/svgs/*.svg')
        .pipe(svgmin(function (file) {
            var prefix = path.basename(file.relative, path.extname(file.relative));
            return {
                plugins: [{
                    cleanupIDs: {
                        prefix: prefix + '-',
                        minify: true
                    }
                }]
            }
        }))
        .pipe(svgstore({ inlineSvg: true }))
        .pipe(cheerio({
            run: function ($) {
                $('svg').attr('style',  'display:none');
            },
            parserOptions: { xmlMode: true }
        }))
        .pipe(gulp.dest('addons/pixney/pixney/thidrandi-theme/resources/svg'));
});
// SVG SPRITES -----------------------------------------------------------------


elixir(mix => {
    mix.sass('pixney.scss')
    .webpack([
        'app.js',
    ]);
});

Installing Bower

I normally use NPM, but sometimes you might wanna use bower. I am just adding a quick setup instruction (how i do it) here as reference.

npm install bower

Add .bowerrc in your project root

{ "directory": "addons/pixney/pixney/thidrandi-theme/resources/dev/vendor" }

bower.json JSON Example

Now, its better if you pull in most of this through npm and require it trough your bootstrap.js file.

{
  "name": "thidrandi",
  "description": "",
  "main": "",
  "license": "MIT",
  "homepage": "",
  "private": true,
  "ignore": [
    "**/.*",
    "node_modules",
    "bower_components",
    "addons/pixney/pixney/thidrandi-theme/resources/dev/vendor",
    "test",
    "tests"
  ],
  "devDependencies": {
    "bootstrap": "^4.0.0-alpha.6",
    "jquery": "^3.1.1",
    "slidebars": "^2.0.2",
    "bLazy": "blazy#^1.8.2",
    "parsleyjs": "^2.6.0",
    "swiper": "^3.4.1"
  }
}

Configure our theme files

Now, lets adjust the twig files included.

metadata.twig

asset_add("theme.css", "theme::css/thidrandi.css",["min"])
asset_style("theme.css")

constants()

for style in asset_styles("styles.css")
    style|raw
endfor

default.twig

asset_add("theme.js", "theme::js/app.js.js") 
html_script(asset_path("theme.js")) 

block js deferred 
    include "theme::partials/js" 
endblock 

Disclaimer

This post is a work in progress. I will be updating it. Since I am almost certain there are errors here. Send me an email at william@williamastrom.se and ill make sure to correct them.