Converter Builders

[pjasiun]

View To Model:

It is not that simple to build an flexible helper functions for converters with readable API, they take too many parameters. But it should be simple to build converters.

This is why I suggest chainable API:

BuildViewConverterUsing( editor.data.toModel, editor.editing.toModel )
    .fromElement( 'strong' )
    .fromElement( 'b' )
    .fromElement( { element: 'span', style: { 'font-weight': fontWeightBold } } ).consuming( { style: 'font-weight' } )
    .toAttribute( { bold: true } );

BuildViewConverterUsing( editor.data.toModel, editor.editing.toModel )
    .fromElement( 'img' ).consuming( { name: true, class: 'src' } )
    .toElement( ( viewElement ) => new ModelElement( 'img', { 'src': viewElement.getAttribute( 'src' ) } ) );

BuildViewConverterUsing( editor.data.toModel, editor.editing.toModel )
    .fromElement( 'p' )
    .toElement( ( viewElement ) => new ModelElement( 'p' ) );

BuildViewConverterUsing( editor.data.toModel, editor.editing.toModel )
    .fromAttribute( { class: 'important' } )
    .toAttribute( { important: true } );

BuildViewConverterUsing( editor.data.toModel, editor.editing.toModel )
    .fromElement( 'a' ).consuming( { name: true, attribute: 'href' } )
    .toAttribute( ( viewElement ) => { return { 'link': viewElement.getAttribute( 'href' ) }; } );

Note that:

• BuildViewConverterUsing() may take many ViewConversionDispatchers, so it may handle many pipelines (editing and data) at the same time, or user can build separate converters for each pipeline.
• fromElement take Matcher (https://github.com/ckeditor/ckeditor5-engine/issues/274) instance or string or object which will be used to build Matcher.
• it is possible to add multiple elements listeners using fromElement,
• consuming defines the list of elements to consume from the last added element, or, if not defined, the consuming list is created based on the match,
• the API is scalable, is should be possible to add more methods in the future if needed (i.e. .withoutChildren()).

Model To View:

Converters from model to view could provide similar API:

BuildModelConverterUsing( editor.data.toView, editor.editing.toView )
    .fromElement( 'p' )
    .toElement( ( modelElement ) =>  new ViewElement( 'p' ) );

BuildModelConverterUsing( editor.data.toView, editor.editing.toView )
    .fromAttribute( 'link' )
    .toElement( ( key,  value ) =>  new ViewElement( 'a', { href: value } ) );

BuildModelConverterUsing( editor.data.toView, editor.editing.toView )
    .fromAttribute( 'bold' )
    .toElement( 'strong' );

[scofalik]

What I don't really like is that there is no definite point in the chain that marks that it's over. You could say that .toXXXX() is over but if the API should be extensible we might add something that makes sense after toXXXX(). Do you think this might happen?

If yes, maybe we should write them:
BuildViewConverter().fromElement().....toElement().for( dispatcher1, dispatcher2, ... );

[scofalik]

Okay, right now we agreed that .toXXXX() will add the callback and in future if we will have any modifiers applicable after .toXXXX() the builder will off the old callback and on modified one.

[pjasiun]

I think the priority here is keeping Builder API simple as possible. We do not need to care about the performance, it will be called once, during the editor initialisation.

And I like the for( dispatcher1, dispatcher2, ... ) part, but I should be able to use it also in different order:

BuildViewConverter().for( dispatcher1, dispatcher2, ... ).fromElement().....toElement();

it should not be a reason of a bug.

Also, talking about the priorities, we could introduce withPriority method:

...toAttribute( { bold: true } ).withPriority( HIGHEST );