|
| 1 | +# WordPress Abilities API Client |
| 2 | + |
| 3 | +Client library for the WordPress Abilities API, providing a standardized way to discover and execute WordPress capabilities. |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +The client is available in two ways: |
| 8 | + |
| 9 | +### 1. As an npm Package (Coming Soon) |
| 10 | + |
| 11 | +The npm package `@wordpress/abilities` is planned for future publication. Once published, you'll be able to install it via: |
| 12 | + |
| 13 | +```bash |
| 14 | +npm install @wordpress/abilities |
| 15 | +``` |
| 16 | + |
| 17 | +The npm package is designed for use with WordPress build tools (`@wordpress/scripts`). It requires the Abilities API plugin to be active in WordPress or via the Composer package, as it references the globally-loaded `wp.abilities` script at runtime. |
| 18 | + |
| 19 | +For now, the client is available through the WordPress script registration below. |
| 20 | + |
| 21 | +### 2. As a WordPress Script (Available Now) |
| 22 | + |
| 23 | +When the Abilities API is installed as a WordPress plugin, the client is automatically registered and available to enqueue: |
| 24 | + |
| 25 | +```php |
| 26 | +wp_enqueue_script( 'wp-abilities' ); |
| 27 | +``` |
| 28 | + |
| 29 | +#### For Composer Installations |
| 30 | + |
| 31 | +If you've installed the Abilities API via Composer, you need to register the script first. |
| 32 | + |
| 33 | +```php |
| 34 | +// Register the client script (usually in your plugin's init hook) |
| 35 | +add_action( 'init', function() { |
| 36 | + if ( function_exists( 'wp_abilities_register_client_script' ) ) { |
| 37 | + // Provide the path and URL to your vendor directory |
| 38 | + $base_path = __DIR__ . '/vendor/wordpress/abilities-api'; |
| 39 | + $base_url = plugins_url( 'vendor/wordpress/abilities-api', __FILE__ ); |
| 40 | + |
| 41 | + wp_abilities_register_client_script( $base_path, $base_url ); |
| 42 | + } |
| 43 | +} ); |
| 44 | + |
| 45 | +// Then enqueue it where needed |
| 46 | +add_action( 'wp_enqueue_scripts', function() { |
| 47 | + wp_enqueue_script( 'wp-abilities' ); |
| 48 | +} ); |
| 49 | +``` |
| 50 | + |
| 51 | +## Usage |
| 52 | + |
| 53 | +```javascript |
| 54 | +// In your WordPress plugin or theme JavaScript |
| 55 | +const { listAbilities, getAbility, executeAbility } = wp.abilities; |
| 56 | +// or import { listAbilities, getAbility, executeAbility } from '@wordpress/abilities'; depending on your setup |
| 57 | + |
| 58 | +// List all abilities |
| 59 | +const abilities = await listAbilities(); |
| 60 | + |
| 61 | +// Get a specific ability |
| 62 | +const ability = await getAbility( 'my-plugin/my-ability' ); |
| 63 | + |
| 64 | +// Execute an ability |
| 65 | +const result = await executeAbility( 'my-plugin/my-ability', { |
| 66 | + param1: 'value1', |
| 67 | + param2: 'value2' |
| 68 | +} ); |
| 69 | +``` |
| 70 | + |
| 71 | +### Using with React and WordPress Data |
| 72 | + |
| 73 | +The client includes a data store that integrates with `@wordpress/data` for use in React components: |
| 74 | + |
| 75 | +```javascript |
| 76 | +import { useSelect } from '@wordpress/data'; |
| 77 | +import { store as abilitiesStore } from '@wordpress/abilities'; |
| 78 | + |
| 79 | +function MyComponent() { |
| 80 | + const abilities = useSelect( |
| 81 | + ( select ) => select( abilitiesStore ).getAbilities(), |
| 82 | + [] |
| 83 | + ); |
| 84 | + |
| 85 | + const specificAbility = useSelect( |
| 86 | + ( select ) => select( abilitiesStore ).getAbility( 'my-plugin/my-ability' ), |
| 87 | + [] |
| 88 | + ); |
| 89 | + |
| 90 | + return ( |
| 91 | + <div> |
| 92 | + <h2>All Abilities</h2> |
| 93 | + <ul> |
| 94 | + { abilities.map( ( ability ) => ( |
| 95 | + <li key={ ability.name }> |
| 96 | + <strong>{ ability.label }</strong>: { ability.description } |
| 97 | + </li> |
| 98 | + ) ) } |
| 99 | + </ul> |
| 100 | + </div> |
| 101 | + ); |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +## API Reference |
| 106 | + |
| 107 | +### Functions |
| 108 | + |
| 109 | +#### `listAbilities(): Promise<Ability[]>` |
| 110 | + |
| 111 | +Returns all registered abilities. Automatically handles pagination to fetch all abilities across multiple pages if needed. |
| 112 | + |
| 113 | +```javascript |
| 114 | +const abilities = await listAbilities(); |
| 115 | +console.log( `Found ${abilities.length} abilities` ); |
| 116 | +``` |
| 117 | + |
| 118 | +#### `getAbility(name: string): Promise<Ability | null>` |
| 119 | + |
| 120 | +Returns a specific ability by name, or null if not found. |
| 121 | + |
| 122 | +```javascript |
| 123 | +const ability = await getAbility( 'my-plugin/create-post' ); |
| 124 | +if ( ability ) { |
| 125 | + console.log( `Found ability: ${ability.label}` ); |
| 126 | +} |
| 127 | +``` |
| 128 | + |
| 129 | +#### `executeAbility(name: string, input?: Record<string, any>): Promise<any>` |
| 130 | + |
| 131 | +Executes an ability with optional input parameters. The HTTP method is automatically determined based on the ability's type: |
| 132 | + |
| 133 | +- `resource` type abilities use GET (read-only operations) |
| 134 | +- `tool` type abilities use POST (write operations) |
| 135 | + |
| 136 | +```javascript |
| 137 | +// Execute a resource ability (GET) |
| 138 | +const data = await executeAbility( 'my-plugin/get-data', { |
| 139 | + id: 123 |
| 140 | +} ); |
| 141 | + |
| 142 | +// Execute a tool ability (POST) |
| 143 | +const result = await executeAbility( 'my-plugin/create-item', { |
| 144 | + title: 'New Item', |
| 145 | + content: 'Item content' |
| 146 | +} ); |
| 147 | +``` |
| 148 | + |
| 149 | +### Store Selectors |
| 150 | + |
| 151 | +When using with `@wordpress/data`: |
| 152 | + |
| 153 | +- `getAbilities()` - Returns all abilities from the store |
| 154 | +- `getAbility(name)` - Returns a specific ability from the store |
| 155 | + |
| 156 | +## Development |
| 157 | + |
| 158 | +```bash |
| 159 | +# Install dependencies |
| 160 | +npm install |
| 161 | + |
| 162 | +# Build the package |
| 163 | +npm run build |
| 164 | + |
| 165 | +# Run linting |
| 166 | +npm run lint:js |
| 167 | + |
| 168 | +# Type checking |
| 169 | +npm run typecheck |
| 170 | +``` |
0 commit comments