====== Toshiba - Generic page builds ======
----

We have set up a base template to work from in order to quickly create a generic Toshiba page build without having to create common required CSS overrides and basic Toshiba page frameworks from scratch.

=====  Prerequisites  =====

Each developer will need to have Ruby, SASS, Node.Js and grunt installed on their machine. To fully make use of the ToshibaGeneric starter build, the instructions in the [[developer_get_started|developer setup]] page should be followed first.

=====  Setting up  =====

Before starting, make sure that a new Mercurial repository has been set up for the project. Next, you will need to clone the //ToshibaGeneric// repository to a directory which exactly matches the name of the repository for the new project (e.g. //C:SourceNewProjectName//).

Once the project has been cloned locally, you can run the setup.bat task which will initialise the correct folder structure and install grunt packages through the Node Package Manager. These are required to compile SASS to CSS as well as to minify JavaScript files.

You can delete the setup.bat file once this process is complete.

Next, you can use the run.bat file to start watching your SCSS files for changes and to run the project in your localhost.

=====  CSS & JavaScript  =====

The main stylesheet for Toshiba Generic builds are to be kept within //app.css//, initially generated from //app.scss// using SASS. JavaScript should mainly be written to //app.js// which, when using Grunt to watch your file updates, will be minified to //app.min.js// should you wish to use a minified version for production.

=====  Full width builds  =====

If your project needs to be full width, utilising a Toshiba generic template other than //Generic 5//, you will need to update the following lines within //app.scss//:

<code>@charset "UTF-8";

/* you need to use EITHER ToshibaGeneric or ToshibaGenericFullWidth, so comment out/in accordingly below */
/*@import '../includes/ToshibaGeneric';*/
@import '../includes/ToshibaGenericFullWidth';</code>

You will also need to replace the contents of //index.html// with //index_full_width.html//, as this includes the necessary HTML elements for Toshiba header and footer.

As a final step, the correct Toshiba footer HTML needs to be chosen as both EU and UK footer content is present in the //index_full_width.html// file.

=====  Compiling with run.bat  =====

A Windows batch file - run.bat - has been set up for your convenience in the top level directory of the ToshibaGeneric starter template. Running this file will open 2 command prompt windows:



    * Grunt task to run your project over the localhost of your machine. Port 8000 is the default configured ([[http://localhost:8000|http://localhost:8000]], although this can be changed by altering the values in the gruntfile.js file.
    * Grunt task to watch for file changes. This will handle SASS to CSS compilation and JS minification.



**If you are having any issues, check through the [[Toshiba_Generic_Page_Builds#Prerequisites|prerequisites]] and the initial [[developer_get_started|developer setup]] instructions.**

=====  Compiling with Grunt on the command line  =====

If you prefer not to use the provided run.bat batch script, you can use Grunt directly to watch your file changes. We use Grunt to watch and run a task to compile SASS to CSS, as well as to minify JavaScript. Grunt will already be installed if you have run the setup.bat file included in the Toshiba Generic project.

To run Grunt, see the instructions below:


    * Navigate to the folder containing the //node-modules// directory and type the following into the address bar:''%%cmd%%''
{{:cmd.jpg?400|}}
    * Now type the following and press the Return key: ''%%grunt watch%%''
    * You should now be able to edit the SCSS / JS files within the project and see them compile and validate as you save.
{{:grunt_sass.png?400|}}
    * //If not, you may be within the wrong directory, or you may need to re-install the node packages for Grunt:// ''%%npm install%%''


=====  SASS variables  =====

There are a number of SASS variables, prefixed with a //$// symbol, which can be used in your project. For instance, common Toshiba colours are held in the following varaibles:

<code>$toshRed: #ff0000;
$toshGreen: #66BD29;
$toshLblue: #00AECB;
$toshBlue: #003479;
$toshPurple: #9F60B5;
$toshOlive: #8E9300;
$toshOrange: #FF6418;</code>

These can then be used in the following way:

<code>p.green { color: $toshGreen; }</code>

Additional variables can be added into the ToshibaGeneric SVN project for use in future projects. The file location for these variables within the project is <code>images/local/en_EU/ToshibaGeneric/includes/ToshibaGeneric.scss</code>.

=====  Useful SASS mixins  =====

Within the includes folder is a file called //mixins.scss//. This contains an array of commonly useful SASS mixins such as vendor-prefixed CSS3 transitions and cross-browser opacity. Get to know these mixins and contribute any you want to add to the Toshiba Generic SVN repository.

=====  Finishing up  =====

While SASS is used to create and compile CSS initially, it is necessary to remove all //.scss// files from the project once it has been deployed to the Toshiba Stage environment. This allows future content editors to make small CSS tweaks without the need for SASS knowledge. This is also why we don't minify production CSS for generic Toshiba pages.