A car picker tool for Mini.

1. Requirements
2. Front End Project overview
   1. Scripts / libraries used in the project
   2. Directory structure
3. Installation
4. Grunt
   1. Grunt tasks
   2. OS X workflow
   3. Windows workflow
   4. Rendering Razor views and copying assets
5. .NET integration
6. CSV data import
7. Troubleshooting

Disclaimer

This document assumes you're using a Mac. If you're on Windows, you will not be able to generate web fonts. For production, always build the project on an Apple machine.

• Node.js
• Bower
• Grunt
• FontForge via Homebrew

1. First, install Node.js.

2. Install Grunt:

   npm install -g grunt-cli
   

3. Install Bower:

   npm install -g bower
   

4. Install Homebrew.

   ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
   

5. Install FontForge and ttfautohint.

   brew install ttfautohint fontforge --with-python
   

Note

Steps 4 and 5 won't work if you're on a Windows machine. Click here to read on how to compile the project in Windows.

• LESS Hat
• jQuery
• jQuery Validation
• Underscore
• GreenSock Draggable (used to create touch-friendly dials)
• SVGInjector
• Mustache
• TaffyDB (used to query JSON data in a SQL-like fashion)
• store.js (used to persist user selection across the screens)

An asterisk denotes a directory created during the build process. Please see the table below to find out more information about some of the directories.

assets/
	cars/
	css/*
	fonts/
		icons/*
		mini/
	icons/
	img/
		sprites/*
	js/
		htc/*
		src/
		tpl/
	less/
		dials/
	sprites/
		svg/
bower_components/
dotnet/
grunt/
json/
landing-page/
node_modules/
prototype/
	assets/
razor_src/
razor_templates/*

Once you've successfully installed all the required tools, it's time to install project dependencies.

1. cd into the project folder and install Node.js packages:

   npm i
   

2. Then install Bower packages:

   bower install
   

And you're done!

This website makes extensive used of the Grunt.js build tool. There's a bunch of things happening in the background, but all you need to know, are just a few tasks:

Typing grunt will run grunt compile and then grunt watch.

Running the following tasks will compile the front-end locally:

grunt squeaky-clean grunt generate grunt to compile & watch or just grunt compile

grunt tidy grunt windows grunt to compile & watch or just grunt compile

Follow the Windows workflow and then type:

grunt dotnet

To keep the front-end and the back-end separate, we're using grunt-processhtml to perform search and replace in the *.php files in order to convert them into Razor views which can then be copied into the dotnet/ directory.

The basic idea is that we write two instances of the code inside the *.php file, one for the PHP version, and one for the .NET, like this:

<div class="form-control">

	// Razor version
	@Html.TextBoxFor( model => model.FirstName, new { id="field-name", name="name", placeholder="First name" } )​

	// Static HTML / PHP version
	<input type="text" id="field-name" name="name" placeholder="First name" />

</div>

For obvious reasons, PHP won't render Razor syntax and .NET won't render any PHP syntax, for example <?php require( 'header.php' ); ?>, therefore we must somehow get rid of one of them depending on the version we want to deploy. We can easily achieve this by using the grunt-processhtml plugin, which can manipulate blocks of HTML.

We will use it to make string replacements and to remove certain blocks of HTML.

Have a look at an upgraded version of the code we've seen before:

<div class="form-control">

	// Razor version
	<!-- build:template
	<%= form.field.name %>
	/build -->

	// Static HTML / PHP version
	<!-- build:remove --><input type="text" id="field-name" name="name" placeholder="First name" /><!-- /build -->

</div>

grunt-processhtml can process lodash-style templates using any data passed to it's options object, so we can easily define replacements for those template tags in Gruntfile.js, like this:

processhtml: {
		
	options: {
	
		data: {

			global:			grunt.file.readJSON( razor + '/global.json' ),
			form:			grunt.file.readJSON( razor + '/form.json' ),
			details:		grunt.file.readJSON( razor + '/results-details.json' ),
			results:		grunt.file.readJSON( razor + '/results.json' ),
			home:			grunt.file.readJSON( razor + '/home.json' ),
			dashboard:		grunt.file.readJSON( razor + '/dashboard.json' ),

		}

	}

}

Essentially, we're simply storing Razor syntax inside *.json files, so they can be processed by grunt-processhtml.

Here's a example of the razor_src/dashboard.json file:

{
	
	"bums":				"@Html.Partial(\"_ControlBums\")",
	"mpg":				"@Html.Partial(\"_ControlMpg\")",
	"lifestyle":		"@Html.Partial(\"_ControlLifestyle\")",
	"luggage":			"@Html.Partial(\"_ControlLuggage\")",
	"options":			"@Html.Partial(\"_ControlOptions\")",
	"speed":			"@Html.Partial(\"_ControlSpeed\")",
	"price":			"@Html.Partial(\"_ControlPrice\")",
	"start":			"@Html.Partial(\"_ControlStart\")"

}

Because it's defined in options.data as dashboard, we can acces it's JSON object by simply calling <%= dashboard.bums %> in the template.

The last thing we need to do, is to remove the static HTML / PHP code, by wrapping it in <!-- build:remove --> tags.

Warning

Never make direct changes to any files in the dotnet/Combobulator/Views/ as they will be removed each time grunt generate is run. Moreover, making changes inside that folder will make it difficult to keep both the front-end and the back-end in sync. Feel free to write and test Razor syntax in those files, but once you're finished, copy them over to a corresponding *.json file before committing your changes.

Data comes from the client (via the PM and AM teams) in CSV format, exported from Excel. To import this there is an ImportController excluded from the C# project — simply follow these steps:

1. Open the CSV file in your text editor of choice.

2. There is more than one Price column in the source data; you may need to change Price to Finance_Price.

3. Save the file in ~/App_Data, converting it to UTF-8.

4. In SQL against your "local" database (which should hopefully be our shared dev SQL server Justforkix):

   Delete From Cars;
   Delete From Finances;
   

5. In the C# project, include the ImportController back into the solution and Build or Debug so you can access it in a browser.

6. Go to your local instance of ~/Import?type=csv, which currently provides no output. (We should fix this.)

7. Make sure you re-exclude the ImportController from the solution, so it never goes live!

8. From Visual Studio, generate Insert scripts for your "local" Cars and Finance tables.

9. Execute these Insert scripts (deleting first, if the scripts do not do so) on the Dev and QA database — database MINI_FS_QA on Rackspace Shared Windows Staging, then test on Dev.

10. Once you're happy with the content on Dev, check on QA, if the codebase differs.

11. Once you're happy with the content on QA, execute the scripts (or DTS the tables Cars and Finance) onto Staging — database MINI_FS on the same server, and test on Staging.

12. When everything is finally signed off, deploy those changes to Production in the same manner.

grunt-processhtml is known to cause some problems when using the latest version - in particular it doesn't remove blocks of code between <!-- build:remove --> tags.

Installing 0.3.6 solves this issue:

npm install grunt-processhtml@0.3.6 -save

If you happen to run grunt squeaky-clean on a Windows machine, you will need to generate icons in order to compile the app.

Warning

Always remember to revert back to fontforge in production. Never commit settings.iconEngine set to node. It will fail to generate proper fonts.

To do so, change temporarily the font-hinting engine used by grunt-webfont.

You can do it by changing settings.iconEngine to node in combobulator.json.