Versions¶
This documentation is written for 2.1.x. Where 2.0.x behaves differently, the page says so in a short box that links here. The older branches, 7.x-1.x and 8.x-1.x, are listed for completeness only.
At a glance¶
| 7.x-1.x | 8.x-1.x | 2.0.x | 2.1.x | |
|---|---|---|---|---|
| Drupal core | 7 | 8 | 10.3 and later, 11 (declared ^10.1 \|\| ^11, see the note below) |
11.2 and later, 12 (^11.2 \|\| ^12) |
| PHP | Not declared | Not declared | 8.1 and later | 8.3 and later |
| Status | Not maintained, last release 2017 | Not maintained, last release 2019, still listed as supported on drupal.org until 2.1.0 | Maintained, fixes only | Maintained, current |
| Security advisory coverage | No | Yes until the branch is marked unsupported, which is planned with 2.1.0 | Yes, stable releases | Yes, stable releases |
| Where you convert | A field added to the node form | The Import To Field form per content type, a field added to the node form | A widget on text_long and text_with_summary fields |
The same widget |
2.0.x and Drupal 10
2.0.x declares Drupal 10.1, but the widget attribute it uses exists only from 10.3. Treat 10.3 as the lowest core version that works. 2.1.x drops Drupal 10, 11.0 and 11.1.
Formats that convert¶
| Format | 7.x-1.x | 8.x-1.x | 2.0.x | 2.1.x |
|---|---|---|---|---|
| DOC, DOCX | Yes | Yes | Yes | Yes |
| ODT, RTF, PPTX | No | No | Declared, but they do not convert | Yes, off by default |
2.0.0 added the ODT, RTF and PPTX switches in Basic Settings, but the code looked for the converted file with a DOC or DOCX name, so those documents failed. They work from 2.1.0. The switches are still off by default: enable them in Basic Settings. PPTX needs the Impress component of LibreOffice, see Installation.
Features¶
| Feature | 7.x-1.x | 8.x-1.x | 2.0.x | 2.1.x |
|---|---|---|---|---|
| Keep the original document | No, it is deleted | No, it is deleted | Optional source file field | Optional source file field, moved to the directory of that field |
| Images of the document | Not handled | Not handled | Not handled, the paths are broken | Stored as managed files, tracked when you save |
Permission use doc to html widget |
Not available | Not available | Declared, never checked | Checked, given to Authenticated by the update |
| Text format of the converted text | Not handled | Not handled | Always full_html |
A widget setting |
| Drush commands | No | No | dth:version, dth:clean, dth:convert |
The same, dth:convert also finds files relative to the shell directory |
| Hooks and events | No | No | PreConvertEvent, PostConvertEvent and two hooks, but the pre convert hook had no effect |
The same, the hook now works and wins over the event |
| File names with spaces | Not checked | Not checked | Fail | Work |
| Concurrent conversions | Not checked | Not checked | Can fail, one shared LibreOffice profile | Work, one profile per conversion |
| Sanitized HTML | No | No | No | Yes, see The widget |
| Theming (formatter, template) | No | No | No | Yes, see Theming |
| Remove the first heading | No | No | No | Yes, a widget setting |
Known problems¶
- Data loss, 2.0.0 and 2.0.1. The cleanup after each conversion and the cron deleted every managed file whose address started with the working folder, permanent or not, in use or not. That includes the source documents kept in a file field. The folder name was matched as a prefix without a slash, so a folder such as
doc_to_html_otherwas matched too. 2.0.2 and 2.1.0 do not touch permanent files or files in use. - Files reachable by URL, 2.0.x. The upload and the converted HTML are written to
public://doc_to_htmland can be opened by URL until the cleanup runs. 2.1.x usestemporary://. - Broken images, 2.0.x. LibreOffice writes the images next to the HTML. The converted text keeps relative paths that point nowhere.
- Spaces in file names, 2.0.x. The conversion fails.
Which version to use¶
- Drupal 11.2 or later, or 12: use 2.1.x.
- Drupal 10, 11.0 or 11.1: stay on the latest 2.0.x release, which is 2.0.2 or later. Do not stay on 2.0.0 or 2.0.1.
- 7.x-1.x and 8.x-1.x: move to 2.x. Their core versions are end of life and the branches are not maintained. There is no automatic upgrade, see Upgrading.
Upgrade paths¶
| From | To 2.1.x |
|---|---|
| 2.0.x on Drupal 11.2 or later | Update the code, then run drush updb |
| 2.0.x on Drupal 10, 11.0 or 11.1 | Update to 2.0.2, then core to 11.2 or later, then 2.1.0 |
| Toward Drupal 12 | 2.1.0 on Drupal 11, drupal/text_with_summary if a field has a summary, then core 12 |
| 7.x-1.x, 8.x-1.x | Not supported |
The details, with what each update does and how to undo it, are in Upgrading.