Skip to content

Upgrading to 2.1.0

See Versions for what differs between the branches. This page is about the move to 2.1.0.

Which path to take

You run Path
Drupal 11.2 or later, with 2.0.x Update the code to 2.1.0, then drush updb.
Drupal 10, 11.0 or 11.1, with 2.0.x Update to 2.0.2 first. Then update core to 11.2 or later, then update the module to 2.1.0.
Drupal 11, going to Drupal 12 Update to 2.1.0 on Drupal 11. If the body field has a summary, require drupal/text_with_summary. Then update core to 12.
8.x-1.x or 7.x-1.x Not supported. There is no upgrade path from these branches.

drush updb stops with an error when the schema of the module is below 8003, which is a site that skipped the 2.0.x updates. The status report shows the requirement DOC to HTML: update path, with the text "Update to the latest 2.0.x release first, then to 2.1.0." Install the latest 2.0.x, run the updates, then go to 2.1.0.

Run the updates after you update the code:

composer update drupal/doc_to_html
drush updb -y
drush cr

Drupal core requirement

2.1.0 requires Drupal ^11.2 or ^12. The 2.0.x line declared ^10.1 but did not work there. Update core first if you run an older version, and stay on 2.0.2 until you do.

Drupal 12 and fields with a summary

Drupal 12 moved the summary widget of text_with_summary fields out of core. If a field has a summary, for example the Body of an Article, require the contrib module before you update core:

composer require drupal/text_with_summary
drush en text_with_summary

The widget of DOC to HTML uses the summary widget that is registered, whoever provides it. text_long fields need nothing.

What each update does

The updates run with drush updb. None of them changes the data of your nodes.

Update What it does Type How to undo it
doc_to_html_update_8004 Removes the temporary files of DOC to HTML that have no usage from the old folder public://<folder>, which core would remove anyway. Permanent files, files in use and unmanaged files stay. Irreversible The removed files cannot be restored by the module. Restore them from a backup if you need them.
doc_to_html_post_update_grant_widget_permission Gives use doc to html widget to the Authenticated role. Reversible Remove the permission from Authenticated at /admin/people/permissions.
doc_to_html_post_update_widget_text_format Sets the text format full_html on each DOC to HTML widget that has no format, when full_html exists. Reversible Change Text format for converted content in each widget, in Manage form display.
doc_to_html_post_update_install_editor Installs the core module editor if it is missing. Irreversible Nothing to do. DOC to HTML depends on editor, so it cannot be uninstalled while DOC to HTML is on.

Each update returns a message that says what it did and how to undo it:

  • 8004: "Removed N unused temporary files from the old public folder." If files remain: "M files remain there, check them and empty the folder by hand."
  • Permission: "Granted 'use doc to html widget' to the authenticated role. Revoke it at /admin/people/permissions if needed."
  • Text format: "Set the text format of N DOC to HTML widgets to full_html. Change it in each widget setting if needed." If full_html does not exist: "The full_html text format does not exist, no widget was changed."
  • Editor: "Installed the editor module, needed to track inline images." If it was there: "The editor module was already installed."

While files remain in the old public folder, the status report shows a warning DOC to HTML: files of the previous version with their number. Check them and empty the folder by hand when you do not need them.

The working folder moves to temporary://

Uploaded documents and converted HTML are no longer written to public://. Each conversion uses a folder of temporary://<folder>/. The Folder name setting is kept and now means a folder under temporary://. A value saved before 2.1.0 with the public:// scheme in front is read without the scheme.

See How the data flows.

Source documents

When a source file field is set, the document is moved to the upload directory of that field. It stays temporary until the node is saved, then it is permanent. Existing files are not moved.

New permission rules

The permission use doc to html widget was declared in 2.0.x but never checked. 2.1.0 checks it. The post update gives it to the Authenticated role, so everyone who can edit content today can still use the widget.

To restrict it:

  1. Go to /admin/people/permissions.
  2. Remove Use DOC to HTML widget from Authenticated.
  3. Give it to the roles that need it.

Also check administer doc to html settings. The update 8002 in 2.0.0 gave it to all roles with access administration pages. The status report now lists the non-administrator roles that have it. See Permissions.

Text format

Before, the widget forced the full_html format. Now the format is a widget setting. The post update sets full_html on existing widgets if that format exists, so nothing changes for you. A new widget starts with Keep the field's current format.

Other changes that may affect you

  • File names with spaces and special characters now work.
  • ODT, RTF and PPTX convert correctly. They are still off by default, so enable them in Basic Settings. The extension is matched in any case.
  • Images are saved as managed files in the new Image upload directory, default public://inline-images.
  • The HTML is sanitized after conversion. Scripts, frames, style, meta, title, link, head and base elements, event attributes and dangerous links are removed.
  • A hook_doc_to_html_pre_convert that changes the options now has an effect. If both a hook and an event set an option, the hook wins.
  • The setting Force UTF-8 encoding now has effect.
  • If proc_open is disabled, the conversion fails with a clear error and there is no fallback to shell_exec().
  • New widget setting Remove the first heading of the document, off by default.
  • New formatter DOC to HTML converted content, see Theming.
  • drush dth:convert looks for the file relative to the Drupal root, then relative to the directory of your shell, and prints only the body content.

Content saved with 2.0.x

With the body regex off, which is the default, 2.0.x saved the whole HTML document produced by LibreOffice, including its head and style elements. The update does not change saved content. If a page shows CSS as text, convert its source document again with 2.1.x.

Going back

No database schema changes. You can go back to 2.0.x by restoring the code. The folder temporary://<folder> stays unused, and the files removed by 8004 do not come back.

Code that calls the module

The interfaces keep the methods of 2.0.1 and add new ones. If you implement FileServiceInterface or CmdServiceInterface yourself, add the new methods. CmdServiceInterface::convertFile() is deprecated and keeps the contract of 2.0.1. escapeRealPath(), $overrideBodyRegex and $overrideBodyMatchIndex are deprecated too. See Services.