Apostrophe 3.18.0: Image cropping, document versions, and much more

[agilbert]

Hi everyone,

This is our biggest release announcement in quite some time. After taking some extra time in April baking everything, today we are very excited to share several major new Apostrophe features with you. Let's dive right in.

Image cropping

Image cropping has been a key Apostrophe feature for a long time, and we wanted to make sure we improved the editing experience when adding it to Apostrophe 3. With the cropping and focal point tools now released in Apostrophe 3.18, you can:

• maintain a single high resolution image in your media library with different crops for each widget in which it appears
• choose between a pre-fixed list of aspect ratios to easily create optimal image crops
• configure image size and aspect ratio constraints in your widget configuration (for example, only allowing high resolution landscape images for a hero widget, forcing square crops on a thumbnail image, etc.)
• pick a focal point on your image that can be used to ensure certain elements of that image are always visible

image-cropping.mov

With this new foundation laid, we have more image editing capabilities on the roadmap that we're looking forward to shipping. In the meantime, you can learn more about how to configure your image widgets via our core image widget documentation. Or just give cropping a try in our public demo and let us know what you think.

Document versions

Another important tool for editors is the ability to roll back your documents to previous versions. In A2, this was sometimes a bit messy because of how frequently documents were auto-saved while editing in context. In A3, we've simplified things to create a snapshot of a document version anytime it is published. Editors can then pull up a list of all of the published document versions, quickly preview the differences in the editor modal, and revert your draft state to an earlier snapshot.

document-versions.mov

Document Versions is currently only available with an Apostrophe Assembly subscription – please get in touch if you'd like to learn more about this feature or any of our other commercial solutions.

Observability with OpenTelemetry

Sometimes developers need insight into performance issues with their websites. OpenTelemetry is a widely adopted, open source solution for collecting performance "traces" that provide insight into where the time is going when a website responds to a request.

In Apostrophe 3.18, we've added optional OpenTelemetry support in the core. If you follow our cookbook recipe to install and enable OpenTelemetry in your Apostrophe project, you'll quickly be able to start posting detailed performance traces to your preferred back-end such as Jaeger or NewRelic.

Give it a try and let us know how we can make this even better at helping you deliver the best performing Apostrophe experiences.

More in-context editing support

Most custom widgets in Apostrophe are edited in a dialog box when the user clicks on the edit button. But there is another possibility: in-context editing on the page. The standard rich text widget is an example of this. The user types text directly on the page.

Following our new documentation for editing custom widgets in context, it's now easier to deliver a more intuitive editing experience for even the most complex custom widgets. There is some amazing potential here – we'd love to see what you come up with using this technique, drop in and share in our Discord.

As always, the full release notes are below 🙌 🙇

Apostrophe 3.18.0

Adds

• Images may now be cropped to suit a particular placement after selecting them. SVG files may not be cropped as it is not possible in the general case.
• Editors may also select a "focal point" for the image after selecting it. This ensures that this particular point remains visible even if CSS would otherwise crop it, which is a common issue in responsive design. See the @apostrophecms/image widget for a sample implementation of the necessary styles.
• Adds the aspectRatio option for image widgets. When set to [ w, h ] (a ratio of width to height), images are automatically cropped to this aspect ratio when chosen for that particular widget. If the user does not crop manually, then cropping happens automatically.
• Adds the minSize option for image widgets. This ensures that the images chosen are at least the given size [ width, height ], and also ensures the user cannot choose something smaller than that when cropping.
• Implements OpenTelemetry instrumentation.
• Developers may now specify an alternate Vue component to be used for editing the subfields of relationships, either at the field level or as a default for all relationships with a particular piece type.
• The widget type base module now always passes on the components option as browser data, so that individual widget type modules that support contextual editing can be implemented more conveniently.
• In-context widget editor components now receive a focused prop which is helpful in deciding when to display additional UI.
• Adds new configuration option - beforeExit async handler.
• Handlers listening for the apostrophe:run event are now able to send an exit code to the Apostrophe bootstrap routine.
• Support for Node.js 17 and 18. MongoDB connections to localhost will now successfully find a typical dev MongoDB server bound only to 127.0.0.1, Apostrophe can generate valid ipv6 URLs pointing back to itself, and webpack and vue-loader have been updated to address incompatibilities.
• Adds support for custom context menus provided by any module (see apos.doc.addContextOperation()).
• The AposSchema component now supports an optional generation prop which may be used to force a refresh when the value of the object changes externally. This is a compromise to avoid the performance hit of checking numerous subfields for possible changes every time the value prop changes in response to an input event.
• Adds new event @apostrophecms/doc:afterAllModesDeleted fired after all modes of a given document are purged.

Fixes

• Documentation of obsolete options has been removed.
• Dead code relating to activating in-context widget editors have been removed. They are always active and have been for some time. In the future they might be swapped in on scroll, but there will never be a need to swap them in "on click."
• The self.email method of modules now correctly accepts a default from address configured for a specific module via the from subproperty of the email option to that module. Thanks to chmdebeer for pointing out the issue and the fix.
• Fixes _urls not added on attachment fields when pieces API index is requested (Regression : the _urls field is not given in the JSON response after API call on a piece #3643)
• Fixes float field UI bug that transforms the value to integer when there is no field error and the first number after the decimal is 0.
• The nestedModuleSubdirs feature no longer throws an error and interrupts startup if a project contains both @apostrophecms/asset and asset, which should be considered separate module names.

Apostrophe 3.x modules

document-versions 1.0.0

• Initial release

Apostrophe 2.x modules

apostrophe-forms

• Allow server side event handlers to modify the response object sent after a form submission, and allow browser side event handlers to see that object.

apostrophe-workflow

• forceExportExistingRelatedDocuments: by default, when force exporting, a choice is also offered to force export related documents even if they already exist in the target locale, overwriting the document in the target locale. If this option is explicitly set to false, this choice is not offered.