Menu icon Foundation
Newbie Issues with Foundation for Emails (Sass)

Hi All,

I'm just trying to evaluate the Zurb Foundation for Email, using the Gulp/Sass Stack.

My first port of call was to try to get some of the sample templates working however, it's not clear from the docs exactly what the general workflow ought to be for a pure beginner.

You would think this would be a no-brainer to take the sample templates, run them through the SASS build system and reproduce the results shown in Zurb's litmus tests, but no, it's proving to be a bit of a nightmare! Some basic walkthroughs included in the docs to clarify the general steps would be helpful for anyone else starting out trying to get familiar with the system.

I really want the Zurb for Emails system to work as I think it has great potential, so if anyone could chip in with some help or general guidelines I would be most grateful.

In particular, I've found the following pretty confusing:-

 

  • To run the in-liner, is there any difference between 'Foundation Build' and 'npm run build'?

  • A brief outline of what the build process actually does would be great. For example, my output file still has the css link tag at the top pointing to 'css/app.css'. Is that supposed to be there even after inlining? Because of this, I'm not sure my inlining process is running properly? Maybe it's no harm to retain it there for compatibility across email clients?

  • As far as I can tell, the inlining process only actually in-lines the css present in the 'css/app.css' file into the style attributes of the various tags in the document.

    Where the page being inlined actually has it's own internal style block <style>...</style> (as in the sidebar-hero sample template) this block is actually only copied into the body of the document
    e.g.
    <table class='body'><tr><td><center><style> ...style block copied here... </style></td></tr></table>

    So, they don't actually get 'in-lined' into the various 'style' attributes on the various tags the same way that the 'css/app.css' styles do.

    Is this supposed to happen like this or is there something going wrong with my in-lining process?

  • Because of the way that the page-level inlining works (as described immediately above) I'm finding that the Zurb sample templates don't actually render in Outlook (2016) the way that the Zurb site portrays them in the Litmus tests, so obviously I'm going wrong somewhere, but can't see where.
    (I've documented this issue here if anyone can help.)

  • After building my page using the Gulp/Sass stack (including inlining with npm run build) are we actually supposed to take the output file and the css provided in the 'dist' folder and run it through Zurb's web-based inliner? I doubt I'm supposed to do this, but the funny thing is, the page actually renders somewhat better in Outlook 2016 after doing this, presumably because the page-level css in the style block is finally properly in-lined within the various style attributes rather than being retained as a style block (which probably gets filtered out by Outlook).

  • Perhaps my issue is with how/what I'm actually sending... Let's say I create a page in the 'pages' folder called 'Demo1.html' and build it with npm run build. The output file is in the 'dest' folder also called 'Demo1.html'. Is this output file self-contained and ready to send out as a HTML email or does it also require the 'css/app.css' file to be included with it? If so, how do you package these two files together for sending as an HTML email? At the moment, I'm using an npm utility called 'send-html-email' which only sends a single html file at a time. So, what to do with the CSS file there? I've also tried using GroupMail which supports sending html emails, but again not sure what to do with the CSS file there either as it just expects you to send a single file. Should it be included as an attachment in some way? Or should the CSS file be put up in a public website and linked to from there? I'd have thought those would get blocked by email clients? Any guidelines here would be appreciated.

  • A little more information on the purpose of the various folders in the SASS build system would be useful. I understand the obvious ones like the 'Layouts' and 'Pages' and 'Dist' however, it's not clear what the 'Partials' folder is for and what the build system does with that! Presumably page fragments go in there but how do they get included? Some examples would help perhaps.

I'm running out of time to evaluate this product, so if anyone could give some info on any of the above sticking points or point me in the direction of the appropriate docs, in case I've missed something, that would be great!

SassbuildinliningOutlooksample templatestutorialsNewbie

Hi All,

I'm just trying to evaluate the Zurb Foundation for Email, using the Gulp/Sass Stack.

My first port of call was to try to get some of the sample templates working however, it's not clear from the docs exactly what the general workflow ought to be for a pure beginner.

You would think this would be a no-brainer to take the sample templates, run them through the SASS build system and reproduce the results shown in Zurb's litmus tests, but no, it's proving to be a bit of a nightmare! Some basic walkthroughs included in the docs to clarify the general steps would be helpful for anyone else starting out trying to get familiar with the system.

I really want the Zurb for Emails system to work as I think it has great potential, so if anyone could chip in with some help or general guidelines I would be most grateful.

In particular, I've found the following pretty confusing:-

 

  • To run the in-liner, is there any difference between 'Foundation Build' and 'npm run build'?

  • A brief outline of what the build process actually does would be great. For example, my output file still has the css link tag at the top pointing to 'css/app.css'. Is that supposed to be there even after inlining? Because of this, I'm not sure my inlining process is running properly? Maybe it's no harm to retain it there for compatibility across email clients?

  • As far as I can tell, the inlining process only actually in-lines the css present in the 'css/app.css' file into the style attributes of the various tags in the document.

    Where the page being inlined actually has it's own internal style block <style>...</style> (as in the sidebar-hero sample template) this block is actually only copied into the body of the document
    e.g.
    <table class='body'><tr><td><center><style> ...style block copied here... </style></td></tr></table>

    So, they don't actually get 'in-lined' into the various 'style' attributes on the various tags the same way that the 'css/app.css' styles do.

    Is this supposed to happen like this or is there something going wrong with my in-lining process?

  • Because of the way that the page-level inlining works (as described immediately above) I'm finding that the Zurb sample templates don't actually render in Outlook (2016) the way that the Zurb site portrays them in the Litmus tests, so obviously I'm going wrong somewhere, but can't see where.
    (I've documented this issue here if anyone can help.)

  • After building my page using the Gulp/Sass stack (including inlining with npm run build) are we actually supposed to take the output file and the css provided in the 'dist' folder and run it through Zurb's web-based inliner? I doubt I'm supposed to do this, but the funny thing is, the page actually renders somewhat better in Outlook 2016 after doing this, presumably because the page-level css in the style block is finally properly in-lined within the various style attributes rather than being retained as a style block (which probably gets filtered out by Outlook).

  • Perhaps my issue is with how/what I'm actually sending... Let's say I create a page in the 'pages' folder called 'Demo1.html' and build it with npm run build. The output file is in the 'dest' folder also called 'Demo1.html'. Is this output file self-contained and ready to send out as a HTML email or does it also require the 'css/app.css' file to be included with it? If so, how do you package these two files together for sending as an HTML email? At the moment, I'm using an npm utility called 'send-html-email' which only sends a single html file at a time. So, what to do with the CSS file there? I've also tried using GroupMail which supports sending html emails, but again not sure what to do with the CSS file there either as it just expects you to send a single file. Should it be included as an attachment in some way? Or should the CSS file be put up in a public website and linked to from there? I'd have thought those would get blocked by email clients? Any guidelines here would be appreciated.

  • A little more information on the purpose of the various folders in the SASS build system would be useful. I understand the obvious ones like the 'Layouts' and 'Pages' and 'Dist' however, it's not clear what the 'Partials' folder is for and what the build system does with that! Presumably page fragments go in there but how do they get included? Some examples would help perhaps.

I'm running out of time to evaluate this product, so if anyone could give some info on any of the above sticking points or point me in the direction of the appropriate docs, in case I've missed something, that would be great!

Corey Schaaf about 3 years ago

Overview assumes you're running windows
If you're using the sass version with the Inky markup, the installation is really straight forward here. 

http://foundation.zurb.com/emails/docs/sass-guide.html

The steps below are for installing the Foundation CLI which is what will enable you to install foundation for Emails, Foundation for Sites or Foundation for Aps. 

Keep in mind you have to have node.js as well as git installed before performing the steps outlined in the link above. (When installing git also make sure to select windows style command line) . Once everything is installed proceed to the steps below. 

Use command line to start the installation. If you're on a windows machine, make sure you're running command line as an administrator. 

Run this command (note this will take several minutes)

npm install --global foundation-cli

Once that's installed, navigate to the folder via command line where all your projects will be stored. I keep my projects on my C: drive under a folder called emails. In this example, I would use command line to navigate to the root of the folder [cd c://emails/]  Once there, run this command (this command actually installs everything you need to use the foundation for emails framework including emails, test server etc ... 

foundation new --framework emails

You will be asked to name this project. Choose a name without any spaces and hit enter. This creates a new folder with whatever name you specified inside the emails folder (based on my example the folder emails would be created). 

This process will also take several minutes to run as it is installing a 220meg file structure needed to use the Foundation For Emails workflow. 

When this process is complete use command line to navigate inside the project folder you just created. Once there, run this command: 

foundation build

Foundation build is the process by which everything in the project is inlined and flat file is created. This command will take a few moments to run but should launch a test file server using Browser Sync (which is part of the Zurb Stack) in whatever your default web browser is . This process also starts your local server which is how you can view your pages as you create them. 

Understanding the file structure created
Assuming you haven't run into any problems yet if you open up windows explorer or sublime text editor, you can navigate to the location of your project and you'll see a folder structure like so. 

Dist <-- posting inlined files from the (pages folder show up here)
etc
node_modules <-- if you're new - stay out of here
src <-- this is where you'll do most of your work

Inside the src folder you'll notice subfolders like so:
assets <-- includes img folder and scss folder. The scss folder is where you'll create custom scss for your emails.
helpers <-- stay out of here if you're new
layouts <-- where multiple layouts can be stored. Files inside your pages directory can use these layouts.
pages <-- where all of your working html using the inky framework are stored.
partials <-- chunks of HTML you want to re-use can live here

These subfolders are where you'll spend the majority of your time working. Now, that browser that launched with a test page, the working contents of that file will be found in pages/index.html

If you make any changes to that index.html page, the command that we ran earlier (foundation build) will re-inline all the files again.  If you have windows file explorer opened you'll notice that the dist folder disappears and re-appears as all the content are deleted and then re-inlined inside the dist folder. 

What's important to differentiate here is that the changes you're making inside the pages directory is not the file the test page is pulling from.  It's looking at the index.html file that is generated inside the dist folder. 

Say you were ready to copy the contents of your html to whatever Email service provider (ESP) you're using. You would copy the html that is generated in the dist folder.  

Now, hit Ctrl + C.  in the Command line. This will stop the build command and also stop your local server from running. If you hit refresh on the page that was generated you will get an error. That's okay. 

Inside command line, use this command:

foundation watch

Foundation watch does pretty much everything foundation build does. However it DOES NOT inline all the styles and doesn't compress images in the img folder.  Foundation build can be an extremely process heavy on system resources. So if you're just in the process of setting up html and not ready to inline this is the command I like to use.

Navigate to the dist folder via file explorer or sublime text and open that index.html file. Notice the file looks very different from an inlined version of the file.  Paths are relative to your project which is okay while you're in this mode. However if you were to try and copy in the index.html file from the dist folder now, you will notice that your page will not render properly if you copy it into an ESP and do a test. So - use foundation build when you're ready to copy your html to your ESP. 

Understand folder structure inside SRC
The Partials folder is where you can keep "pieces" of an email. Like a static header and footer that will never change. You can save those pieces inside the partials folder. Do that now and give it a name of footer.html. 

The way you reference those pieces of html is to navigate to the index.html file inside the pages folder and use what we call Panini. 

Inside your index.html let's make a reference to the footer.html partial. (if you haven't created a footer.html file inside the partials folder go ahead and do so, this way we can reference it). 

The way we reference partials is by adding a line of code to the index.html file that looks like this. 

{{> footer }}

(notice I didn't add .html to the end of that file. It's not necessary. Assuming you're foundation watch command is still running you should see the contents if your're footer displayed. 

Now the really cool feature about this is that if you wanted to make the footer or header part of the layout you could put the reference in the layout file (which makes more sense for headers or footers). This is just to show you that you can reference anything in the partials folder from pages or inside the layout file which is where we will go to next. 

Layout File
Lets checkout the layout file. Open it up and look at the contents of it. You'll notice that this is a standard html build that includes some references using panini. (the markup I just showed you with the footer) Only this example is calling something named body.  

Body would be the index.html file we were just in.  Now, for the sake of this example. Let's delete the footer reference that was in the src/pages/index.html file and instead move it to the layout.html file. 

{{> body}}
{{> footer }}

Once you save this - run the foundation build command.  I believe any changes you make to layout are not recognized by foundation watch. Only changes made in the pages directory.  

Assuming we've done everything correctly the footer should once again render.  

You can create multiple layouts as well as multiple files under the pages folder. If you wanted to create a second email just name it whatever you want and save it inside the pages folder. The only difference is that once the foundation watch or build command is run, you have to change the url path in the browser. So if I created a second file named my-next-email.html. In browser you would navigate to: 

localhost:3000/my-next-email.html

If you wanted to create a new layout file that doesn't use this footer you can do that as well. Just save the current layout as new-layout.html and remove the panini reference to the footer so only body is used. 

Using Front Matter
Now you may be asking yourself how to I make my files in the pages folder use the other layout I just made. The answer is Front Matter. 

Navigate back to the index.html. At the top of the file we want to use the following syntax: 

---
layout: new-layout
---

This piece of code says instead of using the default.html file inside of layout, use the file called new-layout.html. Again notice I didn't add the .html to the end of the file. It's not necessary. 

You can also add your own custom data here as well. Lets say I wanted to create a variable called subject-subhead. You would write that like so: 

 

---
layout: new-layout
subject-subhead: This is my subject subhead
---

Inside your index.html file you could reference this piece of code by doing the following: 

---
layout: new-layout
subject-subhead: This is my subject subhead
---

<row>
  <columns>
    {{ subject-subhead }}
    <!-- when this code above is generated it will pull in your variable above-->
  </columns>
</row>

 This was a rather lengthy post so hopefully others will contribute some of their processes to. By know means is this all encompassing. I highly recommend you take the Foundation for Emails course offered by Zurb. Seeing real world examples and how people use the framework was especially beneficial for me. 

Chris about 3 years ago

@Corey Nice answer!

One question: you wrote "So - use foundation build when you're ready to copy your html to your ESP." After this step I still have a reference to css/app.css in dist/index.html – like the OP I wonder if that's supposed to be that way or if that's simply a bug?

Corey Schaaf about 3 years ago

Does the inlined version look something like this? 

<html xmlns="http://www.w3.org/1999/xhtml"><head><link rel="stylesheet" type="text/css" href="../..\..//css/app.css">

Chris about 3 years ago

Yes, by reference I meant that <link ...> tag

Corey Schaaf about 3 years ago

We've been sending emails out with that included and haven't had any issues. Everything should be inlined anyways. All foundation classes should be nested inside the style tag as well as any media queries you setup.  As long as those are there in addition to the styles="" pretty much appearing everywhere in your file - I would say everything you've done (for the purposes of inlining should be correct). 

Derek McDermott about 3 years ago

Sorry guys, I've been trying to respond but the Zurb spam-bot is preventing me from replying! So, I'm going to break up my reply into chunks just to try to get past it - sorry if it's awkward to follow!

Derek McDermott about 3 years ago

Hi Corey,

Thank you very much for that comprehensive walkthrough, that was a lot of work to trouble you with, but I'm sure it will be of great benefit to anyone else starting out with foundation, particularly your section on the Partials and the Front-Matter, which aren't really covered in the Zurb docs very well, so that's a great help.

I can see that the framework is potentially going to be very useful, provided that I can reproduce the same results across all the email clients that the Zurb appear to support, based on their litmus tests here.

What I still can't get past though, and this is the deal-breaker for me using their framework is that I just can't reproduce their litmus test results (see here) using Zurb's own template samples e.g. sidebar-hero.html.

Derek McDermott about 3 years ago

I have the Foundation for Emails framework v2.2.1 installed (on a Mac) and have everything working that you outlined above, yet without changing any of the sample code, when I paste in the sidebar-hero.html template downloaded from Zurb into my pages folder and run Foundation Build and email myself the "dist/sidebar-hero.html" file, it renders broken in Outlook 2016 (Windows 10 Desktop) as shown here: -

Outlook 2016 Screenshot

 

Derek McDermott about 3 years ago

It isn't too bad, but the point is that it's different, which makes me wonder about the framework generally. In this case, the grey header/wrapper doesn't appear to work, the links are rendered horizontal (probably a parent width problem) so pushing the right hand column width out too far and the social icon colours are all wrong. I can probably hack the layout, but that's not the issue.

So, unless Zurb are using a different layout page or additional CSS I can't understand why I should get such a different result. I've only just downloaded recently the Zurb Foundation for Emails so I'm using the latest sources. The only other thing I can think of is that the Zurb Litmus test is actually old and that Outlook 2016 updates have broken things since - I wonder if Zurb ran the test again would they get the same results? Are their litmus tests run on demand each time or are they just cached images?

Alternatively, it would be nice if Zurb would publish their actual sources used in the Litmus tests so that we can verify everything is working correctly.

Has anyone else come across this issue I wonder? It's pretty easy to test out!

Derek McDermott about 3 years ago

(That was weird - why it wouldn't let me post that reply in one chunk I don't know!)

Derek McDermott about 3 years ago

@Chris, I'd concur with Corey that it probably isn't any harm leaving that css link in the header place - it might even help compatibility across email clients for those that support it. It is a little confusing for anyone starting out though.

However, if you're intent on removing it, I came across this post which explains how to get the sass/gulp build process to remove it for you:-

http://foundation.zurb.com/forum/posts/42859-email-remains-linked-to-appcss-stylesheet

(You could also just set those attributes to true rather than removing them, if you want to more easily change them back later.)

Just do this at your own risk!

Rafi Benkual about 3 years ago

 Derek - thanks for the heads up! I'll take a look at that template today - probably some small change that needs to be updated.

pzo over 1 year ago

Great post this. However I have another question about the "layout-file" section of Corey's reply.

He says this:

"Once you save this - run the foundation build command.  I believe any changes you make to layout are not recognized by foundation watch. Only changes made in the pages directory.  "

After checking the gulp file I really wonder why that is since there is a watch on those files. A rebuild is actually triggered and the browser refreshes... but then i notice all the old values are still being used. Only way to fix this is with another manual build as described.

This really has me confused. Any help anyone?

I fixed it for myself with the following addition. But i do not know if this is the way to go for other people. Wonder why it wasn't that way from the beginning to be honest.

Changed the watch to:

gulp.watch(['../scss/**/*.scss', 'src/assets/scss/**/*.scss']).on('all', gulp.series(resetPages, resetCss, sass, pages, inline, browser.reload));

And added the following function:

function resetCss(done) {
    rimraf('dist/css', done);
}