Docs: client-side reference for Abilities API

[jonathanbossenger]

Now that we have a client-side package, we need reference docs for interacting with Abilities in JavaScript.

It should cover the basic client API.

• getAbilities() - Fetches all available abilities
• getAbility(name) - Retrieves a specific ability by name
• executeAbility(name, input) - Executes abilities

[gziolo]

Thank you for opening the issue. Noting, that there are also:

• registerAbility()
• unregisterAbility()

[jonathanbossenger]

@gziolo I just realised that the client package does contain a readme. Is it overkill to also add something the top level reference docs?

[gziolo]

Good catch. We will need a README file for the package at the time we publish it to npm. So let's plan to include it. It can always reference the docs folder for the time being.

[jonathanbossenger]

@gziolo @emdashcodes, I notice in the in the inline docs an example of a client-side Ability is navigating to a specific page in the dashboard.

I assume one would typically use Abilities registered in JavaScript for browser-based actions, vs Abilities registered in PHP would be more for interacting with WordPress data? Would that be correct?

[gziolo]

I assume one would typically use Abilities registered in JavaScript for browser-based actions, vs Abilities registered in PHP would be more for interacting with WordPress data? Would that be correct?

I don't have a formed opinion at this stage, but I would say that abilities executed with JavaScript callback offer more flexibility in the browser, as you can change UI state, preprocess something on the client, but also still perform some operations that change state on the server. At the same time, server-side abilities are limited to operating only within the scope of the server.

[emdashcodes]

I assume one would typically use Abilities registered in JavaScript for browser-based actions, vs Abilities registered in PHP would be more for interacting with WordPress data? Would that be correct?

I don't think that will always be true. For example, there may be client Abilities using the entities API allowing it to manipulate WordPress data, but with additional client functionality like undo/redo.

[jonathanbossenger]

Thanks, folks. When either of you has some time, the reference docs PR is ready for review.