Clarification about htmlBody/textBody conversion

[Raphaël Ouazana]

Hi,

Reading the specification I find the conversion between htmlBody and textBody can be a little confusing.

• textBody: String|null The plain text body part for the message. If there is only an HTML version of the body, a plain text version will be generated from this.
• htmlBody: String|null The HTML body part for the message if present. If there is only a plain text version of the body, an HTML version will be generated from this.

What is the point of converting textBody into htmlBody?
I find it useless from a client point of view, and can even be troublesome as we are not able to tell any more which is the original version.

Note that other parts of the spec are more clear about this.
In draft:

• textBody: Optional. If not supplied and an htmlBody is, the server SHOULD generate a text version for the message from the HTML body.
• htmlBody: Optional.

In vacations:

• textBody: String|null The plain text part of the message to send in response to messages when the vacation response is enabled. If there is only an HTML version of the body, a plain text version SHOULD be generated from this.
• htmlBody: String|null The plain text message to send in response to messages when the vacation response is enabled. If there is only a plain text version of the body, an HTML version MAY be generated from this, or it may be sent as plain-text only.

If you agree that the current version is not enough clear, I can make a PR to match the vacation version which is more explicit.

Regards,

Raphaël Ouazana.

[Neil Jenkins]

On Wed, 6 Jul 2016, at 01:14 AM, Raphaël Ouazana wrote:

What is the point of converting textBody into htmlBody?

 

The idea was this: for simplicity, clients may only want to have to deal with rendering HTML rather than having a separate code path for rendering plain text (which will need to mark up URLs etc.). Similarly, basic clients may always want just to handle a plain text version.

 

(Requesting just "body" will return the htmlBody if the message has an HTML part, otherwise the textBody, which is probably what you want for most rich clients.)

 

Certainly I think we need the ability for clients to be able to always request a plain text version, for those that cannot safely handle HTML (older browser support, lower power devices). The ability to always request an HTML version is arguably less useful, although is consistent.

 

If we dropped the generation of an HTML version we could make it:

 

• textBody: String The plain text body part for the message. If there is only an HTML version of the body, a plain text version MUST be generated from this.
  

• htmlBody: String|null The HTML body part for the message if present.
  

 

Perhaps a better alternative (and more consistent) is to make the standard "textBody"/"htmlBody" properties be only if present, but add special properties "generate-htmlBody"/"generate-textBody" you could request that would then generate a "textBody"/"htmlBody" if not present. (This is a bit like the special "body" property you can request; it's not actually a property that's returned, but it affects what is returned for textBody/htmlBody). Thoughts?

 

Neil.

[Raphaël Ouazana]

Le mercredi 6 juillet 2016 04:02:24 UTC+2, Neil Jenkins a écrit :

On Wed, 6 Jul 2016, at 01:14 AM, Raphaël Ouazana wrote:

What is the point of converting textBody into htmlBody?

 

The idea was this: for simplicity, clients may only want to have to deal with rendering HTML rather than having a separate code path for rendering plain text (which will need to mark up URLs etc.). Similarly, basic clients may always want just to handle a plain text version.

 

(Requesting just "body" will return the htmlBody if the message has an HTML part, otherwise the textBody, which is probably what you want for most rich clients.)

 

Certainly I think we need the ability for clients to be able to always request a plain text version, for those that cannot safely handle HTML (older browser support, lower power devices). The ability to always request an HTML version is arguably less useful, although is consistent.

 

If we dropped the generation of an HTML version we could make it:

 

• textBody: String The plain text body part for the message. If there is only an HTML version of the body, a plain text version MUST be generated from this.
  
• htmlBody: String|null The HTML body part for the message if present.
  

Thank you for your answer. This modification seems perfect to me.
 

Perhaps a better alternative (and more consistent) is to make the standard "textBody"/"htmlBody" properties be only if present, but add special properties "generate-htmlBody"/"generate-textBody" you could request that would then generate a "textBody"/"htmlBody" if not present. (This is a bit like the special "body" property you can request; it's not actually a property that's returned, but it affects what is returned for textBody/htmlBody). Thoughts?

This could be a good alternative too, allowing to keep original content clearly separated from computed content and allowing clients to choose which version they want.

An other alternative would be to ask for some special properties "generated-htmlBody" and "generated-textBody", but it is a little less consistent with for example "body" specification.

Regards,
Raphaël Ouazana.

[Neil Jenkins]

On Thu, 7 Jul 2016, at 12:58 AM, Raphaël Ouazana wrote:

If we dropped the generation of an HTML version we could make it:

 

• textBody: String The plain text body part for the message. If there is only an HTML version of the body, a plain text version MUST be generated from this.
  
• htmlBody: String|null The HTML body part for the message if present.
  

 

Thank you for your answer. This modification seems perfect to me. 

 

OK, this seems reasonable. It's fairly consistent with how vacation response etc. are specified too. I've made this change.

 

Cheers,

Neil.