Rebuilding Wardrobe: Week 2

This is the second week in a series on rebuilding WardrobeCMS, the minimal blogging engine. Here is the link to last weeks in case you missed it and want to get caught up.

For this week I want to accomplish two main goals. The first is to get a base install of Laravel 4.3 going and start an admin style guide.

The first step for me is to create a new github repo so I have a publicly available place for you to browse both the code and changes. I created a new rebuilding-wardrobe repo and each week will have a new branch so you can follow along with the progress.

After creating the repo I grabbed a fresh copy of Laravel 4.3 and got it running on my local Homestead. Keep in mind that 4.3 is currently beta and things will change between now and the official release date in November. I’m hoping not much changes in the base Laravel repo but I have no guarantees and that’s part of the fun of using a beta.

Create A Package

With it running locally I’ve knocked out my first item really quickly, however before I start a style guide I need to make a few decisions. The first goes back to one of my original goals, “Easy upgrades”. If I do all the work in a base install of the framework then that will be impossible. This is what workbench packages are for and I need to start with that right away.

Creating the package is as easy as running:

php artisan workbench vendor/package --resources

But wait…. I need a package name.

In v1 I used the name core, a beta I never finished used the name cabinet, so I think this should differ from both of those. How about wardrobe/drawer? Yes, naming is hard and I’m just going with it.

php artisan workbench wardrobe/drawer --resources

Next, I add it to the config/app.php providers and I’m up and running. I should go ahead and commit this and that is when I hit another question. Eventually I will have two repos, one for the base Laravel install, and another for the package. I don’t want to separate these right now and would rather wait until the end. So I will just commit the whole thing. This will give you the opportunity to pull it down and it should just work without having to setup anything manually.

Style Guide

When I say style guide I’m referring to the visual side of the app, the CSS and HTML. Here is a great write up on creating style guides if you aren’t familiar with them. For an app like this creating a style guide is probably over kill, but I’ve wanted to create one for a project and haven’t had the opportunity. Plus it will be a great learning experience for me for future projects. Styles are the one area that can get quickly out of control. This should help with that.

A style guide should be a single page living document and ideally automated. When new features are added it would be great if we could have them automatically inserted. Another advantage to having them all on one page is by using an auto reload plugin I can just have the style guide open and refactor to my hearts content.

My idea on a way of setting this up is to use a “views/modules” folder which will contain all the sections of the site and then just iterate that directory and add the views in. You can see this in action in the routes and styleguide.blade.php files.

Now when I start creating the real views I can just @include these modules wherever I want and everything will stay in sync.

Themes

From last weeks planning I decided that I should create a few admin themes and have a theme selection in the admin settings. For the first release I’ll have a light and a dark theme.

I debated on how these should be created and came up with the following two ideas:

The first idea is to just break it into two stylesheets that would be added to the html. Structure.css and then one for the color, this way if when you switch themes you’ll have structure cached and it will just be a very minimal new stylesheet with the various colors.

The second way, which is what I decided to use, is to just define new sass files for the different themes. Then each will have variables and all the imports. This way the layout only imports the one style sheet for the selected theme. Here is the current sass file for the light theme:

// Break points
$bp-small: 320px
$bp-medium: 500px

// Backgrounds
$primary-bg: #fafafa
$secondary-bg: #fff

// Fonts
@import url(http://fonts.googleapis.com/css?family=Nunito:400,700,300)
$base-font: 'Nunito', sans-serif

// Navigation Bar
$nav-bg: $secondary-bg
$nav-link-color: #74777b
$nav-link-active-color: #629DCC

// Body
$border-color: #ebebeb

// Positive Color
$positive-color: $nav-link-active-color

// Imports
@import base/normalize
@import layout/structure
@import modules/nav
@import modules/forms
@import modules/post

I do have a concern about going this way, it could potentially make it more difficult for third parties to create their own themes. Since the sass files are hidden inside the package they may not have an easy way of pulling the imports in. Now I need to start compiling these and that’s where Gulp comes in.

Gulp

Gulp, if you are not aware, is a build system for pretty much anything. I’ve seen tasks for node, css, sass, less, phpunit, and on and on. If you can imagine it a package probably exists. For this week all I need is to setup styles and will add more to this over time.

One thing to note about this step is that instead of installing Gulp in the root it needs to be in the package. This isn’t a big deal and just requires cd’ing into workbench/wardrobe/drawer directory and running the npm commands there.

Tip: Before you run npm commands create a package.json file with an empty json object in it. That way the npm --save-dev flag will add dependencies automatically.

Here is the command I ran:

npm install gulp gulp-autoprefixer gulp-ruby-sass gulp-notify --save-dev

I want to point out that I used gulp-ruby-sass instead of the node version. From what I’ve read the node version runs faster but it doesn’t match one to one with Ruby Sass features. I don’t think either would be an issue for this project but this is something to keep in mind if you are trying deciding between which one to use.

The final step with gulp is creating the gulpfile.js and verify it works. Here is the full file I created for reference and I’d like to expand on two areas of the file:

var config = {
  sass: {
    watch: './assets/sass',
    themes: [
      './assets/sass/light.sass',
      './assets/sass/dark.sass'
    ]
  }
}

In that code block I’m just setting up a config object with a path to the sass folder and an array of stylesheet files. Next is my css task:

gulp.task('css', function() {
  config.sass.themes.forEach(function (theme) {
    return gulp.src(theme)
    .pipe(sass({ style: 'compressed' })
      .on("error", notify.onError(function (error) {
        return "Error: " + error.message;
      })))
    .pipe(autoprefix('last 2 version'))
    .pipe(gulp.dest('../../../public/packages/wardrobe/drawer/css'))
    .pipe(gulp.dest('./public/css'));
  })
});

Because of the config.sass.themes array I can now loop these in this task and create all the stylesheet files without having to duplicate. Finally notice that I’m piping to two different locations. The first is the Laravel base install public directory and the second is the package public directory. I did this so I wouldn’t have to run php artisan publish:assets over and over in development.

Screenshot

This is a screenshot of both themes as they are right now. Really the only part I’m relatively happy with is the navigation bar, and it’s something I just happen to come across. The rest is just okay to me and I already want to work more on the styles. So don’t consider this a finished design. I’m out of time this week and I’m really wanting to get into coding so this will have to wait.

Getting This Weeks Code

Here are instructions for grabbing the code from git:

git clone git@github.com:ericbarnes/rebuilding-wardrobe.git && cd rebuilding-wardrobe

Next checkout and switch to the week-2 branch:

git checkout -f week-2

Wrap Up

This week I accomplished my two goals but as I mentioned I’m not completely happy with the design. The main thing is getting the base in place so now future changes and adjustments should come much quicker. For next week I plan on starting with migrations and getting at least a few routes working. I do have some planning to do around integrating with existing apps but I think I have a simple solution that you will like. You’ll just have till next time for more details.

Thanks again for following with this series and if you have any comments, questions, or observations post them below.