How to expose a widget directive API

I'm creating a complex directive of a grid widget and I'm not sure where should I expose the grid directive API, i.e. it's properties (e.g. selectedItems) and methods (e.g. scrollRowIntoView(rowIndex)).

The options I'm considering are:

  1. Expose the API on the scope (my directive defined an isolated scope).
  2. Expose the API in the directive's controller (if I understand correctly this is what was done in the ngFormDirective).
  3. Expose a grid object on the scope which in turn exposes the API.
  4. Some kind of mix between the previous options (e.g. properties exposed on the scope, methods in the controller).

What I want to know is:

  • Is there a best practice for this use case?
  • What are the pros and cons for each alternative?
  • Are there any other valid alternatives?

Thanks!

Generally, you want to expose the bindings as attributes on your directive. That is, if I want to bind my array someItems to your grid, I'd expect your directive to look something like this: <my-grid my-items="someItems">.

You can expose hooks as attributes as well for things like "Run this function when the grid is resized". If I have a whenGridResized function on my scope, I'd want to set that as an attribute as well, like this: <my-grid onresize="whenGridResized()">.

In other cases you can't really use attributes, like your scrollRowIntoView() example. That would be a good candidate to expose in the directive controller, since that is something the directive user might want to call when other things occur in the system (such as DOM events).

So you should expose your API as attributes for events that happens inside your grid (things that you control), like onresize and ondelete or whatever. You can of course expose them in a controller as well.

When your directive needs to react to outside events like scrollRowIntoView(), you would to expose that in the directive controller since it would be a clunky API to expose such hooks as attributes.

You shouldn't expose your API through the scope since you want an isolated scope for your grid. Exposing it through the scope would mean that you have to set it your scopes parent, and it's almost never a good idea to access the parent scope directly.

TL;DR

A rule of thumb would be to expose as much as you can as attributes, and methods on your directive controller when attributes doesn't make sense. Exposing the same functionality in both attributes and your controller is a good idea since it's hard to anticipate how your users will use your directive.