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.

[kazoompa]

After reading all the comments above I was able to create a small add-on but have no clear idea how to use sf-field or sf-field-mode, the scope's form is always undefined. The documentation is really essential for a new feature. I am looking forward for an update :)

[Anthropic]

@kazoompa have you looked at the documentation this week, I made some updates to make it a little clearer on the weekend (in develop branch).

[kyse]

The extending docs actually cover the implementation details those details pretty well. But do yourself a favor and walk though the source on the builders to understand what they are actually doing. Will give you some good insight on how to extend your addons even further.

[kazoompa]

@Anthropic I did read the docs over the week-end and yesterday but had some problems with sf-field and sf-field-mode, Every time I used them the form of the add-on is undefined (I can provide code if necessary).

@kyse's, I have read the code as you suggested but I would do it again.

What would be lovely is a working sample that uses sf-field and sf-field-model and other goodies so people can use them and change the content to their needs :) I am trying to build a custom File Uploader and I use the existing ones as references but these use the old API and their own directives. I was hoping to see how sf-field can replace a custom directive for such an add-on, alas, no luck yet.

Cheers for the quick responses.

[kyse]

Not sure exactly what you mean when you say the form of the addon is undefined. I'm guessing you're referring to the form object on the control elements's scope? Sounds like your missing a directive on your template.

Could try drawing up a quick plunker of your usage of the directives to see what's going wrong. Try building out a simple input.

Here's another quick tip regarding using the directives together: the-template

You keep using 'sf-field-mode'. I'm hoping you mean sf-field-model by the way.

Also, if you're creating the field via some schema default addon setup, you might look at the lines in your form object creation to make sure nothings going wrong. Just set a breakpoint around these lines:

var f = schemaFormProvider.stdFormObj(name, schema, options);
    f.key = options.path;
    f.type = 'datepicker';
    options.lookup[sfPathProvider.stringify(options.path)] = f;
    return f;

[kazoompa]

Thanks @kyse, I did some screwing around and got the add-on go further using sf-field-model="replaceAll". I still have a lot to accomplish.

Out of curiosity, if you put a console.log() in your provider function you mentionned:

var myAddOn = function (name, schema, options) {
   if (schema.type === 'string' && ... ) {
     // ... some stuff
    console.log('I am here!');
   }
}

Do you also get a lot of 'I am here!'? I thought after this call this is not called again:

options.lookup[sfPathProvider.stringify(options.path)] = f

The options.lookup always enters the function clean, i.e.:

options.lookup[sfPathProvider.stringify(options.path)] === undefined

Thanks.

[kyse]

Running it only once wouldn't make sense. It's purpose is to test if a form definition not specifically defined to a specific type matches a condition to use that form type as the default (ie schema.type is string, and schema.format is datetimepicker, then this datetimepicker addon would be deafult instead of a stock text input control (or rather the default template). So I'd wager that method gets run at least once for every entry in your form definition. I have yet to use it yet though as most of what I'm doing is builder specific and all my form definitions specifically spell out what type I want to use.

sf-field-model="replaceAll" is useful if you need to apply the model target to other attributes besides ngModel. If left blank it should just create the ng-model attribute with the proper target for you.

[kazoompa]

Thanks a lot @kyse, you're paving the way for the light to come through ;)

I had to used replaceAll to make my add-on model properly initialized:

  <div class="form-group">
    <label>{{form.title}}</label>
    <input sf-field-model="replaceAll" type="text" class="form-control" ng-model="$$value$$.description" placeholder="Enter a description">
    <attachment-wrapper sf-field-model="replaceAll" files="$$value$$.attachments" multiple="true"></attachment-wrapper>
  </div>

attachment-wrapper is our custom directive for file uploads.

I'll be baaack :)

Cheers.

[LeonardoGentile]

@kyse @kazoompa thanks for your examples, even tough I'm having some difficulties following trough :) As my first comment I still think that a fully working example of a custom add-on using the new builder accompanying the docs would be very much appreciated

[kyse]

Did you look at the angular schema form add ons examples github page? I think they have a couple.

[Anthropic]

@LeonardoGentile you raise good points, I think the add-on generator repo needs to be updated too to make it clear what should be done for the new builder, @kornosaurus what are the chances? ;)

[nicklasb]

I believe that, actually, both the add-on repo and the generator accepts PRs... :-) WRT the add-on repo, and unless I am just given a PR to merge, I can add this next week (out sailing the seven seas),

[LeonardoGentile]

@kyse they look to me the old way to create an addon, maybe I really did not understand the difference old/new then.. @nicklasb I could send PR, if you could just point me to a working example...oh wait 😄

[kornosaurus]

@Anthropic I've been meaning to release some examples in the generator specific to the new builder, hopefully out this week actually

[Anthropic]

There's an example in the repo now. https://github.com/json-schema-form/angular-schema-form/blob/development/examples/add-on/calculate.js

Still need to update documentation though. How's the generator going @kornosaurus, any chance of an update?