T/1198: ViewElementConfig with helper converters. #1205

jodator · 2017-12-14T17:33:01Z

Suggested merge commit message (convention)

Enhancement: Introduce ViewElementDefinition. Closes ckeditor/ckeditor5#4216.

Additional information

I'd love to hear about this implementation as I'm not sure if it's the right way to do this. Basically the most interesting file would be configurationdefinedconverters.js which has 4 helpers for defining V->M and M->V converters for both ContainerElement and AttributeElmeent. All methods have docs so please check the usage first.

What I'm not sure about is mostly naming of that file. The other thing is that I've used other helpers that already existed buildModelConverter and buildViewConverter to build upon this helper methods.

What I'm not sure right now is how to pass ConversionDefinition object. Right now I pass config directly as it should be compatible with ConversionDefinition object as I've used option 2 from this as @pjasiun suggested. Maybe it would be nicer to group all those required properties on one object?

The other thins is the model part and how those util method accepts them as for Element I've used model string directly whereas for Attribute conversion I've used it as attributeValue as you pass attributeName as method parameter. The rationale behind this was how those two features were structured. In Heading there were many possible elements (hence many model attributes) while in Font I had only one attribute name (fontSize) with many size options as different values.

To see both in action check (or checkout t/ckeditor5-font/2 branch on ckeditor5 repo):

Element conversion: heading branch, example test
Attribute conversion: font branch and example configuration tests.

…efinition interface.

…documentation.

jodator · 2017-12-14T17:41:57Z

So the model part might be also like this:

{
    model: {
        attributeName: 'foo',
        attributeValue: 'bar'
    }
}
// or
{
    model: {
        element: 'baz'
    }
}

...but it could lead to mis configuration for feature that expects attribute to have the same name.

So after second thought I'm for leaving model's attribute meaning as is.

oskarwrobel · 2017-12-15T08:28:57Z

src/conversion/configurationdefinedconverters.js

+ *			view: {
+ *				name: 'h1'
+ *			},
+ *			acceptAlso: [


Maybe view could be an array in case of multiple definitions?

The view option defines default model->view conversion and it should always be one as it would be impossible to convert one model value to many (random?) view definitions ;).

The acceptAlso is used as a way to convert existing markup to model in view->model conversion. As in this example you always want to convert to h1 element but when loading content you want to map other elements to heading1 also.

So TL;DR: I don't think so ;)

I mean view as array only for view->model conversion. I wouldn't be afraid that someone will try to use it for converting to multiple or random element in case of model->view conversion.

Or I don't understand something. Maybe exactly the same definition will be used for both conversions.

But the configuration (like in heading) would be one:

return VirtualTestEditor .create( { plugins: [ HeadingEngine ], heading: { options: [ { model: 'paragraph', title: 'paragraph' }, { model: 'heading1', view: 'h1', acceptsAlso: [ { name: 'p', attributes: { 'data-heading': 'h1' }, priority: 'high' } ], title: 'User H1' } ] } } )

Ok, makes sense now :)

And also the feature would use it as:

https://github.com/ckeditor/ckeditor5-heading/blob/b8ef80f86121f8a1ec20c66314bf09eb837cb818/src/headingengine.js#L85-L100

Reinmar · 2017-12-15T12:59:32Z

src/conversion/configurationdefinedconverters.js

@@ -0,0 +1,310 @@
+/**


This file is named incorrectly. If it doesn't export a variable called configurationDefinedConverters then these are 3 separate words and hence the file should be called configuration-defined-converters.js.

I'm also unsure about naming this file after "configuration". What if I just want to use these helpers in my feature (which has no configuration)? Can we think about a different name?

definition-based-converters.js? :D

Or we need to find some proper name for these definitions. Something distinctive that we could use all around the code. Conversion specs, conversion maps, conversion rules, conversion... dunno. None of these is better than conversion definitions.

Yeah... I go with that definition-based-converts and other cleanups. We can review it once again after I make all the requested changes.

Reinmar · 2017-12-15T13:02:41Z

src/conversion/configurationdefinedconverters.js

+ *			},
+ *		}, [ dispatcher ] );
+ *
+ * Above will generate an HTML tag:


"the following DOM element:"

actually, isn't it a view element?

Reinmar · 2017-12-15T13:05:23Z

src/conversion/configurationdefinedconverters.js

+ * Helper for creating model to view converter from model's element
+ * to {@link module:engine/view/containerelement~ContainerElement ViewContainerElement}. The `acceptAlso` property is ignored.
+ *
+ * You can define conversion as simple model element to view element conversion using simplified definition:


I think it's always "by using". "using" means that the definition is an unrelated condition. https://english.stackexchange.com/questions/217815/what-is-difference-between-using-and-by-using

The same applies below – "by defining".

Reinmar · 2017-12-15T13:06:34Z

src/conversion/configurationdefinedconverters.js

+
+/**
+ * Helper for creating model to view converter from model's element
+ * to {@link module:engine/view/containerelement~ContainerElement ViewContainerElement}. The `acceptAlso` property is ignored.


What does the last sentence do here? You're introducing the function, so don't go into details like what kind of property is ignored because you haven't introduced this property yet.

Reinmar · 2017-12-15T13:12:44Z

src/conversion/configurationdefinedconverters.js

+}
+
+/**
+ * Helper for creating view to model converter from view to model element. It will convert also all matched view elements defined in


The first sentence makes no sense. "view to model converter" and then "from view to model"?

Reinmar · 2017-12-15T13:25:15Z

src/conversion/configurationdefinedconverters.js

+ *				attributes: {
+ *					'data-heading': 'true'
+ *				},
+ *				// it might require to define higher priority for elements matched by other features


Upper case and period.

You may need to use a high-priority listener to catch elements which are handled by other (usually – more generic) converters too.

Reinmar · 2017-12-15T13:25:54Z

src/conversion/configurationdefinedconverters.js

+ *		viewToModelElement( {
+ *			model: 'heading1',
+ *			view: {
+ *				name: 'h1'


Why using the object syntax in this case?

Reinmar · 2017-12-15T13:29:06Z

src/conversion/configurationdefinedconverters.js

+ *			]
+ *		}, [ dispatcher ] );
+ *
+ *    Above example will convert such existing HTML content:


The above
an existing view elements

Reinmar · 2017-12-15T13:30:37Z

src/view/element.js

+	 * Creates element instance from provided viewElementDefinition.
+	 *
+	 * @param {module:engine/view/viewelementdefinition~ViewElementDefinition} viewElementDefinition
+	 * @returns {Element}


Reinmar · 2017-12-15T13:36:21Z

src/view/element.js

+		const stylesObject = viewElementDefinition.styles;
+
+		if ( stylesObject ) {
+			attributes.style = toStylesString( stylesObject );


Do you guys think that we could avoid this stringification? E.g. by setting styles after creating this element (then, view Element should then have setStyles() method)?

Uncareful stringification is unsafe.

Reinmar · 2017-12-15T13:36:38Z

src/view/element.js

+		const classes = viewElementDefinition.classes;
+
+		if ( classes ) {
+			attributes.class = Array.isArray( classes ) ? classes.join( ' ' ) : classes;


Same as with styles below.

Reinmar · 2017-12-15T13:57:28Z

src/conversion/configurationdefinedconverters.js

+ *		<p data-heading="level1">Paragraph-like heading</p>
+ *		<div style="font-size:24px; font-weigh:bold;">Another non-semantic header</div>
+ *
+ * into `heading1` model element so after rendering it the output HTML will be cleaned up:


Again - avoid using "HTML".

Ooops. I haven't noticed that you mention here retrieving the data back. So it makes sense to call it HTML. But at the same time, maybe it's better to only mention here what ends up in the model. It will be clearer where and when the unification happen.

Reinmar · 2017-12-15T13:59:50Z

src/conversion/configurationdefinedconverters.js

+
+/**
+ * Helper for creating model to view converter from model's attribute
+ * to {@link module:engine/view/attributeelement~AttributeElement AttributeElement}. The `acceptAlso` property is ignored.


Don't specify the second param of {@link} because what you did here is actually breaking the link. It should look like: AttributeElement but you made it AttributeElement. If you won't specify the second param it will be rendered correctly. Specify the second param only if you want to write something custom like config.foo.bar (which would be better than the default bar). Also, make sure to always wrap code names in backticks.

…erters.

….createFromDefinition()` and use methods for adding styles & classes.

jodator · 2017-12-19T13:52:30Z

Most things were cleaned up. Remainig are:

extract matcher~Pattern definition (in docs) and add full support of it in acceptAlso (RegExp & callback remaining)
what to do with conflicting solutions for ConverterDefinition#model?

Ad. 1. It might be a follow up - but I can do it rather quickly now.
Ad. 2. It's either we're OK with it or it is adding a full flavor configuration for. (I'm for OK option here):

Full:

const elementConfig = {
    view: 'h1',
    model: {
        element: 'heading1'
    }
};
const attributeConfig = {
    view: { style: { 'font-size': 'big' } },
    model: {
        attribute: 'fontSize',
        value: 'big'
    }
};

Current:

const elementConfig = {
    view: 'h1',
    model: 'heading1'
};

const attributeConfig = {
    view: { style: { 'font-size': 'big' } },
    model: 'big' // A feature knows on what attribute it works ('fontSize')
};

And after looking how features will be configured it would be a lot easier to change only model value instead of reading which values of 'model' object to define. What can be more frustrating is that users could redefine attribute name in such (full) configuration which is also wrong.

I'm still for using model as either element name or attribute value - especially if we gonna let that be configurable.

/cc @pjasiun @Reinmar

Reinmar · 2017-12-20T12:35:53Z

Ad. 1. It might be a follow up - but I can do it rather quickly now.

If we can postpone it I'd rather do it later. Let's have features unblocked asap.

And after looking how features will be configured it would be a lot easier to change only model value instead of reading which values of 'model' object to define. What can be more frustrating is that users could redefine attribute name in such (full) configuration which is also wrong.

Exactly. It's enough to have model exposed in the config. The API of those helper methods can be different if @pjasiun doesn't like the current API that much. Those are independent things.

Still, I'd just progress with what we have now. All this will be reviewed once again soon anyway.

pjasiun · 2017-12-20T15:33:04Z

src/conversion/definition-based-converters.js

+
+	const viewDefinition = typeof view == 'string' ? { name: view } : view;
+
+	const viewDefinitions = Array.from( definition.acceptsAlso ? definition.acceptsAlso : [] );


Calling 2 variables in so similar way is asking for troubles. Why not leave "view" or "acceptsAlso"?

As, I see that you adds viewDefinition to viewDefinitions. Still, I would call it better: fromView and toView (or sourceView/targetView).

pjasiun · 2017-12-20T15:34:04Z

src/conversion/definition-based-converters.js

+// @param {module:engine/conversion/definition-based-converters~ConverterDefinition} definition An object that defines view to model
+// and model to view conversion.
+// @returns {Object}
+function parseConverterDefinition( definition ) {


This function gets JSON and return JSON, it parse nothing. It should be called "normaliseConverterDefinition".

That's the word I was seeking then :)

normalizeConverterDefinition() in AmE.

pjasiun · 2017-12-20T15:39:54Z

src/view/element.js

+	 * @param {module:engine/view/viewelementdefinition~ViewElementDefinition} viewElementDefinition
+	 * @returns {module:engine/view/element~Element}
+	 */
+	static createFromDefinition( viewElementDefinition ) {


Since this method will be removed from the view element I would put it in definition-based-converters.js.

pjasiun · 2017-12-20T15:47:47Z

A agree with @Reinmar that there is no sense to do a deep review at this point. I only left a few comments to the code.

In fact, the only thing I don't like in the current definition for features is the model property for attribute values and the fact that the same property in the very similar definition means something very different (in one case it is node name, in the other, it is attribute value). It might be very misleading for people writing these plugins, or if we will want to support mixed configuration at some point. Maybe we could call it just modelAttributeValue?

jodator · 2017-12-20T15:53:04Z

Maybe we could call it just modelAttributeValue?

If so we should then be consequent and ad two: modelAttribueValue and modelElementName and make those in configuration of features as in previous comment.

Also I don't see how those configuration would be mixed in one feature.

pjasiun · 2017-12-20T16:00:27Z

I talked with @jodator and realized that in fact, users do not need to know if they are defining element names or attribute values. For headings, which is the only case for element names so far, heading1 might be element name or attribute value and it's only a matter of the implementation which should not be important for the end user.

TL;DR: model is enough.

jodator · 2017-12-20T16:01:16Z

TL;DR: I win 😜

…oid confusion.

…to definition-based-converters as a private method.

pjasiun

It looks good for me. I leave it to @Reinmar for the final check and closing it.

jodator · 2017-12-21T11:17:04Z

Unfortunatelly I've found one bug. So please hold back this PR :(

…buteElement as an array.

jodator · 2017-12-21T11:48:26Z

So the but was when changing attribute value from 'a' to 'b' in one step. I've caught it when dealing with fontSize. Probably defining modelAttributeToview() converters for each attributeValue was not a good way to do this.

I've changed modelAttributeToViewAttributeElement() to accept array of all configured attribute values so there will be only one converter for given attribute instead of n as previously.

coveralls · 2017-12-21T12:19:28Z

Coverage remained the same at 100.0% when pulling 211d748 on t/1198 into 79f621f on master.

coveralls · 2017-12-21T12:37:07Z

Coverage remained the same at 100.0% when pulling 4760cce on t/1198 into 79f621f on master.

coveralls · 2017-12-21T12:38:42Z

Coverage remained the same at 100.0% when pulling 4760cce on t/1198 into 79f621f on master.

jodator added 13 commits December 5, 2017 14:47

Other: Initial implementation of unified converters from ViewElementD…

2b4352a

…efinition interface.

Other: Unify ViewElement converters for attribute and element.

ea95029

Other: Rename ViewElementDefinition attributes to plural names.

1e28cba

Tests: Add tests for Element.fromViewDefinition() method.

61ea426

Tests: Add tests for new conversion helpers.

b2f1044

Other: Rename AttributeElement conversion helpers.

a54727d

Other: Rename ContainerElement conversion helpers.

d7141cc

Other: Merge configuration defined converters into one file.

7381a09

Docs: Update module:engine/conversion/configurationdefinedconverters …

291d889

…documentation.

Merge branch 'master' into t/1198

1328204

Docs: Update configuration defined converters docs and method names.

f80abc2

Other: Revert changes in matcher.

2ac20cc

Tests: Update tests description in configurationdefinedconverters.js.

4604f04

jodator requested review from Reinmar and pjasiun December 14, 2017 17:33

oskarwrobel reviewed Dec 15, 2017

View reviewed changes

Reinmar reviewed Dec 15, 2017

View reviewed changes

jodator added 5 commits December 19, 2017 10:15

Other: Rename configurationdefinedconverters to definition-based-conv…

67de247

…erters.

Docs: Refine definition-based-converters documentation.

7d30fa1

Refactor: Rename view.Element.fromViewDefinition() to `view.Element…

86be1e7

….createFromDefinition()` and use methods for adding styles & classes.

Docs: Update ViewElementDefinition description.

e2ce318

Refactor: Use singular class and styles in ViewElementDefinition.

a48f922

pjasiun reviewed Dec 20, 2017

View reviewed changes

jodator added 4 commits December 21, 2017 08:12

Other: Rename internal variables of definition-based-converters to av…

f6b5676

…oid confusion.

Other: Move static method createFromDefinition from view:Element …

b77b76f

…to definition-based-converters as a private method.

Docs: Fix documentation links.

42848f7

Merge branch 'master' into t/1198

55f7555

pjasiun approved these changes Dec 21, 2017

View reviewed changes

Changed: Pass all ConverterDefinitions to modelAttributeToViewAttri…

5e4ebda

…buteElement as an array.

Merge branch 'master' into t/1198

211d748

Reinmar and others added 2 commits December 21, 2017 13:28

API docs fixes.

548734e

Typo fixes.

4760cce

Reinmar merged commit d2e9f06 into master Dec 21, 2017

Reinmar deleted the t/1198 branch December 21, 2017 13:03


		const viewDefinition = typeof view == 'string' ? { name: view } : view;

		const viewDefinitions = Array.from( definition.acceptsAlso ? definition.acceptsAlso : [] );

T/1198: ViewElementConfig with helper converters. #1205

T/1198: ViewElementConfig with helper converters. #1205

Conversation

jodator commented Dec 14, 2017 • edited by pomek

Suggested merge commit message (convention)

Additional information

jodator commented Dec 14, 2017

Choose a reason for hiding this comment

jodator Dec 15, 2017 • edited

Choose a reason for hiding this comment

oskarwrobel Dec 15, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jodator Dec 15, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jodator Dec 15, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Reinmar Dec 15, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jodator commented Dec 19, 2017

Reinmar commented Dec 20, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pjasiun commented Dec 20, 2017

jodator commented Dec 20, 2017

pjasiun commented Dec 20, 2017

jodator commented Dec 20, 2017

pjasiun left a comment

Choose a reason for hiding this comment

jodator commented Dec 21, 2017

jodator commented Dec 21, 2017

coveralls commented Dec 21, 2017

coveralls commented Dec 21, 2017

coveralls commented Dec 21, 2017

jodator commented Dec 14, 2017 •

edited by pomek

jodator Dec 15, 2017 •

edited

oskarwrobel Dec 15, 2017 •

edited

jodator Dec 15, 2017 •

edited

jodator Dec 15, 2017 •

edited

Reinmar Dec 15, 2017 •

edited

Reinmar commented Dec 20, 2017 •

edited