Editor preferences based on XClass property references

Development
#1

Hello,

Currently, we propose to display editors to the user in different form (text or wysiwyg), according to the configuration.
The details of how an editor is displayed are documented here.

But, while the current configuration allows to configure the preferred editor type at different levels (e.g., wiki/space/user), the configuration does not take into account the usage of the editor. In other words, all editors are considered equals and changing the configuration will impact all of them.

This has some limitations. For instance, it is not possible to configure a different editor type specifically for the comments.

What I propose is to enrich the editor type configuration with the notion of XClass property. Technically, this implies adding a new propertyReference field in EditorBindingClass.

The following logic would be applied to select the displayed editor type (the new steps are highlighted in bold). In summary, an EditorBindingClass object with a matching propertyReference takes precedence over other EditorBindingClass objects.

  1. if a TextArea property in a XClass has an editor type defined, its value is used
  2. if a EditorBindingClass instance with a matching propertyReference and dataType exists for the current user, its value is used
  3. if a EditorBindingClass instance with a matching propertyReference and dataType exists in the current nest space, its value is used
  4. if a EditorBindingClass instance with a matching propertyReference and dataType exists in the current wiki, its value is used
  5. if a EditorBindingClass instance with an empty propertyReference and a matching dataType exists for the current user, its value is used
  6. if a EditorBindingClass instance with an empty propertyReference and a matching dataType exists in the current nest space, its value is used
  7. if a EditorBindingClass instance with an empty propertyReference and a matching dataType exists in the current wiki, its value is used
  8. if a matching configuration key exists in xwiki.properties, its value is used
  9. if the current user has defined a preferred editor to use, its value is used
  10. if the wiki has a defined preferred editor to use, its value is used

WDYT?

#2

It’s not very clear to me what format you propose for the propertyReference field value. The complete entity reference of a given xclass property ? How would you configure the comments default editor for the whole wiki, for example ?

#3

Configuring the comments default editor for the whole wiki required a new EditorBindingClass object in XWiki.XWikiPreferences with the following values:

  • propertyReference=XWiki.XWikiComments#comment
  • dataType=org.xwiki.rendering.syntax.SyntaxContent
  • roleHint=wysiwyg

For the format of propertyReference I’m thinking of ${classReference}#${propertyName} but I haven’t checked if we already have an equivalent format in the code base.

#4

Well we have a standard syntax already actually (see https://extensions.xwiki.org/xwiki/bin/view/Extension/Model%20Module#HClassPropertyReferences) so I guess it should be XWiki.XWikiComments^comment. Another possibility is to have two different fields for the xclass and the property, which is probably easier to set for most users and also allow to set a given default editor for a whole xclass (but it also mean that some user might set only the property name which probably does not make much sense).

#5

Hi Manuel. Could you give one example of a use case for this need? Seems someone wants to configure the editor for comments only but I’m curious to know why for ex a user would want the wysiwyg editor for comments but not for editing other xobjects. Thanks

#6

+1 for splitting propertyReference in classReference / propertyName.

In this case we’d select in priority the EditorBindingClass with matching classReference and propertyName, otherwise the one with a matching classReference and an empty propertyName (to configure all the properties of a given XClass).

This is useful when the administrator wants to use a given editor type in some part of the UI, regardless of the global configuration. For instance, in a use case raised by @Jsd and @lucaa, the administrator wants to set the editor type to text for the comments only (without changing the rest of the editor preferences).

#7

Seems you’ve just rephrased my question :slight_smile:

Could you explain the use case to me please?

Note: You should have started your post with it since all proposals need to come from a need. It’s always good to know the UCs. Thx!

#8

Actually, it’s the other way around, and with some details different:

An admin would want, for the whole wiki and for all users, to replace the Wysiwyg editor used for the comments input with a simpler editor (e.g. textarea). The reason to do that is that the fully fledged Wysiwyg editor is “too much” for the comments section, adding extra complexity where it’s not needed and giving an easy way for users to add complex content in a comment (such as, for example, macros).
It’s true that macros are also possible in a textarea field as well, but it’s not a matter of making sure there are no macros, but more of a matter of UX: in a textarea field the user needs to be a power user to add macros, in wysiwyg there is UI guiding one to do so.

In addition, in the annotations popup (which uses the same comments class setting), the editor is not only “too much” but also hinders the main usecase, which is adding a small, unformatted comment on a piece of text. It takes most of the in the small popup UI, causing the text to scroll early, taking more horizontal space (so annotating something on the right of the document will cause this popup to go out of the screen) and filling the UI with useless stuff (the html path at the bottom of the editor):

image

(there is also a focus issue here, where the focus is not directly in the editable field anymore when that popup loads, but that’s a bug that can be fixed independently of the used editor).

#9

Because of issue https://jira.xwiki.org/browse/XWIKI-18854 which prevents the admin from overwriting the class settings and which is not a bug but a feature, @mleduc tried to imagine a way in which the various editors used in various places would be configurable by an admin, in a generic way.

However, I am not really sure we need this whole layer of configuration, as it adds some configuration complexity which we’ll need to maintain, I think this may be specifically a comments / annotations issue, that we may fix easier by going back on the decision of not hardcoding the comments editor (done for https://jira.xwiki.org/browse/XWIKI-17318 , I think), and hardcode it back but to a simpler wysiwyg editor rather than the fully fledged one. I’ll let @mleduc take from here and make the proposal for that.

#10

To summarize, the main thing we miss is a lighter/less space-consuming rich editor, with fewer options (inline shortcuts such as [ or @ + some basic buttons for basic formatting for instance).
I need to discuss with @mflorea but I think this can be achieved by providing an alternate configuration for CKeditor where:

  • the toolbar is only showed when the focus is on the textarea.
  • the toolbar only provides actions for the simplest formatting (e.g.n bold, italic…)
  • the bottom bar with the breadcrumb is hidden

Then comes the question of where and how to integrate this new editor in the wiki. The main goal is to have it in the comments and annotations.

At the start of this discussion, I’d advocated for a very generic way to configure which type of editor should be shown to the user.
Conversely, we could also simply force the editor type on some places (for instance, the editor for the comments could be the new “lightweight-wysiwyg”, regardless of the wiki and user preferences).
A generic solution has a higher cost in terms of maintenance but allows wiki admin and users to fine-tune their UX.
I’m still in favor of some configuration options on the editor choice, but we need to agree on a tradeoff between maintenance costs and configurability.

#11

As we discussed in private, I think we could still honor the user / wiki settings here, but just deciding that when the user / wiki settings say “wysiwyg” , we’d just use the lightweight-wysiwyg instead of the fully fledged one.

#12

It is really the other way around: we first decide if, where and how we’d like to integrate it, to provide what functionality, and if it turns out that we do indeed want it, then we should ask ourselves the question of how to make it happen technically :slight_smile: .

#13

I really don’t see how this is feature? Where is this documented: the fact that mandatory classes are read-only? I can’t find anything on xwiki.org and xwiki-platform/MandatoryDocumentInitializer.java at master · xwiki/xwiki-platform · GitHub doesn’t mention anything about mandatory documents being read-only (or that they should be handled as read-only).

I find the proposal to extend the EditorBindingClass too complex. I think we need to fix https://jira.xwiki.org/browse/XWIKI-18854 which is definitely a bug for me: users (admins) should be able to customize mandatory documents (and classes) and those customizations should be kept as much as possible (of curse, if someone deletes a “mandatory” property it can be added back, but I don’t see why the user should not be able to modify the property meta data).

#14

I have seen the behaviour that is the opposite of XWIKI-18854 in action and I found it to be a bug, because it was so much honoring the “user settings” of mandatory classes that it was not even upgrading them from one XWiki version to another.
Precisely, the behaviour that I have seen was the following:

  • wiki A was installed at version V1 and used, without any change or modification or customization of mandatory classes
  • wiki A was upgraded to version V2
  • another wiki B was installed directly at version V2
  • mandatory classes are different on wiki A and wiki B and the functional result for the user is different → this is a bug, for the admin of the wiki, they haven’t done anything “wrong”.
    In addition, there is no button or anything that allows the admin on wiki A to reset that class to the “factory settings”, to make it identical with the class on wiki B.

As I said on the ticket XWIKI-18854 , if we find a way for the situation above to not happen while still allowing customization of the classes, I’m all for considering XWIKI-18854 a bug.

#15

I don’t see how what you describe is the opposite of XWIKI-18854. Honoring user customizations doesn’t mean we cannot upgrade mandatory documents. We allow users to customize standard (extension, non-mandatory) documents and we are still able to upgrade them because we merge. We could use merging also for mandatory documents, forcing the version created by the mandatory document initializer to win when there’s a conflict:

  • current version: what can be found in the database
  • new version: the version created by the mandatory document initializer (corresponding to the XWiki version in use)
  • previous version: the version created by the previous version of the mandatory document initializer (corresponding to the previous XWiki version); getting the previous version is tricky, but the mandatory document initializer could use a special save comment when saving/creating the document and then use this comment to find the previous version in history; of course, we won’t be able to get the previous version if the user deletes the history, but we would still able to do a simple merge (no 3-way) which is still better than what we currently do.
#16

From a functional point of view it’s not, of course, as you explained and as I explained.
In practice it used to be (and still is) , as long as the upgrade mechanism is not implemented (and it’s not).

My reasoning was in the sense of making sure that we’re not replacing one problem by another.

#17

Beyond all this, though, even if XWIKI-18854 was fixed, it would still not fully fix the need from the usecase from a functional point of view, as it would only leave the choice between full editor and no editor, the “simplified editor” option would still not be available and would still be interesting.

My personal opinion is that if the comments editor would be a simplified wysiwyg editor, this customization of the default editor would less be needed, XWIKI-18854 would not be a frequent usecase that needs attention and an upgrade merging mechanism for mandatory classes would not be needed. So while all those would remain valid questions, from a principial point of view, we could avoid the cost of answering them now.

Of course I don’t have UX tests results to prove that the simplified editor for comments satisfies more people than the full fledged editor, and than the textarea editor, it’s just a feeling I have.

#18

For me this is too complex and overkill and costly. We just need the ability to configure the WYSIWYG editor so that it can fit in smaller areas (compact format), e.g. when editing xproperties in the xobject editor.

Then the template displaying the comments would call the WYSIWYG editor with options to use the compact format of it.

An alternative is to make the WYSIWYG editor compact for all use cases, with ability to click on some >> button for example to expand the toolbar (and << to reduce its size).

#19

Of course. The only question is whether we hardcode the size of the editor for some areas of the wiki (and based on what?) or whether the admin of the wiki or the user should be able to decide their own sizes.

I’m for hardcoding a small editor for comments & annotations, but not for the xobject properties.

To me, this is a bonus of the small editor when the small editor is used (see the question above), but this shouldn’t force the editor to be small everywhere.

#20

I think we need to distinguish clearly between:

  • editor type (or category): text, wysiwyg
  • editor implementation: ckeditor
  • editor configuration:
$services.edit.syntaxContent.wysiwyg(
  'one **two** three',
  $services.rendering.resolveSyntax('xwiki/2.1'),
  {
    'id': 'description',
    'name': 'description',
    'rows': 25,
    'cols': 80
  }
)

The “simplified WYSIWYG editor” can be implemented:

  • either through a new category (‘wysiwyg-simple’), that the user can select on the comment property meta data
  • or through a new editor implementation (‘ckeditor-simple’), that the administrator needs to configure somehow for the comment property (e.g. using Manuel’s proposal)
  • or through configuration, using a custom displayer for the comment property
$services.edit.syntaxContent.wysiwyg($content, $syntax, {
  'name': 'XWiki.XWikiComments_0_comment',
  'simple': true,
  ...
})

I find the last option simpler to implement.