192 Lotus blogs updated hourly. Who will post next? Home | Blogs | Search | About 
 
Latest 7 Posts
XPages webmail – Using Mime Inspector to debug Mime
Tue, Feb 14th 2017 66
Pasting Images into XPages CKEditor
Sun, Feb 12th 2017 46
Preventing pasting of remotely hosted images in CKEditor
Mon, Nov 14th 2016 4
Preventing Pasting of Images in CKEditor
Mon, Nov 14th 2016 5
Controlling the order of Script Resources (e.g. Jquery) with a Custom ViewRootRenderer
Mon, Sep 19th 2016 3
Review: JRebel with Domino OSGi development
Mon, Sep 5th 2016 7
Extended Messages Control available as an XspLibrary
Tue, Jul 12th 2016 5
Top 10
XPages webmail – Using Mime Inspector to debug Mime
Tue, Feb 14th 2017 66
Pasting Images into XPages CKEditor
Sun, Feb 12th 2017 46
Build System for XPages and OSGi plugins
Fri, Aug 8th 2014 9
Uploading Plugins Headlessly to Open Eclipse Update Site
Sat, Jul 18th 2015 7
Uploading Plugins Headlessly to Open Eclipse Update Site
Sat, Jul 18th 2015 7
Review: JRebel with Domino OSGi development
Mon, Sep 5th 2016 7
Select themeIds from plugins in Designer Xsp Properties Editor
Mon, Sep 8th 2014 5
Build Automation for XPages Presentation Slides - AUSLUG/Inform 2015
Thu, Jun 11th 2015 5
Welcome to my blog
Tue, Mar 11th 2014 5
Associating *.theme and *.xsp-config with Eclipse XML Editor
Wed, Mar 9th 2016 5


Webmail UI – You must learn about MIME
Twitter Google+ Facebook LinkedIn Addthis Email Gmail Flipboard Reddit Tumblr WhatsApp StumbleUpon Yammer Evernote Delicious
camerongregor    

If you were like me, you spent many years developing classic Notes applications before making the switch to XPages. If this was the case, you were no doubt comfortable with the notion of a RichText field.
You probably even occasionally did some RichText manipulation in LotusScript, adding Paragraphs and formatting using RichTextStyles and RichTextNavigators, attaching Files using EmbeddedObjects.

And then XPages comes along, and says “If you want to edit any RichText through XPages, it is going to be saved as MIME”.  And I’m like “Ok whatever you say, although, I don’t know what your’e talking about and I’m too busy trying to learn all these other new things to also learn about MIME”

And then later on, you come along and write an agent or a function that is meant to deal with a RichText Item and you don’t know why it doesn’t work and why everything looks funny after you do it, and it all comes down to the difference between RichText and MIME but you didn’t even realise there was a difference.

If you can understand some core principles of this Mime / Rich Text ecosystem, then you will be on a much better footing to solve the problems which inevitably appear whenever you are getting involved with Mime / Rich Text creating and manipulation.

Confusing Terms

I think one origin of confusion is that the phrase ‘Rich Text’ is often used to describe more than one thing.

To demonstrate what I mean, let’s think about ‘Audio files’. Imagine you are a programmer and your problem is that you need to record and playback some sound. Well what file format do you use? Maybe you decide to come up with your own format like Microsoft did e.g. Windows Media Audio (.wma) or alternatively, maybe you decide to use a format that everybody else uses e.g. MPEG layer-3 (.mp3).

The end result for both these ‘Audio Files’ is that you hear sound coming out your speaker just the same, but they are store in different underlying formats. Additionally, if I talk to you about the above situation and I say the word ‘Audio File‘, you know that I am talking about the CONCEPT of an audio file, not any specific format.

  • Audio Files
    • mp3
    • wma

In comparison, IBM came up with there own way to save ‘Pretty words, pictures and files’, and the rest of the world came up with another way ‘MIME’, but in Notes/Domino we tend use the word RichText to describe both the CONCEPT of ‘Pretty words, pictures and files’ and also we use RichText to describe the specific format IBM created to store these items.

  • RichText (concept)
    • RichText
    • MIME

So you can see the confusion here, someone says “I am storing it as RichText” well what do you mean? are you talking about the format or the concept???
A less confusing way to think about it is maybe:

  • Pretty words, pictures and files
    • RichText format
    • MIME format

Learning about MIME

If you don’t know about MIME, this is one of the first things you should try to get an understanding of because you will need to know what’s going on. MIME stands for Multipart Internet Mail Extensions, 

When they first invented email, RFC822 was the standard which defined how a computer could send a text message to another. This was great, but then people wanted to send messages with using different character sets, they wanted to include images and attachments (Look how excited Steve Ballmer is about putting a picture of a Ferrari in a ‘Microsoft Write’ document). So MIME was invented, which was a new standard of transferring this more complicated information over the same RFC822 compliant system.

In a crude nutshell, a MIME message is just a big long text string/file, which is formatted in a precise way in accordance to the MIME standard.

The Wikipedia article on MIME is a good overview, but if you are ever in doubt about exactly how it works, read the RFC’s that are linked there as these are from the horse’s mouth and they form the actual standard that software would hopefully adhere to.

Inspecting some MIME

Let’s have a quick look at a MIME message. Many email clients / webmail clients will have some way for you to inspect the original ‘MIME’ version of your email. To demonstrate, I will send myself an Email in Gmail and have a look.

Here is a draft Email that I am sending myself, it has an embedded Image, and it also has an Attachment.

MimeDraftEmail

So now I send the email to myself, and when I open it in Gmail, I can choose option to ‘Show Original’.

MimeShowOriginal

This then opens up the Original MIME representation that was received for Gmail

MimeMessage

So you can see it is like a big long text file, but hidden in all that is my image, my attachment, my Html message (and also a plain text version so that anyone on an old school messaging client can also read it).

Let’s break down the Message:

SMTP headers

The Message Starts with some SMTP headers which help understand how the message came to be in our inbox! If you are sending receiving MIME in domino, this header information will not be stored in the Body ‘RichTextItem’ but is usually stored as separate items on the Document, e.g. the ‘Subject’ item, SendTo etc.

SMTPHeaders

Then we get to the actual message body, which is made up of a bunch of Mime Parts. Each mime Part has some headers of it’s own which describe some things about that mime part, it then has a blank line, and then it has the Content of the Mime Part. Let’s look at an easy to understand MIME part, the Html message:

MimeTextHtml

So the Mime Part starts with a ‘Content-Type’ Header which describes the purpose of this mime part, in our case it is saying ‘Please treat this as Html’, it also says that our charset is UTF-8. Then it has the blank line which indicates we are finished with headers, and now comes the content. The content then begins and you can see the Html content of our email message.

Note in our html content the <img> tag does not use a http URL, but instead uses ‘cid’. This is a mechanism that is used for inline images. The cid refers to a Content-ID of another Mime Part, let’s have a look at that part:
MimeImagePng

This mime part represents the little image of the G, it begins with the headers that say “Treat me like a PNG image, I like to be called ‘image.png’. I am meant to be shown ‘inline’ (e.g. embedded, not as a separate attachment), my content is encoded using base64. Some other mime parts refer to me as ‘ii_154338a9bb6d446c’.”
It then has the blank line, and then the content, which is just the image data in a base64 encoded string.

Multipart Content Types

So we have seen 2 simple MIME Parts, but for a complicated message it also needs to be specified how all our Mime parts fit together, and this is usually done by using the ‘multipart’ mime types. Multipart content types are special parts which contain child mime parts.
Multipart types must specify a ‘Boundary’. The boundary is just a text string that is used as a marker to signify when each Child MIME Part begins and ends. This boundary could be anything you like, however if you were to choose a boundary that might also appear in the content, there might be a clash, so the boundary is usually some type of garbled text that is unlikely to appear in a content block.

In our example message we have:

  • multipart/mixed – usually used to put an attachment, alongside a message body
  • multipart/related – usually used to put an inline image alongside a message body
  • multipart/alternative – usually used to say ‘hey you can used this or that’ e.g. html or plaintext

Let’s look at our multipart/alternative mime part

MimeAlternative

So we can see at the start, the multipart/alternative says “I will use 047d7b414d2a112e990530e95d88 as the boundary, and we can see it has used this boundary to define the start and end of the 2 child mime parts (text/plain and text/html) which are to be treated as ‘alternatives’ i.e. you could read one or the other. Note also, the very last boundary must have 2 hypens at the end.

Put it all together

So if we were to think of our entire message in terms of a tree like child/sibling structure, we could represent it as such:

  • multipart/mixed
    • multipart/related
      • multipart/alternative
        • text/html
        • text/plain
      • image/png  (encoding in base64 display inline)
    • text/plain (encoded in base64, treat as an attachment)
Learning how to Inspect/Manipulate MIME in Domino
In Domino, mime parts are  referred to as MIMEEntities, and the MIMEEntity is the class used to represent one of these parts. If this message (above) was stored in a Domino document as a RichTextItem using MIME format, you could access it using:
MIMEEntity me = document.getMIMEEntity();
But, what you would actually get is the just the first MimeEntity (in our case the multipart/mixed part). You would then have to traverse through child/sibling to do what you want to do. This topic warrants another post so I won’t go into depth right now.
IMPORTANT NOTE: If you wish to do some MIME processing on a document you must tell your NotesSession NOT to convert MIME to RichText when it opens a document. This must be done before you retrieve your document. e.g.
session.setConvertMIME(false);

Document doc = db.getDocumentByUNID(someunid);

// YOU CAN NOW HAVE FUN WITH MIME
MIMEEntity me = doc.getMIMEEntity();

If you don’t do this, it will look to you as if the MIME was actually stored as RichText (the format) but what is really happened is that Notes is doing a sneaky conversion when you open the document.

This is a NotesSession-wide setting, so it is good practice to check what this setting was before you modify it. That way you can set it back to what it was before you changed it. e.g.

boolean wasConvertMime = session.isConvertMIME();

// Make sure it won't convert for us
session.setConvertMIME(false);

//DO YOUR MIME THING

// Set it back to whatever it was
session.setConvertMIME(wasConvertMime);

One last point, is that if you do any manipulation of MIME Entities (we will cover in another post), when you are finished you should use the closeMIMEEntities method to tell the document you are finished mucking around. This method has a ‘saveChanges’ parameter which indicates whether you want to keep what you have done, or discard whatever you were doing with MIMEEntities. By default it is ‘false’ or discard. This ‘savechanges’ is an in-memory process, e.g. it just means apply the changes to the document you have open. You still need to save the document to make the changes permanent.

MIMEEntity me = document.getMIMEEntity();

//DO YOUR MIME PROCESSING

//Apply the changes to the document
document.closeMIMEEntities(true);

// Save changed document for good
document.save();

Conclusion

I feel MIME is one of those things that is complicated and simple at the same time. Whenever I have to solve some MIME related problem, I know the answer will be simple, it is usually one line of code in the wrong place, or one bad MIME part header. But, the steps involved to debug that ONE change, are often complicated, and require a good understanding of what is actually going on both in MIME-land and in Domino-land. I hope this post has helped clarify at least some of it for you, please let me know if you have any questions (or if I have made a mistake somewhere)!



---------------------
http://camerongregor.com/2016/04/21/webmail-ui-you-must-learn-about-mime/
Apr 20, 2016
6 hits



Recent Blog Posts
66
XPages webmail – Using Mime Inspector to debug Mime
Tue, Feb 14th 2017 11:12a   Cameron Gregor
In a previous post in this series I did a bit of an overview on how MIME works. We also did a little bit about how MIME works in XPages + Domino land. With this knowledge in hand we can now start to analyse the different ways a ‘Pretty words, pictures and attachments’ can be stored in the document. During development of the ‘XPages Webmail’ interface, I encountered many problems which could only be solved by investigating the MIME content in detail. To help me do this, I
46
Pasting Images into XPages CKEditor
Sun, Feb 12th 2017 10:00p   Cameron Gregor
Programs like ‘Snipping Tool’ on Windows, are super useful for users to make a quick snapshot, do some quick markup on the image, paste into chat/email and send. Unfortunately when using the default configuration of CKEditor in XPages (the inputRichText control), support for pasting images is not available for all browsers, and even for the ones that do support it, the images are only pasted as a PNG data URI. I have explained data URI images in a previous post, so check that out if
4
Preventing pasting of remotely hosted images in CKEditor
Mon, Nov 14th 2016 11:21p   Cameron Gregor
In the previous post, I showed how to prevent a user from pasting Images from the Clipboard into CKEditor. This post is of a similar nature but is designed to ensure that users don’t paste images with URLs to external / internal applications. This post is part of my XPages webmail tips series, and addresses a problem where, a user copies and pastes some HTML that includes images, from a webpage and pastes it into CKEditor for a message that is then sent via email. The recipient is then una
5
Preventing Pasting of Images in CKEditor
Mon, Nov 14th 2016 12:43a   Cameron Gregor
In the process of developing our XPages ‘Webmail’ interface, we discovered that many recipients were unable to view embedded images in the emails. After investigating, it was caused by the images being embedded using Data URIs. Support for Data URI Images is not universal, and because it is supported in IBM Notes, everything looked like it was working ok, but a quick test viewing an email in Gmail confirmed a problem when images could not be seen. What is a Data URI? You are most lik
3
Controlling the order of Script Resources (e.g. Jquery) with a Custom ViewRootRenderer
Mon, Sep 19th 2016 9:28a   Cameron Gregor
When loading Client Side Javascript libraries in XPages, sometimes the order that the libraries are ‘encoded’ (or written in HTML) in the tag is important. For example jQuery and some of it’s plugins can have some issues if Dojo is encoded first. By default in XPages you don’t have too much say in what is written out first, a nifty workaround for this has been shared by Sven Hasselbach (here and here) which utilises the lesser known tag. This workaround ensures t
7
Review: JRebel with Domino OSGi development
Mon, Sep 5th 2016 11:53p   Cameron Gregor
Last year I finally figured out how to use JRebel with Domino, and I posted a how-to video. I thought I would do a quick follow up to say how it’s going. It is going great! I can’t imagine giving back my JRebel license. I have gone entire days without restarting my http server. If you are only developing xpages from within an NSF, and don’t do any OSGi plugin development, then you really don’t have much need for JRebel. But if you are involved in any OSGi Library developm
5
Extended Messages Control available as an XspLibrary
Tue, Jul 12th 2016 8:49a   Cameron Gregor
A while ago I shared an Extended version of the messages control which allows for multiple messages to be displayed for a single control at the same time. Originally this was just shared as a ‘control within an NSF’. One of the problems with the control within an NSF approach is that you repeatedly get an ‘unknown tag’ compilation problem which eventually goes away after a ‘project clean’ but it is very annoying nonetheless. I receiving a request to package
6
Webmail UI – You must learn about MIME
Wed, Apr 20th 2016 10:14a   Cameron Gregor
If you were like me, you spent many years developing classic Notes applications before making the switch to XPages. If this was the case, you were no doubt comfortable with the notion of a RichText field. You probably even occasionally did some RichText manipulation in LotusScript, adding Paragraphs and formatting using RichTextStyles and RichTextNavigators, attaching Files using EmbeddedObjects. And then XPages comes along, and says “If you want to edit any RichText through XPages, it i
3
Tips for Creating a Webmail UI with XPages
Tue, Apr 19th 2016 8:38a   Cameron Gregor
Over the past year my main project has been an XPages application for project-related Email correspondence, with formal document management thrown it as well and a bunch of Action Item / comment functionality surrounding it all. Developing the application as it’s own email client presented a few different challenges that may not be encountered in normal xpages development. Along the way I have come across a few different gotchas that I thought I better make record of, both the the benefit
4
My Slides from AUSLUG 2016 Presentations
Fri, Apr 15th 2016 2:45a   Cameron Gregor
This year at AUSLUG I presented 2 sessions. ‘Anatomy of a UI Control’ and ‘Using Source Control for Domino Development’. I have just uploaded the slides to the AUSLUG community and thought I would also share to the wider world! Slides and description of sessions are below. If you have any questions please let me know! I hope to share more about extension library / control development soon. Anatomy of a UI Control This session was designed to just spark a bit of curiosity




Created and Maintained by Yancy Lent - About - Planet Lotus Blog - Advertising - Mobile Edition