Follow-up to #2509218: Ensure that SafeString objects can be used in non-HTML contexts

Problem/Motivation

The parent issue transforms HTML into plain text, but does so merely by stripping tags and decoding entities. For transformation of longer HTML text, we may want to provide a separate output strategy.

Proposed resolution

Provide a PlainTextFormatted output strategy that will be used in email, non-HTML files and possibly in CLI output (i.e. exceptions). We already have a MailFormatHelper, so likely we can just move its code into the output strategy class and deprecate MailFormatHelper.

Remaining tasks

User interface changes

N/A

API changes

Addition of a new output strategy

Comments

stefan.r created an issue. See original summary.

plach’s picture

plach
he/him
Primary language Italian
Location Venezia
commented
Priority: Major » Normal
Issue tags: +SafeMarkup, +API addition
wim leers’s picture

wim leers
Location Ghent 🇧🇪🇪🇺
commented
Title: Provide a PlainTextFormatted output strategy » Provide a PlainTextMailOutput output strategy

Transplanting my comment at #2509218-165: Ensure that SafeString objects can be used in non-HTML contexts to here:

Ok, per #163, we need to deal with the mail thing here.

I think PlainTextFormattedOutput is an extremely confusing name. So let's try to find something better. This is the relevant code:

  /**
   * Transforms an HTML string into plain text, preserving its structure.
   *
   * The output will be suitable for use as 'format=flowed; delsp=yes' text
   * (RFC 3676) and can be passed directly to MailManagerInterface::mail() for sending.
   *
   * We deliberately use LF rather than CRLF, see MailManagerInterface::mail().
   *
   * This function provides suitable alternatives for the following tags:
   * <a> <em> <i> <strong> <b> <br> <p> <blockquote> <ul> <ol> <li> <dl> <dt>
   * <dd> <h1> <h2> <h3> <h4> <h5> <h6> <hr>
   *
   * …
   */
  public static function htmlToText($string, $allowed_tags = NULL) {

So it is transforming HTML into plain text, while preserving the HTML structure and just mapping it to a syntax defined in RFC 3676. That RFC is titled The Text/Plain Format and DelSp Parameters.

So it's actually transforming text/html to text/plain.

Suggested names based on this so far: StructuredPlainTextOutput, MailPlainTextOutput, PlainTextMailOutput.

Second, let's look at that RFC for inspiration:

3.  The Problem

   The Text/Plain media type is the lowest common denominator of
   Internet email, with lines of no more than 998 characters (by
   convention usually no more than 78), and where the carriage-return
   and line-feed (CRLF) sequence represents a line break (see [MIME-IMT]
   and [MSG-FMT]).

   Text/Plain is usually displayed as preformatted text, often in a
   fixed font.  That is, the characters start at the left margin of the
   display window, and advance to the right until a CRLF sequence is
   seen, at which point a new line is started, again at the left margin.
   When a line length exceeds the display window, some clients will wrap
   the line, while others invoke a horizontal scroll bar.

   Text which meets this description is defined by this memo as "fixed".

Suggested names based on this: PreformattedPlainTextOutput, MonospacedPlainTextOutput.

Conclusion: pick one of these names:

  1. StructuredPlainTextOutput
  2. MailPlainTextOutput
  3. PlainTextMailOutput
  4. PreformattedPlainTextOutput
  5. MonospacedPlainTextOutput

I think PlainTextMailOutput is the best one.

jhedstrom’s picture

jhedstrom
Primary language English
Location Portland, OR
commented

Since this format could potentially be used on CLI or other non-mail uses, PlainTextMailOutput might need to be differently named.

wim leers’s picture

wim leers
Location Ghent 🇧🇪🇪🇺
commented

#4: 

The Text/Plain media type is the lowest common denominator of Internet email […]

It's specifically designed for e-mail, it does more than just the <em> -> * mapping.

plach’s picture

plach
he/him
Primary language Italian
Location Venezia
commented

I don't think this is about mail only: it's about making available a generic logic to a wider audience. If I had to choose between PlainTextMailOutput and PlainTextFormattedOutput, I'd go with the latter. MarkedPlainTextOutput would work for me too.

StuartJNCC’s picture

StuartJNCC commented

How about RFC3676PlainTextOutput which then describes what it is not what it is intended to be used for?

wim leers’s picture

wim leers
Location Ghent 🇧🇪🇪🇺
commented

@StuartJNCC I considered that too, but 1) it's hard to read, 2) our naming rules would require it to be written as Rfc3676PlainTextOutput, which is even harder to read.

stefan.r’s picture

stefan.r commented
Title: Provide a PlainTextMailOutput output strategy » Provide a PlainTextFormattedOutput output strategy
Priority: Normal » Major

Discussed this with @dawehner, @plach, @jhedstrom, @Wim Leers and we can probably keep the 77-character RFC-specific logic in the mail helper and take out the HTML to text functionality into a PlainTextFormatted output strategy that can be used for mail, CLI etc.

As a followup to a critical this might be major, maybe normal, maybe won't fix - but it's not blocking any of the other issues, merely a DX improvement.

Leaving this at postponed because @alexpott wanted to do some work on something related.

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.6 was released on February 1, 2017 and is the final full bugfix release for the Drupal 8.2.x series. Drupal 8.2.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.3.0 on April 5, 2017. (Drupal 8.3.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.3.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.4 was released on January 3, 2018 and is the final full bugfix release for the Drupal 8.4.x series. Drupal 8.4.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.5.0 on March 7, 2018. (Drupal 8.5.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.5.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

joelpittet’s picture

joelpittet
he/him
Primary language English
Location Vancouver
commented
Version: 8.5.x-dev » 8.6.x-dev
Status: Postponed » Active

Related issues have been committed for a while.

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.

smustgrave’s picture

smustgrave commented
Status: Active » Postponed (maintainer needs more info)
Issue tags: +stale-issue-cleanup

Thank you for creating this issue to improve Drupal.

We are working to decide if this task is still relevant to a currently supported version of Drupal. There hasn't been any discussion here for over 8 years which suggests that this has either been implemented or is no longer relevant. Your thoughts on this will allow a decision to be made.

Since we need more information to move forward with this issue, the status is now Postponed (maintainer needs more info). If we don't receive additional information to help with the issue, it may be closed after three months.

Thanks!