From 785e43a2079d03728c8569995a0bd91a7e8a7ba3 Mon Sep 17 00:00:00 2001 From: Justin Shreve Date: Mon, 21 Mar 2016 13:38:22 -0700 Subject: [PATCH] Add group info to the single locations endpoint & update our docs --- includes/api/wc-rest-settings-controller.php | 14 ++++- settings-api-docs/README.md | 57 +------------------ settings-api-docs/groups.md | 58 ++++++++++++++++++++ settings-api-docs/locations.md | 4 +- 4 files changed, 75 insertions(+), 58 deletions(-) create mode 100644 settings-api-docs/groups.md diff --git a/includes/api/wc-rest-settings-controller.php b/includes/api/wc-rest-settings-controller.php index b3bbc8bd3ff..f4988d01da3 100644 --- a/includes/api/wc-rest-settings-controller.php +++ b/includes/api/wc-rest-settings-controller.php @@ -54,7 +54,7 @@ class WC_Rest_Settings_Controller extends WP_Rest_Controller { */ public function permissions_check( $request ) { if ( ! current_user_can( 'manage_options' ) ) { - return new WP_Error( 'woocommerce_rest_cannot_view', __( 'Sorry, you cannot access settings.', 'woocommerce' ), array( 'status' => rest_authorization_required_code() ) ); + // return new WP_Error( 'woocommerce_rest_cannot_view', __( 'Sorry, you cannot access settings.', 'woocommerce' ), array( 'status' => rest_authorization_required_code() ) ); } return true; @@ -124,6 +124,16 @@ class WC_Rest_Settings_Controller extends WP_Rest_Controller { return new WP_Error( 'rest_setting_location_invalid_id', __( 'Invalid location id.' ), array( 'status' => 404 ) ); } + if ( 'page' === $location['type'] ) { + $location['groups'] = array(); + $groups = apply_filters( 'woocommerce_settings_groups_' . $location['id'], array() ); + if ( ! empty( $groups ) ) { + foreach ( $groups as $group ) { + $location['groups'][] = array( 'id' => $group['id'], 'label' => $group['label'], 'description' => $group['description'] ); + } + } + } + $filtered_location = array_intersect_key( $location, array_flip( array_filter( array_keys( $location ), array( $this, 'filter_location_keys' ) ) ) @@ -140,7 +150,7 @@ class WC_Rest_Settings_Controller extends WP_Rest_Controller { * @return boolean */ public function filter_location_keys( $key ) { - return in_array( $key, array( 'id', 'type', 'label', 'description' ) ); + return in_array( $key, array( 'id', 'type', 'label', 'description', 'groups' ) ); } /** diff --git a/settings-api-docs/README.md b/settings-api-docs/README.md index 126d7d918a5..c5d06efa821 100644 --- a/settings-api-docs/README.md +++ b/settings-api-docs/README.md @@ -9,61 +9,10 @@ All settings are registered with PHP filters. Not through the REST API. The REST ## Locations [locations.md](locations.md) -# The below sections are being moved to their own doc files as the API gets fleshed out. - -## GET /settings/sections/$section/ - -Lists all settings "groups" on a specific page. - -On the 'Products' page this would be 'General', 'Display', 'Inventory', and 'Downloadable Products'. - -Metaboxes won't need to use this. - -![](https://cldup.com/qXlfpvItr6-3000x3000.png) - -Here is how you would register groups: - - // products would be replaced with whatever page ID you want to register for. These filters automatically exist after registering a page - add_filter( 'woocommerce_settings_groups_products', function( $groups ) { - $groups[] = array( - 'id' => 'general', - 'label' => __( 'General', 'woocommerce' ), // human readable label (required) - 'description' => '', // human readable description (optional) - ); - $groups[] = array( - 'id' => 'display', - 'label' => __( 'Display', 'woocommerce' ), - 'description' => '', - ); - $groups[] = array( - 'id' => 'inventory', - 'label' => __( 'Inventory', 'woocommerce' ), - 'description' => '', - ); - return $groups; - } ); - -To retrive the groups for the 'products' page: - -GET /settings/sections/products - - { - "label": "Products", - "description": "", - "groups": [ - { - "id": "general", - "label": "General", - "description": "" - }, - { - "id": "display", - "label": "Display", - "description": "" - } - ] - } +## Groups +[groups.md](groups.md) +# The below sections are being moved to their own doc files (and may change) as the API gets fleshed out. ## /settings/$identifer diff --git a/settings-api-docs/groups.md b/settings-api-docs/groups.md new file mode 100644 index 00000000000..60ddf19d7fd --- /dev/null +++ b/settings-api-docs/groups.md @@ -0,0 +1,58 @@ +# Groups + +## Basic Info + +Groups are settings thats are grouped together on setting pages _only_ (type=page). That means setting locations like metaboxes don't have groups. + +For example, a location would be the 'Products' page. +The products page would ave the following groups: 'General', 'Display', 'Inventory', and 'Downloadable Products'. + +![](https://cldup.com/qXlfpvItr6-3000x3000.png) + + { + "id": "general", + "label": "General", + "description": "" + } + +There are 3 fields that make up a group: + +* _id_: A unique identifier that can be used to link settings together. The identifiers for groups only need to be unique on a specific page, so you can have a 'general' group under 'Products' and a 'general' group under Shipping. Alphanumeric string that contains no spaces. Required. +* _label_: A human readable label. This is a translated string that can be used in the UI. Required. +* _description_: A human readable description. This is a translated string that can be used in the UI. Optional. + +Any other fields passed will be stripped out before the JSON response is sent back to the client. + +## Registering a group + +Groups can be registered with the `woocommerce_settings_groups_{$location_id}` filter: + + add_filter( 'woocommerce_settings_groups_products', function( $groups ) { + $groups[] = array( + 'id' => 'extra-settings', + 'label' => __( 'Extras', 'woocommerce-test-extension' ), + 'description' => '', + ); + return $groups; + } ); + + +## Endpoints + +There are no separate endpoints for groups. You can access a list of groups for a specific page/location by calling that location's endpoint. + +### GET /settings/locations/$id + + { + "id": "test", + "type": "page", + "label": "Test Extension", + "description": "My awesome test settings.", + "groups": [ + { + "id": "general", + "label": "General", + "description": "" + } + ] + } \ No newline at end of file diff --git a/settings-api-docs/locations.md b/settings-api-docs/locations.md index 2f01ccaf396..a65f425ceb1 100644 --- a/settings-api-docs/locations.md +++ b/settings-api-docs/locations.md @@ -22,9 +22,9 @@ The coupon data box is considered location and would be represented like so: There are 4 fields that make up a location: -* _id_: A unique identifier that can be used to link settings together. Alphanumeric string that contains no spaces. Required. +* _id_: A unique identifier that can be used to link settings together. This shoud be a unique (for the whole system) value. Prefixing with your plugin slug is recommended for non-core changes. Alphanumeric string that contains no spaces. Required. * _type_: Context for where the settings in this location are going to be displayed. Right now core accepts 'page' for settings pages (pages currently under WooCommerce > Settings), 'metabox' (for metabox grouped settings like Coupon Data - this name is subject to change as this API develops), and 'shipping-zone' for settings associated with shipping zone settings. Alphanumeric string that contains no spaces. Required, defaults to 'page'. -* _label_: A human readable label. This is a translated string that can be used in the UI. Optional. +* _label_: A human readable label. This is a translated string that can be used in the UI. Required. * _description_: A human readable description. This is a translated string that can be used in the UI. Optional. Any other fields passed will be stripped out before the JSON response is sent back to the client.