Remove settings api docs, moving to wiki
This commit is contained in:
Justin Shreve
parent
6bb546e11c
commit
9f7c769c4f
|
|
@ -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.
|
||||
|
|
@ -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'.
|
||||
|
||||
|
||||
|
||||
{
|
||||
"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": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue