Every now and then you can find yourself in situations, where you have to use other people's code or you need special versions of yours. Wouldn't it be great if you had ready-made tools to convert the existing code to what you actually need? In this post, you'll find three of them that help with different transformations. These types of tools are called code modifier tools.

It's important to understand that code modifiers are in fact specific code generators. They both provide the output based on the supplied input and the previously defined rules for the transformation. Opposed to code generation tools, however, in code modification tools the input has to be working pieces of codes (in our tools HTML), not only parameters, and the output is the same data with controlled alterations. Does it make sense?

I hope it does. If you think about it, inliners are good examples for code modifiers: HTML is provided with style tags, which is translated to markup with inline styles. We'll revisit them in detail in our next article, where we'll be talking about CSS architecture in email development.

In this tutorial, I'll show you 3 open-source projects that surfaced as development needs during our email editor's development previously. The projects are as follows:

  • TextVersionJS strips out HTML markup and provide customizable markdown format
  • Bulletprooflist converts ul, ol and li elements in HTML to legacy email client compatible code
  • BulletproofLineLenght wraps long lines to separate multiple lines

I'll show you thoroughly how to include them in any project. You may find them useful in your workflow as well. I even hope that they inspire you to write your own custom tools.

As we are developing a new generator engine at EDMdesigner, it is likely that we'll release new open-source projects in the future. You can visit us on Github from time to time to check up on these upcoming tools.

HTML To Text String with TextversionJS

First, we start with TextVersionJS that converts email HTML to markdown text. You would most often need that to reduce SPAM scores of an email campaign. By sending along the email's text version in your ESP, it's less likely that the message gets marked as SPAM.

Another use case is for testing email campaigns' value with the plain text version. In some email marketing communication plain text performs better in user engagement. If you work with very long HTMLs, it's much easier to extract the content with this tool than by hand.

Let's see, how we can use the tool and what configurations are available.

We used the Universal Module Definition pattern, which attempts to offer compatibility with the most popular script loaders of the day. With that, you can use the tool on the server-side and in the browser as well.

I'll show how to include TextVersionJS in the browser step-by-step firstly:

1, Create a basic template:

    <!DOCTYPE html>
    <html>
    {% include head %}
    <body>   
        {% include header %}

        <div class="page-content">
            <h1>TextversionJS</h1>
            <p>This tool is awesome</p>
            <h2>HTML to plain text converter online</h2>

            <h3>Paste your email HTML here</h3>
            <div>
                <textarea id="htmlTextarea"></textarea>
            </div>
            <button id="generateButton">Generate</button>

            <h3>The text version</h3>
            <div>
                <textarea id="textVersionTextarea"></textarea>
            </div>       
        </div>

        {% include footer %}
    </body>
    </html>

There are two textarea elements in the content. We define ids ("htmlTextarea" and "textVersionTextarea") for easy access to them from the JavaScript.

The parts, denoted as {% include footer %} are for showing, where you would likely add fancy custom elements. We'll only change some of them.

2, Include TextversionJS and make calls to the tool:

As the JavaScript file detects it's environment as I showed before, you can include it as you would any other JS file in the HTML:

       <script src="./textversion.js"></script>

To activate the freshly included JS functionality, we need to call its main method. That's htmlToPlainText according to the documentation, but it's set to be called as createTextVersion in the module definition.

We set up a button element, which will fetch the necessary DOM elements and call createTextVersion on them. The returned content will then bed pushed to the second textarea. You can see this below:

<script>  
    function generate() {
        var htmlTextarea = document.getElementById("htmlTextarea");
        var textVersionTextarea = document.getElementById("textVersionTextarea");
        textVersionTextarea.value = createTextVersion(htmlTextarea.value);
    }

    var generateButton = document.getElementById("generateButton");
    generateButton.onclick = generate;
</script>  

3, Add basic styling for design value

It has little value to the tool's functionality, but if you work with the browser probably can't leave out some finesse for the UI:

            <style>
                .page-content {
                    margin: 0 30%;
                }
                textarea {
                    width: 40vw;
                    height:20vh;
                }    
            </style>

It's time to see what we've achieved:

Convert HMTL markup to text animation](http://textversionjs.com/)

You can pass a configuration object for the tool with 7 configuration properties:

    var styleConfig = {
        linkProcess : null,
        imgProcess : null,
        headingStyle : "underline"; // hashify, breaklink
        listStyle : "indention"; // indention
        uIndentionChar : "-",
        listIndentionTabs : 3  
    }

To sum up, you can set the indentation, link and image output format and heading styles. The linkProcess and imgProcess properties are special because they'll apply any custom implementation you provide.

There are a few highlights about usability:

  • It has no dependency, so you can use it safely and consistently
  • On the client-side, if you use custom strings you need to replace them before you could send the email
  • While you can convert the final HTML to text-version on the server-side, no additional steps required

I encourage you to check out how it works and give it a try now on the project's demo page and check out the full source code of the tool.

Crop Lines with BulletproofLineLenght

The next tool takes good care of long lines as most email clients have troubles displaying them. Many characters in a single line can break the layout easily. To prevent this from happening, we can use the BulletproofLineLenght tool and set up the line lengths to an arbitrary value.

In this section, we are going to use the tool on the server-side in the example, but you can access it online too.

The project's working folder contains a test tool, where you can try out quickly how this code modification works. We are going to use that for the server-side example, with the only difference of including the project's working files via NPM. The steps are the following:

1, Open a project folder:

The necessary commands are:

        mkdir <your directory name>
        cd <your directory name>
        npm init
        npm install bulletprooflinelength --save

After npm init you are prompted several questions about the project, completing them you'll have the package.json file created. If you need a deeper understanding about getting started with NPM, you can check our previous tutorial on scripting or the NPM documentation.

2, Install BulletproofLineLength:

        npm install bulletprooflinelength --save

With this command, a node_modules directory gets added to your working files.

3, Using the tool in projects:

As mentioned before we already have an exemplary use of the tool among our working files, and the project's documentation shows clearly how we can include it in our JavaScript files. So the modified code is:

        // FROM THE DOCUMENTATION
        // Including from node_modules
        var bulletproofLineLength = 
        require("bulletproofLineLength");

        // FROM PROJECT'S TESTING TOOL
        // Requiring necessary Node packages
        var fs = require("fs");
        var path = require("path");

        var stringWithLongLines;
        var maximalLineLength = 50;

        // Parsing command line arguments
        var pathToFile = path.join(__dirname, process.argv[2]);
        var parsedPath = path.parse(pathToFile);

        stringWithLongLines = 
        fs.readFileSync(pathToFile, "utf8");

        var stringWithShortLines = 
        bulletproofLineLength(stringWithLongLines, maximalLineLength);

        // Writing line-split HTML to file
        fs.writeFileSync(path.join(__dirname, "./results/", parsedPath.name 
        + "-splitted" + parsedPath.ext), stringWithShortLines);

and that's it. We have BulletproofLineLength set up in our project, able to read HTML files and output line-split version of it into a separate file. It could be an end-task of an automated workflow.

It's time to spare some word about how the tool works and what restrictions or opportunities it has:

  • the tool accepts any input format, but only HTML and CSS lines are processed, otherwise, the original line is returned
  • the splitting of lines are set up based on typical separator characters of the language: <, >, ", ' in HTML and ;, ,, } in CSS. That means that long inline style declarations are not split in the HTML.

I encourage you to check out how it works and give it a try now on the project's demo page and check out the full source code of the tool.

Lists in Emails with Bulletprooflist

This third project was introduced years ago in our email HTML generator. A recent update in it made us realize that it can be helpful for fellow email coders. The tool is responsible for making unordered and ordered lists bulletproof.

In this section, our main focus will be on the generated output, namely what makes a list bulletproof in email clients.

There's a necessary addition in order to make the tool work in the browser: we need to bundle our server-side dependency, the Cheerio package with Browserify or a similar bundler. Bundlers let us implement external modules easily. with this out of the way, let's jump in the middle:

After copy & paste and generate we have a bulletproof list available for comparison with the original one:

Before
          <html>
            <head></head>
              <body>
              <ul>
                  <li style="font-size: 16px;">First Item</li>
                  <li style="font-size: 16px;">Second Item</li>
                  <li style="font-size: 16px;">Third Item</li>
              </ul>
              </body>
          </html>
After
          <html><head></head>
          <body>
          <table cellpadding="0" cellspacing="0" border="0">
              <tr><td align="left" width="15" valign="top" 
                    style="font-size: 16px;">•</td>
                  <td align="left" 
                    style="font-size: 16px;">First Item</td>
              </tr>
              <tr><td align="left" width="15" valign="top" 
                    style="font-size: 16px;">•</td>
                  <td align="left" 
                    style="font-size: 16px;">Second Item</td>
              </tr>
              <tr><td align="left" width="15" valign="top" 
                    style="font-size: 16px;">•</td>
                  <td align="left" 
                    style="font-size: 16px;">Third Item</td>
              </tr>
          </table>

          </body></html>

You see in the above tables that the ul tags are converted to tables (just as ols would) and each lis are replaced with a tr element with 2 cells. The first td holds the bullet point and handles the spacing with the width value. The second cell contains the text content of the list item. They each inherit an align="left" and a font-size property.

Now the most important step is to check the results of visual tests.

First, let's check what happens when we apply no style on our lists but have margin and padding reset as part of the necessary reset step of email development workflows. We can see that bullet points are not aligned correctly to their containers in regular lists, but they work correctly when used with the bulletproof method with tables:

Before After
Original email preview of HTML list Email preview of HTML list with Bulletproof code

I only included Apple Mail's preview as it is the most modern client, but the same behavior was true for every other email client.

We continue by adding the following snippet to the code, which will make regular lists to align correctly:

            tr,
            td,  
            ul,  
            ol,
            li {
                margin: 10px;
                padding: 10px;
            }

We can open up the previews of the original and the bulletproof HTML to examine the difference.

As you can see in the images below, list items aren't aligned correctly (bullet points are not in line with the ordered list's numbers) in some of the clients, but are fixed with the bulletproof code:

Original
Outlook 2003 original email preview
Bulletproof
Outlook 2003 bulletproof email preview
Original
Yahoo! Mail original email preview
Bulletproof
Yahoo! Mail bulletproof email preview

Last, but not least some additions to think of when you use the tool:

  • it increases the email size, which may increase the spam score, especially with long lists
  • you have little options for customization. You would need to modify the tool's code to receive different output

I encourage you to check out how it works and give it a try now on the project's demo page and check out the full source code of the tool

Summary

By finishing this tutorial post you have learned all about our ready to use code modification tools.

We saw what TextVersionJS, Bulletprooflist, BulletproofLineLenght are good for but the name quite said it all.

The key takeaways:

You can use tools for single-purpose use cases.

Ours are available if you want to:

  • bookmark them: 1 , 2 , 3
  • download or clone them from Github: 1 , 2 , 3
  • install via NPM: 1 , 2 , 3

Let your projects benefit from open source tools.

We also mentioned that with the whole new email generator engine we're building at EDMdesigner, we are likely to release similar open-source tools. Hope that the email developer community will find these tools useful.

If you enjoyed this tutorial post and you do not want to miss the next one, please subscribe to our newsletter.

Author
Mihály Sáróy

Mihály Sáróy

Developer @ EDMdesigner.com

  • Beginner's Guide to Using Sass in Email Coding Beginner's Guide to Using Sass in Email Coding

    Do you repeat bits of CSS code across email template projects? Learn to use the Sass preprocessor language to change that and design reusable components.

    Read more
  • Managing Full-time Employees at a Growing SaaS Company Managing Full-time Employees at a Growing SaaS Company

    In this article you can read about how an early-stage startup can overcome management difficulties with the SCRUM methodology and the pomodoro technique.

    Read more
  • Code Generator Tools Used in HTML Email Development Code Generator Tools Used in HTML Email Development

    Do you write every line of HTML manually when coding emails? Stop! It's time to find out more about code generator tools used in email development.

    Read more