diff --git a/settings-api-docs/README.md b/settings-api-docs/README.md deleted file mode 100644 index c5d06efa821..00000000000 --- a/settings-api-docs/README.md +++ /dev/null @@ -1,83 +0,0 @@ -# Settings API Proposal - -The Settings API is a set of WP-API endpoints that return information about WooCommerce settings. Settings can also be updated with the API. - -The API should be capable of handling settings in many different contexts including pages (WooCommerce > Settings), "metaboxes" (product data, coupon data), shipping zones, and be extendable to other contexts in the future. - -All settings are registered with PHP filters. Not through the REST API. The REST API is only for retrieving settings and updating them. - -## Locations -[locations.md](locations.md) - -## 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 - -Gets the actual settings to be displayed in a specific area. You can load settings for a specific group, or for a specific metabox. - -GET /settings/page:products:general would return settings for Settings > Products > General. -GET /settings/metabox:coupons would return settings for Coupons > Add New Coupon > Coupon Data metabox. - -To register settings: - - // The filter (page_products_general) should match the identifer for the area we are loading settings for. - apply_filters( 'woocommerce_settings_page_products_general', array( - array( - 'label' => __( 'Measurements', 'woocommerce' ), - 'type' => 'title', - 'id' => 'product_measurement_options' - ), - array( - 'label' => __( 'Weight Unit', 'woocommerce' ), - 'description' => __( 'This controls what unit you will define weights in.', 'woocommerce' ), - 'id' => 'woocommerce_weight_unit', - 'default' => 'kg', - 'type' => 'select', - 'options' => array( - 'kg' => __( 'kg', 'woocommerce' ), - 'g' => __( 'g', 'woocommerce' ), - 'lbs' => __( 'lbs', 'woocommerce' ), - 'oz' => __( 'oz', 'woocommerce' ), - ), - ) - ) ); - -Settings response: - - [ - { - "label": "Measurements", - "type": "title", - "id": "product_measurement_options" - }, - { - "label": "Weight Unit", - "description": "This controls what unit you will define weights in.", - "id": "woocommerce_weight_unit", - "default": "kg", - "type": "select", - "options": { - "kg": "kg", - "g": "g", - "lbs": "lbs", - "oz": "oz" - } - } - ] - -We should different form input types for 'type', text, textarea, select, radio, checkbox, ... - -## GET /settings/$identifer/$setting - -Get data for an individual setting. - -## PUT /settings/$identifer/$setting - -Update a setting by passing a new 'value' in the body. A success response will be returned. - -## PUT /settings/$identifer - -Update multiple settings at the same time with key => value pairs. A success response will be returned. diff --git a/settings-api-docs/groups.md b/settings-api-docs/groups.md deleted file mode 100644 index 60ddf19d7fd..00000000000 --- a/settings-api-docs/groups.md +++ /dev/null @@ -1,58 +0,0 @@ -# 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 deleted file mode 100644 index 287727402b1..00000000000 --- a/settings-api-docs/locations.md +++ /dev/null @@ -1,59 +0,0 @@ -# Locations - -## Basic Info - -Settings can be grouped together by location. - -A location is just a grouping of settings that all share a common 'location' key. -This is so you can pull all settings meant to be displayed together in a particular area. - -Example: - -In wp-admin there is a "Coupon Data" box on the "Add New Coupon" page. -The coupon data box is considered location and would be represented like so: - - { - "id": "coupon-data", - "type": "metabox", - "label": "Coupon Data", - "description": "" - } - - -There are 4 fields that make up all locations: - -* _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. 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. - -Locations with type 'page' can also have an associated set of 'groups' which are sub sections/pages. See [groups.md](groups.md). -Pages will return an array of groups in their response. - -## Registering a Location - -Locations can be registered with the `woocommerce_settings_locations` filter: - - add_filter( 'woocommerce_settings_locations', function( $locations ) { - $locations[] = array( - 'id' => 'test-extension', - 'type' => 'page', - 'label' => __( 'Test Extension', 'woocommerce-test-extension' ), - 'description' => __( 'My awesome test settings.', 'woocommerce-test-extension' ), - ); - return $locations; - } ); - - -## Endpoints - -### GET /settings/locations - -Returns a list of all locations supported by WC. -There is an optional ?type parameter that allows you to return only locations for a specific context (like all page locations). - -### GET /settings/locations/$id - -Returns information on a single location + any associated groups. \ No newline at end of file