Diving into FTP development with REC

As well as via the admin interface, you can use FTP to gain a greater level of control over the design of your REC site by being able to directly access the files. Why is this useful?

Prerequisites

We'll need an editor to work with the template files, for the purpose of this demo we'll be using Sublime Text 2, although there are plenty others you may prefer such as Brackets, Atom, Dreamweaver, more info on choosing an editor here.

(UPDATE: I have a new post on using Atom, a free text editor, instead of sublime in case you're interested. You can still use this post for getting started if you skip over the sublime references, down to First time notes)

(UPDATE 2: & a newer post (2019) for vscode & live reload)

With which ever editor you choose you'll need to use FTP to transfer files back and forward between your computer and the site, either setup within the editor or you can use a separate ftp client such as the Filezilla Client.

But here we'll use Sublime Text's excellent SFTP package.

Checklist:

1. Sublime Text 2 installed (http://www.sublimetext.com/2)

2. Sublime Package Control installed (https://packagecontrol.io/installation#st2)

3. Sublime SFTP plugin installed (https://wbond.net/sublime_packages/sftp/installation)

Starting a new project

To start we'll want to create a new folder to work in and open Sublime Text with our site files in ready to begin coding. Follow these steps for Sublime Text.

Create a folder for us to work in
Open Sublime
(In Sublime) "Projects" > "Add Folder to Project..."
(In Sublime) right click on folder name in sidebar > "SFTP/FTP" > "Map to Remote..."
Setup the sftp-config.json file
- set the type as either "ftps" or "ftp" instead of "sftp" (ftps is a more secure choice)
- set your host, user and password (found in your REC site > Admin > FTP Account)
- port is 21
- set file permissions: "file_permissions": "666", "dir_permissions": "777",
- choose other useful configuration, e.g.
  - "upload_on_save": true, - To always upload back to the server when you save the file
  - "sync_down_on_open": true, - To always re-download the latest version of a file from the server on open
- Here's an example config for you to compare to if you'd like.
Save the sftp-config.json file
Now download the current files, (In Sublime) right click on folder name in sidebar > "SFTP/FTP" > "Download Folder"
If everything was configured ok it should start to download all the template folders into your folder. If you have any issues try switching from ftps to ftp, but please leave a comment at the bottom if you have any issues.

First time notes

Things to keep in mind when developing within REC.

File Permissions

The *-base folders are locked, you won't be able to change or delete these files and folders on the site.
but you can work within the *-site folders, by default you'll want to work in the "responsive-site" folder
and you can create new folders for new templates or variations on your design, e.g. a Christmas folder for any minor tweaks to promote extra Christmas sales

HTML files

These are the core template files
The 0-base, legacy-base and responsive-base are our officially updated themes. Legacy-base is for sites built before responsive-base came out.
Your files will sit in your template folder, and by default this is the "responsive-site" folder.
Files in a child template like responsive-site override the parent template files such as responsive-base.
E.g. When the system renders the middle section of the page (html/layouts/index.html.twig) it first looks for this file in the live template folder, e.g. responsive-site. If that file is found here it will use it, else it will check it's parent folder, responsive-base, if the files found here it will use it, else it will check in the parent of this parent template, 0-base.
The syntax used in these files in HTML + Twig.
Twig is a template language we use to allow you access to the system, e.g. to show variables such as a products name ( e.g. {{ product.name }} ) and price on the products page ( html/store/product_info.html.twig )
Documentation is available on Twig and there's a playground to test Twig ideas outside of REC.

CSS / JS files

Store your css in css/site.css.twig inside your template folder.
Same for your js, store inside js/site.js.twig
You can however include multiple other files into these files with Twig, we'll talk more about this later :)
The "responsive-base/css/" folder is full of useful css files, mainly in the "modules/" folder, where all the style of the site is stored.
Like the html files you can place a file in the same location but in your responsive-site folder and it will override it, but if you do you'll loose updates to this file as you'll be overriding it.
This works well such as for replacing the nav styling entirely, you'd want to remove the default style and you would not care about the upgrades to it, as you'd be using your own custom version.
But if you wanted to keep using the same nav and only make a minor change to it would be best to make your changes in a separate file loaded from site.css.twig
The css/main.css.twig and js/main.js.twig files as seen in the responsive-base folder are the main files used to include all the other files we use to build the template. Don't override these files, as you'd loose new files being included and any other updates to it. Instead use the css/site.css.twig and js/site.js.twig files. These site files are included at the bottom of the main files. You can use them to include other files in the same way but we leave these files blank purposefully for you to use.

Javascript / jQuery

jQuery comes pre-installed in all REC sites.
We currently use version 1.11.3, and you can change this by overriding the html/sections/head/jquery.html.twig file like all others.
However in REC $ does not by default reference to jQuery as we have an older javascript lib also included called Prototype.js. In time we'll remove Prototype.js but when using jQuery you'll need to wrap your code so that you $ is jQuery for you. This can be done with:

(function ($) {

// your code... executed immediately, before dom ready

}(jQuery));

jQuery(function ($) {

// your code... executed on dom ready
// same as using jQuery(document).ready(function ($) { ... });

});

Caching

Our css/js/images etc. all cache in the browser for 1 month.
This is great for performance, but during development you'll want to always see your latest code changes.
You'll either want to always use hard refreshes
or set your browser to not cache (e.g. in chrome's developer tools, on the network tab you can tick to disable cache, this will force hard refreshes for you automatically when)
Also once you've finished work via ftp you'll want to bump the version for users browsing the site if it's already live. You can do this in REC site > Admin > Templates > "Bump Cache Buster".

Diving in

Currently I'm working on a redesign of Impkids clothing site.

I have a few tasks to work through with you here including:

Enable preview mode, as this is a live site currently running the legacy-site template and I don't want the changes to show till I'm done.
Move the slider next to the sidebar above the main content, instead of above the entire middle section as it is by default.
Style the outer design of the site in css.

Preview mode

First, lets enable the preview mode. REC site > Admin > Templates > Hover over the responsive-site template folder and click "Preview".

This will open a new tab with the site in for you, and you're ready to start work in this folder in a preview that only you can see.

Moving the slider

Now we'll work on moving that slider.

If we look in responsive-base, the default layout file that loads in the slider is at html/layouts/index.html.twig. So we need to create a file at this same path, and the layouts directory it's in.

In Sublime you can create a new folder by right clicking on the parent folder, in our case responsive-site/html/ and then select "New Folder...". Then the same to create a new file except click "New file...".

In this file we'll copy the contents from the responsive-base version and paste into our new responsive-site file.

With this file copied in we can take the slider block and move it down to under the <main> element.

Lines 12 to 17 should be:

{# slider #}
{% block content_slider %}
    {% if page.show_content_slider %}
        {{ page.content_slider }}
    {% endif %}
{% endblock %}

Which is inside the middle div/section of the page, but we want it to the side of the sidebar so if you cut this chunk out and paste onto what is now line 26, just above the {% if page.show_content %} area.

Save the file and with our FTP sync setup previously it should send this file up to the server.

Styling the layout

The existing Impkids site has a nice outer design where the main column has a white background with a shadow over a light orange background.

We can use css to recreate this in our responsive design.

As mentioned above, we will be putting our CSS into the css/site.css.twig file in responsive-site.

The responsive-site directory comes with this file ready and left blank for you.

/* ----- Main outer theme ----- */
body {  
    /* light orange background */
    background-color: #FDC288;
}
/* the layout container is used for the main 3 sections of the page, the header, middle and footer */
.layout-container {
    /* We want the main content on a white background */
    background: #FFF;
    /* with a semi-transparent shadow to the sides */
    box-shadow: 0 20px 20px rgba(0, 0, 0, 0.3);

    /* Add some margin to reveal the box-shadow too */
    margin: 0 15px;
    /* and some padding so content inside the layout is not too close to the edge */
    padding: 0 15px;
}

This gives us the outer design, but lets also talk about the header design.

Impkids logo image is a little unusual, usually the site's logo is uploaded via Admin > Site Setup, however for Impkids it's not and we don't want to upload it now as to not affect the live site in any way.

Instead we will set the logo on the currently blank header-logo element in the header and size it like so:

/* header logo */
.header-logo {
    background: url("/userfiles/impkids/images/IMPLOGO.png");
    position: absolute;
    width: 185px;
    height: 140px;
    left: 32px;
    top: -3px;
    z-index: 999;
    color: #FDC288;
}

This gives us our header logo image, and next we can move onto the navigation...

We want to move the navigation over to the side of the logo on larger screens and style it like the current site.

I won't go through all the css here but you can see we're moving the nav over (leaving space for our logo), making the nav top of the nav transparent by default and the sub links have a white background.

Then the active link and hover links are large orange bubbles around white text.

The difference here is I only want to change this on larger screens, on the phone and small tablet size we want to use the default nav as it's optimised for touch.

We use media queries to change the display as the screen size increases.

The default screen breakpoints we use are: 35.5em, 48em, 64em, 80em.

A great example of this is in responsive-base/css/modules/pull.css

.pull-left { float: left; }
.pull-right { float: right; }

/* same sizes as defined here: http://purecss.io/grids/#pure-responsive-grids */
@media screen and (min-width: 35.5em) {
    .pull-left-sm { float: left; }
    .pull-right-sm { float: right; }
}
@media screen and (min-width: 48em) {
    .pull-left-md { float: left; }
    .pull-right-md { float: right; }
}
@media screen and (min-width: 64em) {
    .pull-left-lg { float: left; }
    .pull-right-lg { float: right; }
}
@media screen and (min-width: 80em) {
    .pull-left-xl { float: left; }
    .pull-right-xl { float: right; }
}

The above is from that pull.css file, it sets up default classes in css we can use in our html templates to pull elements to the left or right but maybe only at specific screen breakpoints.

It's worth exploring the css/modules/ directory in responsive-base as there are plenty files.

Back to this design though, our end navigation style looks like:

@media screen and (min-width: 48em) {

    /* ----- nav ----- */
    #header .nav {
        left: 240px;
        bottom: 0px;
    }
    /* nav background to transparent*/
    #header .nav ul {
        background-color: transparent;
    }
    #header .nav ul ul {
        background-color: #FFF;
    }
    /* active link */
    #header .nav > ul > li:hover,
    #header .nav > ul > li.is-focused,
    #header .nav > ul > li.is-current {
        background-color: #F78F1E;
        border-radius: 10px;
    }
    #header .nav > ul > li:hover > a,
    #header .nav > ul > li.is-focused > a,
    #header .nav > ul > li.is-current > a {
        color: #FFF;
    }

}

Now the outer and header styling is pretty close.

There's still plenty for me to work on but I hope this helps you get started with your own designs.

Cleaning up our work

So far our CSS has all been added to our site.css.twig file, but we can actually separate it into multiple files.

e.g. we could take the outer "Main outer theme" part, the body and the .layout-container and put this into a css/outer-layout.css file, the same for the header styles into a css/header.css file.

Then back in the site.css.twig file you'll need to include the newly created files where the css used to be. We can do this with Twig so that we still end up with a single css file being sent to the browser e.g:

{{ source("css/outer-layout.css") }}
{{ source("css/header.css") }}

This part is up to you as it's your project. It's fine to leave all your style at first in the site.css.twig file, especially on a small project. But as this file grows you may want to look into doing this.

At this point we have a working responsive site, it's simple and though for my Impkids redesign I have much left to work on, this has just been a small dive into what's needed. The most important next step is to try out different designs, use your css skills and you have pretty much free reign over the style of the site.

Feel free to contact me about any questions you may have on this or on anything to help improve this post for future readers, thank you.

Next steps

Where can you go from here?

Read up on Responsive design (css, designing and workflow ideas)
Browser testing (e.g. using browserstack or emulators or real devices)
Version control, it's useful to have a history of your changes e.g. After downloading the files in step 6 you could use git to start a history of the files.

Contents

Prerequisites

Starting a new project

First time notes

Diving in

Next steps