Skip to content
This repository has been archived by the owner on Nov 29, 2023. It is now read-only.

2.0 beta 4

Pre-release
Pre-release
Compare
Choose a tag to compare
@sebastiangreger sebastiangreger released this 27 Oct 12:59
· 10 commits to develop since this release
v2.0-beta.4
4f1063f

As the plugin code, these release notes are beta -- any feedback on missing or unclear instructions are most welcome via Issues!

Changes from v2.0-beta.3

  • Small improvements on the French language translations (#126, thx @luce-carevic)
  • Compatibility update with Kirby core version 3.6

Commentions 2.0 — What's new?

Version 2.0 primarily brings significant UX improvements for the comments form and adds additional configuration options to accommodate varying preferences. In addition, a new "custom form fields" feature lays the foundation for advanced custom integrations and future developments. And this major release of course fixes some bugs and responds to small feature requests.

The Readme file on this branch is mostly up-to-date already, while a few breaking changes from v1.x are described at the end of this message.

Comment form UX improvements

  • Better error feedback in the frontend by utilizing Kirby's built-in backend validation mechanisms; native frontend validation is now disabled by default, but can be activated for custom JS implementations (#106)
  • The frontend now displays a meaningful error message when spam trap is triggered (no longer silently fails) (#95)
  • URLs in the comment form's website field can be entered with/without https:// (#83)
  • An optional autocomplete attribute can be configured for form fields (#83)
  • Configurable behaviour for anchor links after form submission (#99)
  • Configuration option to keep comment form displayed after successful submission (#96)
  • Configuration settings related to the frontend presentation have been moved from the config.php setup to a new (optional) $attrs variable in the commentions() helper. This allows more fine-grained control in different templates. At the same time, the helper commentions('grouped') has been removed. *breaking change*

Custom form fields

  • Setup and handling of additional fields (beyond name, email, website and comment)
  • Advanced validation rules for standard and custom fields in combination with new backend validation
  • Custom fields displayed and editable in the panel
  • Enables almost limitless customization of comment implementations
  • This comes with a required change to the configuration of form fields *breaking change*

Additional new features

  • Optional possibility to store the ID of authenticated users with their comments (#93)
  • Pagination in the panel views (#101)

Other updates

  • Snippets moved to subfolder commentions for cleaner integration (#78) *breaking change*
  • Form field name/id of comment text changed from message to text *breaking change*
  • Frontend form markup is now generated dynamically
  • Temporary fix for an upstream issue with broken datetime field in edit modal; pending an upstream bugfix, comment timestamps can currently only be edited with 5-minute precision (#102)
  • Stricter data-minimalist setup for webmentions storage (now only storing the URL by default, none of the parsed meta data; previous default can easily be restored, if desired) *breaking change*
  • Renamed the master branch on GitHub to main -- this may have implications if you are working with a local fork (though the development of v2.0 takes place in develop during the beta phase) *git configuration needed for collaborators*

Breaking changes and migration instructions

As the major (semver) version number indicates, sites previously using version 1.x require a handful of setup changes, each relevant under the following conditions (click to see detailed instructions for each case):

If you configured form fields using the setting sgkirby.commentions.commentfields


The newly gained flexibility in form field setup requires changes to the sgkirby.commentions.commentfields setting in config.php, if you have configured your site to use other than the default field setup.

In version 1.x, it was possible to set sgkirby.commentions.commentfields to an array that may contain a mix of simple and associative fields like

'sgkirby.commentions.commentfields' => [
  'name' => true,
  'email' => true,
  'website',
  'text',
],

Due to the improved configurability of the plugin it is now always necessary to provide an associative array, using an empty array value instead of the previous undefined values. At the same time a simple true is no longer enough to express required fields, but the config array has to be set up as follows:

'sgkirby.commentions.commentfields' => [
  'name' => [
    'required' => true,
  ],
  'email' => [
    'required' => true,
  ],
  'website' => [],
  'text' => [],
],

For more details, see the documentation on comment field configuration.

If you are processing Webmentions


The default fields stored for incoming webmentions have been changed to the bare technical minimum: storing the URL of the source. This is to ensure data-minmalism by default and to ease compliance with certain privacy laws. Re-adding other fields is of course possible, but it is recommended to only add such fields that are also used.

In version 1.x, the plugin also stored name and homepage URL of the author (if it can be parsed by the microformats parser) and a copy of the HTML of the source page. To restore that behaviour, you need to add the values text, name and website to the variable sgkirby.commentions.webmentionfields in your config.php:

'sgkirby.commentions.webmentionfields' => [
  'text',     // store source HTML
  'name',     // store author's realname
  'website',  // store author's homepage URL
],
If you are using any customized snippets (files site/snippets/commentions-*.php)


The location for custom snippets has moved from site/snippets to site/snippets/commentionsand the prefixcommentions-` has been removed from their name.

To migrate, move your customized snippets to the subfolder commentions and rename them by removing the prefix. However, keep in mind the following update as well.

If you are using a customized form snippet (file site/snippets/commentions-form.php)


This snippet has received significant updates that are closely tied to some of the new functionalities of v2. The most critical changes are:

  • name and id of field message are now text
  • the rendering of each field has been outsourced into a separate field.php snippet as it builds the bridge between backend and frontend (if you modify the snippet, try to use the field.php snippet unaltered whenever possible to receive future updates
  • the markup is affected by the new $attrs variable (as frontend settings are configured from the snippet call, not the config file)
  • the markup for the open/close mechanism has changed to a more universal and accessible <details>/<summary> structure
  • instead of Kirby's t() function for UI strings, the snippet now uses the plugin's own Frontend::uistring() function which allows more granular overrides of specific texts
If you used the setting sgkirby.commentions.hideforms in your config.php


This global setting (adding some HTML code to enable collapsing the forms) has been replaced with an optional attribute in your template. Remove the sgkirby.commentions.hideforms from your config.php and instead add the collapse attribute where you call the commention() or commention('form') helper:

// <?= commentions() ?> becomes:
<?= commentions('all',  ['collapse' => true]) ?>
// <?= commentions('form') ?> becomes:
<?= commentions('form',  ['collapse' => true]) ?>

Please also note that the HTML in the snippets/form.php (formerly snippets/commentions-form.php) has changed. The plugin now uses the <details>/<summary> element in order to provide collapsible forms out of the box in an accessible way. Version 1 rendered a more complicated markup that required additional custom JS code to enable the accordion effect.

If you used the commentions('grouped') helper and/or the config setting sgkirby.commentions.grouped


The helper commentions('grouped') has been removed in favour of adding a configuration attribute to commentions('list').
The configuration array for grouped output is no longer being read from the config.php but should be included as an attribute when calling commentions('grouped').

To apply the default grouping, a boolean true is sufficient:

<?= commentions('list', ['grouped' => true]) ?>

Otherwise, custom grouping rules can be defined by using an array:

// snippet call in template
<?= commentions('grouped') ?>

// with config.php settings
'sgkirby.commentions.grouped', [
  'read'            => 'Read by',
  'like'            => 'Likes',
  'repost'          => 'Reposts',
  'bookmark'        => 'Bookmarks',
  'rsvp:yes'        => 'RSVP: yes',
  'rsvp:maybe'      => 'RSVP: maybe',
  'rsvp:interested' => 'RSVP: interested',
  'rsvp:no'         => 'RSVP: no',
],

become

// configuration added as attribute array to the snippet call
<?= commentions('list'), [
  'grouped' => [
    'read'            => 'Read by',
    'like'            => 'Likes',
    'repost'          => 'Reposts',
    'bookmark'        => 'Bookmarks',
    'rsvp:yes'        => 'RSVP: yes',
    'rsvp:maybe'      => 'RSVP: maybe',
    'rsvp:interested' => 'RSVP: interested',
    'rsvp:no'         => 'RSVP: no',
  ],
],

Copy-pasting the array from config.php to the helper and renaming the helper from grouped to list should be all that is needed.

Contributors

luce-carevic
Assets 2
Loading