Add-ons with the new builder

[LeonardoGentile]

Hello,
I've read the documentation on extending schema form and at the same time I've seen the source code of some add-ons.

There is quite some confusion about the old and new way of building add-ons, and it seems there is no transition documentations about it (or I've missed it).

For example, many addons uses something like this:

schemaFormDecoratorsProvider.addMapping(
      'bootstrapDecorator',
      'awesome',
       'templates/my/addon.html',
);

while in the docs it is a bit different:

schemaFormDecoratorsProvider.defineAddOn(
    'bootstrapDecorator',         // Name of the decorator you want to add to.
    'awesome',                    // Form type that should render this add-on
    'templates/my/addon.html',    // Template name in $templateCache
    sfBuilderProvider.stdBuilders // List of builder functions to apply.
  );

which one to use? What's the difference? Is the 4th argument optional?

Then, in many example I've seen:

schemaFormDecoratorsProvider.createDirective(
      'awesome',
      'templates/my/addon.html'
 );

but inspecting the source code of ASF I could read this:

  /**************************************************
   * DEPRECATED                                     *
   * The new builder and sf-field is preferred, but *
   * we keep this in during a transitional period   *
   * so that add-ons that don't use the new builder *
   * works.                                         *
   **************************************************/
   //TODO: Move to a compatability extra script.
   var createDirective = function(name) {

so it seems deprecated, how the preferred sf-field is supposed to be used instead?

Could you please update the doc or give a brief explanation here?
Even better an example of an add-on entirely written to be specific for the new builder.

Thanks

[Anthropic]

@LeonardoGentile the new version is defineAddOn with the builder provider. That is why the docs were updated. Add-on using the old method will need to be updated if they don't use the default set of builders. But many haven't yet.

There will be more info on this when alphas for v1.0.0 are released as it will potentially break some older add-on. Many add-on writers are still involved so we should be able to get most to update.

The new Material Design decorator uses the new builder, but being a whole decorator isn't exactly how you would do an add-on. But could give some guidance. But yes, we need to update the date picker demo if that hasn't been done yet.

[Anthropic]

@nicklasb does your add-on use the new builder? If not any chance of an update so it can be highlighted as an example?

[nicklasb]

No it doesn't, but obviously, it should.
Or rather, if the user selects to include the external angular-schema-form-bootstrap instead of the built-in it does, but no, the examples and the dependencies doesn't.

I will fix that and make a release, you should be able to use that soon.

[nicklasb]

Released:
https://github.com/OptimalBPM/angular-schema-form-dynamic-select/releases/tag/v0.15.0

[Anthropic]

@LeonardoGentile give that a look and if you think it helps enough as a reference let us know and I will update docs :)

Thanks @nicklasb for a quick response 👍

[LeonardoGentile]

@Anthropic @nicklasb thanks for the quick reply!

Unless I've missed something the release 0.15.0 of dynamic selects doesn't make things much more clear. The plugin is just using the external bootstrap but it still using the addMapping instead of defineAddOn and the list of builder functions to apply

[nicklasb]

I was just addressing what @Anthropic asked for, the bootstrap decorator.
What, you're expecting me to read the entire issue? :-)

I will fix that later, meanwhile, please imagine ASFDS using defineAddOn. :-)

[Anthropic]

@LeonardoGentile they're not very different, it is really an alias for a very similar function. Did you look at the Material repo?
If you like at define decorator it is nearly identical but just with multiple 'add-on' being the templates for the decorator.
https://github.com/json-schema-form/angular-schema-form-material/blob/develop/src/material-decorator.js

[LeonardoGentile]

ok I'll take a look there 👍
@nicklasb you made me laugh 😄

[raoulus]

+1
To me the documentation is also pretty confusing. For the new builder I couldn't find any helpful documentation. I spent for more time than I want in creating custom directives...

[nicklasb]

@raoulus In the add:ons repo, I will update the examples to use the new builder soon(we take PR:s, too).
The documentation there will then also follow that pattern.

[kyse]

If you're hitting up the documentation for decorators, perhaps expand on adding multiple templates as well. When i tried using the defineDecorator version of your documentation instead of multiple defineAddon calls to inject into the existing bootstrapDecorator I couldn't figure out how to get the module to find the new decorator to use the templates. If I used bootstrapDecorator, instead of merging my new templates into the existing array it would replace the existing bootstrapDecorator completely.