System Overview

The HTML Newsletters system has been designed to enable InterWoven based websites to easily create HTML versions of their newsletters which are consistent with their site templates, and do not require any HTML design. Rather, any InterWoven user should be able to manage and deploy their HTML newsletters as easily as they do regular site content. Also, there should be no need to create two copies of the newsletter to facilitate those uses who either only have HTML email clients, or those who only have text email clients. The system automatically creates both versions and sends them out from one set of content. The system has also been designed to be extremely customizable, allowing for as simple a newsletter as just a pretty frame surrounding the text content, or as complicated as an InterWoven index page and article page combined.

DCR Design

The Basics:
The basic design of this system has been constructed around the idea of an article DCR which has been extended by index DCR functionality. The first few fields on the DCR contain the main content of the newsletter. The TITLE field will typically be the title of the article, but may also be used for the title of the HTML version of the newsletter. The feature image, author, and date should also be in reference to the main article text. You will notice that there are two text fields in this section. One is HTML enabled, the other is just simple text. This is the only location on the template where you will need to have duplicate copies of content. The HTML version will be used in the HTML newsletter, and the text version will be used in the text email. You should be able to cut and paste your formatted content out of the HTML box and into the TEXT box without too much trouble.

You will also notice that there is an ITEM_ID field in the upper right corner. We will discuss the function of this field later, but for now you just need to know that this field corresponds to all this basic content which we have just covered. If this is all the content that your newsletter contains, this field should be filled with the value: 01

Custom Sections:
More complex versions of newsletters may contain other types of content than just simple text. This is where the custom sections come in. Similar to the SECTIONs found on index DCRs, these CUSTOM fields are meant to be used to organize other content into custom categories. For example, if in addition to the main article text, you wish to have a list of feature articles in your HTML newsletter, you would place them all under a custom section, possibly called "Feature Articles". Each CUSTOM section can contain multiple ITEMS which, in the case of the above example, you would use to list the feature articles you wish to include.

Each custom section should have a TITLE, FEATURE_IMAGE, TEXT, SECTION_ID, and ITEM_ID. Though TITLE, FEATURE_IMAGE and TEXT may or may not be used depending on how your particular newsletter is constructed, each CUSTOM section should always have a SECTION_ID, and an ITEM_ID. Though we'll talk about the ITEM_ID later, the SECTION_ID is used to tell the scripts on the HTML template, where to find the data they're looking for. This SECTION_ID should always remain the same on every edition of this newsletter that you create. If you have been set up with a sample DCR for your newsletter, you should make sure that the SECTION_IDs you use are always the same as those used in the sample. There is one exception! If your site runs multiple newsletters, you may have different SECTION_IDs on one newsletter than you do on another. Please do not mix them up. If you do, parts of the newsletter you are creating will not work properly

Items:
Under each CUSTOM section you can create multiple ITEMS. As with most of the fields we're talking about, depending on your template design, some of these fields will be used, and some will not. It is your responsibility to know how the fields correspond to what's actually displayed on the template. If you take our example from the previous section where we were discussing the CUSTOM fields, you should realize that each ITEM under the example "Feature Articles" section will correspond to a feature article which will appear in the newsletter.

Different newsletters will be designed in different ways depending on what your team and website needs, and as such, some fields might not be used. If we continue with our example of the "Feature Articles", the ITEM_TITLE field would then correspond to the title of the feature article as displayed in the newsletter. The ITEM_TEXT field might then be a small teaser which you wish to have displayed under each title. And the LINK_URL might be the link to which the user is taken when they click on the title. The LINK_TEXT field might be used in the event that you have requested that there be text at the end of the teaser which is linked, rather than the title.

You will also notice that each ITEM has a "this is an ad" check box. If this is checked, it will impact the display of this ITEM in the text version of the newsletter. As you may know from other text newsletters you've received, advertising is often denoted by long lines of dashes or some other type of text formatting "boxes" around them in order that the reader knows they are looking at advertising and not the regular content of the newsletter. You may also wish to use this functionality.

ITEM IDs:
The purpose of the ITEM_ID field is to indicate how the content should be arranged in the text version of the newsletter. Because this text version is being created automatically, and obviously is limited in its design by the limitations of text, it was necessary to allow the newsletter designer a means by which to organize the order in which the text appears in that version of the newsletter. This is what the ITEM_ID field is used for. Beginning with 01, the ITEM_ID's should become progressively greater in the order in which the designer wishes each bit of content to appear. In other words, whatever you label as ITEM_ID: 01 will appear first, ITEM_ID: 02 will be second, and so on.

In some cases (as in the CUSTOM sections) you may not wish the title and text of an item to appear. In this case, the ITEM_ID SHOULD NOT BE LEFT BLANK but rather should have some sort of text in it. For example, it could contain the text "do not display".

CRITICAL:
IF YOU LEAVE ANY OF THE ITEM_ID'S BLANK, THE ENTIRE NEWSLETTER WILL NOT WORK. YOU MUST LABEL ALL OF THEM EITHER WITH A NUMBER OR WITH TEXT INDICATING NOT TO DISPLAY THAT ITEM.

Links and Images

It is important to remember when designing one of these newsletters that when the person receives this newsletter, it will be in their email; they will not be on our site. As such, you must make sure that all images and links use fully qualified URLs. What this means is that it must contain the entire url, including the HTTP://www.blah. If you do not do this, images will not display, and links will not work.

Image Specifics:
For the purpose of stats tracking, all images should be stored on the same domain as the newsletter is being developed. Typically, this will be something like nltr.sitedomain.com. The NLTR indicates that this is the newsletter system. You should NOT link to images located on the WWW site at any time as this will create chaos and pandemonium in the stats tracking. Also, please remember to reference ANY images to the fully qualified domain name.

/images/mypicture.jpg will not work!
http://nltr.mysite.com/images/mypicture.jpg will work fine.

Link Specifics:
As mentioned above, all links should also be fully qualified domain names, but instead of going to the NLTR site, they should go to the regular WWW site.

A link to:
/articles/myarticle.html will not work!
http://www.mysite.com/articles/myarticle.html will work fine.

Sending to Lyris

Once you have completed building the newsletter, you will want to preview it on the live NLTR site because the content there is the same as what the end user will be seeing. So, once you've made all your changes, you may deploy to the live site.

There is no index on the live site of all your previous newsletters. It should display them in the same folder as you developed them on the InterWoven site. So, if you developed your newsletter in /templatedata/content/newsletters/data/mynewsletter/newsletter_name it will appear on the NLTR site as http://nltr.mysite.com/mynewsletter/newsletter_name.html. It will also be password protected, and these passwords will be set up by a TruthMedia admin. Please talk to us if you wish to add or change usernames and passwords.

At the end of the HTML version of the newsletter on the live site, you will find two small forms. One will allow you to send a test version of the newsletter to yourself after filling in the field with your email address. The other will send the newsletter straight to the Lyris system where it should then get final approval and be sent out. Please be aware that clicking the "Send to Lyris" button does not send it out to the entire list. It simply combines the text and HTML versions of the newsletter and sends them to the Lyris que to be approved before the final send.

Archiving for Linking

At some point, you may want to develop a list of old newsletters which people on your site can browse through. Obviously, you will not want to link directly to the ones with the Lyris controls due to the fact that they are password protected, and they would allow any of your website visitors to send the newsletters to Lyris. This is where archiving comes into play. After you create a newsletter and send it to Lyris, you will want to create an archived version of it. This would be something like a snapshot of what it looked like when you sent it out originally. This snapshot should not change when you make updates / changes to the template, because then it would change what the original looked like.

Archiving of the newsletter is done within the InterWoven environment. To do this, load up the DCR, and click the Generate button which is right next to the Preview button. A window should pop up which asks you where you want to save the generated file. The standard way in which to save it is in in the archive folder off the root of your site, in another folder named the same as the name of your newsletter. You will also need to add a .html extension. So, it would save something like this /your workarea/archive/newslettername/filename.html.

Anything in this folder can be linked to from the live website. In order to do so you would link to www.yoursitename.com/nltr/archive/newslettername/filename.html

We recommend that at least for these archives (if not for every newsletter you do) you use the following naming structure year_month_day in numeric form. For example you might name your May 31'st newsletter to be 2004_05_31. This will greatly aid in file organization later on when you have multiple years worth of newsletters, and want to find one for one particular year, month and day.

Frequently Asked Questions

Why does the screen just stay blank or the newsletter won't load when I click preview?
You probably didn't include an ITEM_ID for everything in the newsletter.

How come pictures don't work when I sent a test email?
You need to make sure all pictures are deployed to the live server, and all references to those pictures are fully qualified URLs.

How come my links don't work when I look at the site in my email?
You need to make sure all your links are fully qualified URLs going to the WWW site.

How come my archived newsletter doesn't appear on the NLTR site?
You need to deploy it after creating it in IW.