[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Entity actions API.
   4   *
   5   * An action definition is the serializable subset of the DataViews Action
   6   * API: every property that is plain data (`id`, `label`, `isPrimary`,
   7   * `supportsBulk`, `context`, `modalHeader`, …). Properties that are
   8   * JavaScript callbacks, components, or elements (`callback`, `RenderModal`,
   9   * `isEligible`, `icon`, a `label` that depends on the items, …) cannot be
  10   * declared here. They are provided by a script module registered for the
  11   * entity along with its actions: its default export maps action ids to the
  12   * properties of each action that are JavaScript. An entity can have several
  13   * modules. Each module applies to the actions it was registered with, see
  14   * {@see wp_get_registered_entity_action_modules()}.
  15   *
  16   * Actions are registered on the `wp_entity_actions_api_init` action, and only there,
  17   * with {@see wp_register_entity_actions()} and {@see wp_unregister_entity_actions()}. The
  18   * other functions read the registry. WordPress core registers its own
  19   * actions the same way, from packages/core-actions.
  20   *
  21   * @package WordPress
  22   * @subpackage Entity Actions
  23   * @since 7.2.0
  24   */
  25  
  26  /**
  27   * Registers actions for an entity, see
  28   * {@see WP_Entity_Actions_Registry::register()}.
  29   *
  30   * It only runs on the `wp_entity_actions_api_init` action.
  31   *
  32   * @since 7.2.0
  33   *
  34   * @param string      $origin        Who registers the actions: `core`, or
  35   *                                   the slug of the plugin or theme.
  36   * @param string      $kind          The entity kind (e.g. `postType`).
  37   * @param string      $name          The entity name (e.g. `page`).
  38   * @param array[]     $actions       The list of action definitions, each with an `id`.
  39   * @param string|null $script_module The id of the script module providing
  40   *                                   the JavaScript parts of the actions, if any.
  41   * @return string[] The ids of the actions registered, in the order of the
  42   *                  call. Empty when none is.
  43   */
  44  function wp_register_entity_actions( $origin, $kind, $name, $actions, $script_module = null ) {
  45      return WP_Entity_Actions_Registry::get_instance()->register( $origin, $kind, $name, $actions, $script_module );
  46  }
  47  
  48  /**
  49   * Unregisters actions of an entity, see
  50   * {@see WP_Entity_Actions_Registry::unregister()}.
  51   *
  52   * It only runs on the `wp_entity_actions_api_init` action.
  53   *
  54   * @since 7.2.0
  55   *
  56   * @param string        $kind The entity kind (e.g. `postType`).
  57   * @param string        $name The entity name (e.g. `page`).
  58   * @param string[]|null $ids  The ids of the actions to unregister. Default
  59   *                            null, every action of the entity.
  60   * @return array[] The list of the definitions unregistered, in
  61   *                 registration order. Empty when none is.
  62   */
  63  function wp_unregister_entity_actions( $kind, $name, $ids = null ) {
  64      return WP_Entity_Actions_Registry::get_instance()->unregister( $kind, $name, $ids );
  65  }
  66  
  67  /**
  68   * Returns the actions registered for the given entity.
  69   *
  70   * @since 7.2.0
  71   *
  72   * @param string $kind The entity kind (e.g. `postType`).
  73   * @param string $name The entity name (e.g. `page`).
  74   * @return array[] The list of registered action definitions, in
  75   *                 registration order. Empty until the `init` action has
  76   *                 completed: a read before then is refused.
  77   */
  78  function wp_get_registered_entity_actions( $kind, $name ) {
  79      return WP_Entity_Actions_Registry::get_instance()->get_registered( $kind, $name );
  80  }
  81  
  82  /**
  83   * Returns the script modules registered for the given entity.
  84   *
  85   * @since 7.2.0
  86   *
  87   * @param string $kind The entity kind (e.g. `postType`).
  88   * @param string $name The entity name (e.g. `page`).
  89   * @return array[] {
  90   *     The script modules, in registration order. Empty until the `init`
  91   *     action has completed: a read before then is refused.
  92   *
  93   *     @type array ...$0 {
  94   *         @type string   $id      The id of the script module.
  95   *         @type string[] $actions The ids of the actions the module applies
  96   *                                 to, in registration order.
  97   *     }
  98   * }
  99   */
 100  function wp_get_registered_entity_action_modules( $kind, $name ) {
 101      return WP_Entity_Actions_Registry::get_instance()->get_registered_action_modules( $kind, $name );
 102  }
 103  
 104  /**
 105   * Returns the ids of all script modules registered for any entity.
 106   *
 107   * @since 7.2.0
 108   *
 109   * @return array<string, array<string, string[]>> The lists of module ids,
 110   *                                                keyed by kind, then by
 111   *                                                name. Empty until the
 112   *                                                `init` action has
 113   *                                                completed: a read before
 114   *                                                then is refused.
 115   */
 116  function wp_get_all_registered_entity_action_modules() {
 117      return WP_Entity_Actions_Registry::get_instance()->get_all_registered_action_modules();
 118  }
 119  
 120  /**
 121   * Declares the script modules of the entity actions as dependencies of the
 122   * editor script, see _wp_add_entity_modules_to_editor_script().
 123   *
 124   * The actions are loaded by `usePostActions()` of the editor script, so every
 125   * screen showing them loads it.
 126   *
 127   * The `admin_footer` action passes it no argument, so the global registry is
 128   * used. In other scenarios (tests), the scripts are given directly.
 129   *
 130   * @since 7.2.0
 131   * @access private
 132   *
 133   * @param WP_Scripts|null $scripts The scripts registry. Defaults to the global one.
 134   */
 135  function _wp_add_entity_action_modules_to_editor_script( $scripts = null ) {
 136      _wp_add_entity_modules_to_editor_script( $scripts, 'wp_get_all_registered_entity_action_modules' );
 137  }
 138  
 139  /**
 140   * Preloads the actions of the post types the editors list.
 141   *
 142   * The editors read them from the `/wp/v2/entity-actions` route as they load,
 143   * see `useEntityActions()` in
 144   * packages/editor/src/dataviews/entity-actions-loader.ts in Gutenberg. The
 145   * post editor reads those of the edited post in its actions menu. The site
 146   * editor reads those of the edited post, if any, and of the post types of the
 147   * screen it opens on, whose lists show the actions of their items. A path must
 148   * match the request of the `getEntityActionsConfig` core data resolver, see
 149   * packages/core-data/src/resolvers.js in Gutenberg.
 150   *
 151   * @since 7.2.0
 152   * @access private
 153   *
 154   * @param mixed $paths   REST API paths to preload.
 155   * @param mixed $context Optional. Block editor context. Default null.
 156   * @return mixed Filtered preload paths. See _wp_add_entity_preload_paths().
 157   */
 158  function _wp_preload_entity_actions( $paths, $context = null ) {
 159      return _wp_add_entity_preload_paths( $paths, $context, '/wp/v2/entity-actions' );
 160  }