Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add reusable blocks documentation for remaining blocks (#40521) 

* Add documentation for woocommerce/product-radio-field

* Update woocommerce/product-taxonomy-field documentation

* Rename checkbox section for consistency

* Edit pricing attribute name for consistency

* Add documentation for woocommerce/product-pricing-field

* Add 'conditional' documentation

* Update README.md

* Add usage text

* Add documentation to collapsible

* Fix details across all readmes

* Add changelog

* Try adding video html tag

* Allow video html tag

* Fix wrong position in doc

* Rename 'name' to 'property' on InputControl props

* Fix mistake in label position
This commit is contained in:
Nathan Silveira 2023-10-03 09:49:46 -03:00 committed by GitHub
parent e224445bf6
commit bda564ad67
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 301 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.markdownlint.json
View File

@ -4,6 +4,7 @@
"MD007": { "indent": 4 },
"MD013": { "line_length": 9999 },
"MD024": { "allow_different_nesting": true },
"MD033": { "allowed_elements": ["video"] },
"no-hard-tabs": false,
"whitespace": false
}

5
packages/js/product-editor/changelog/doc-more-reusable-blocks Normal file
View File

@ -0,0 +1,5 @@
Significance: patch
Type: dev
Comment: Add reusable blocks documentation

2
packages/js/product-editor/src/blocks/checkbox/README.md
View File

@ -36,7 +36,7 @@ Property in which the checkbox value is stored.
Tooltip text that is shown when hovering the icon at the side of the label.
## Example
## Usage
Here's an example on the code that is used for the 'sold_individually' field in the Inventory section:

51
packages/js/product-editor/src/blocks/collapsible/README.md Normal file
View File

@ -0,0 +1,51 @@
# woocommerce/product-collapsible
Container with collapsible inner blocks.
![Collapsible](https://woocommerce.files.wordpress.com/2023/09/woocommerceproduct-collapsible.png)
## Attributes
### toggleText
- **Type**: `string`
- **Required**: ` Yes`
The text to display on the toggle button.
### initialCollapsed
- **Type**: `boolean`
- **Required**: ` Yes`
Controls if the content is collapsed by default.
### persistRender
- **Type**: `boolean`
- **Required**: ` Yes`
Controls if content is rendered to the DOM even when collapsed.
## Usage
Here's the code that was used to create the example in the screenshot above:
```php
$product_inventory_advanced = $product_inventory_section->add_block(
[
'id' => 'product-inventory-advanced',
'blockName' => 'woocommerce/product-collapsible',
'attributes' => [
'toggleText' => __( 'Advanced', 'woocommerce' ),
'initialCollapsed' => true,
'persistRender' => true,
],
]
);
$product_inventory_advanced->add_block(
[
// add block information here
]
)
```

45
packages/js/product-editor/src/blocks/conditional/README.md Normal file
View File

@ -0,0 +1,45 @@
# woocommerce/conditional
Container to only conditionally render inner blocks.
<video src="https://github.com/woocommerce/woocommerce/assets/13437655/ccf6888d-59bd-4f7c-9487-105e5e0d8166"></video>
## Attributes
### mustMatch
- **Type**: `Record< string, Array< string > >`
- **Required**: `Yes`
A list of requirements that must be met for the inner blocks to be rendered. The keys should reference properties from the product, and the values are possible values for that property so that the inner blocks are rendered.
## Usage
Here's the code that was used to create the example in the video above:
```php
$wrapper = $product_summary_field->get_parent()->add_block(
[
'id' => 'example-conditional-wrapper',
'blockName' => 'woocommerce/conditional',
'order' => $product_summary_field->get_order() + 5,
'attributes' => [
'mustMatch' => [
'name' => [ 'Car', 'Bike' ]
],
],
]
);
$wrapper->add_block(
[
'id' => 'example-pricing-field',
'blockName' => 'woocommerce/product-pricing-field',
'order' => $product_summary_field->get_order() + 5,
'attributes' => [
'label' => __( 'Example price field', 'woocommerce'),
'property' => 'custom_price',
'help' => 'This is a help text',
],
]
);
```

64
packages/js/product-editor/src/blocks/pricing/README.md Normal file
View File

@ -0,0 +1,64 @@
# woocommerce/product-pricing-field
A product price block with currency display.
![Product pricing field](https://woocommerce.files.wordpress.com/2023/09/woocommerceproduct-pricing-field.png)
## Attributes
### property
- **Type:** `String`
- **Required:** `Yes`
Property in which the price value is stored.
### label
- **Type:** `String`
- **Required:** `Yes`
Label that appears on top of the price field.
### help
- **Type:** `String`
- **Required:** `No`
Help text that appears below the price field.
## Usage
Here's the code that adds the field from the screenshot after the Summary field:
```php
<?php
if ( ! function_exists( 'add_pricing_field' ) ) {
function add_pricing_field( $product_summary_field ) {
$product_summary_field->get_parent()->add_block(
[
'id' => 'example-pricing-field',
'blockName' => 'woocommerce/product-pricing-field',
'order' => $product_summary_field->get_order() + 5,
'attributes' => [
'label' => __( 'Example price field', 'woocommerce'),
'property' => 'custom_price',
'help' => 'This is a help text',
],
]
);
}
}
if ( ! function_exists( 'example_hook_up_block_template_modifications_pricing' ) ) {
function example_hook_up_block_template_modifications_pricing() {
add_action(
'woocommerce_block_template_area_product-form_after_add_block_product-summary',
'add_pricing_field'
);
}
}
add_action( 'init', 'example_hook_up_block_template_modifications_pricing', 0 );
```

2
packages/js/product-editor/src/blocks/pricing/block.json
View File

@ -8,7 +8,7 @@
"keywords": [ "products", "price" ],
"textdomain": "default",
"attributes": {
"name": {
"property": {
"type": "string",
"__experimentalRole": "content"
},

6
packages/js/product-editor/src/blocks/pricing/edit.tsx
View File

@ -26,11 +26,11 @@ export function Edit( {
attributes,
}: ProductEditorBlockEditProps< PricingBlockAttributes > ) {
const blockProps = useWooBlockProps( attributes );
const { name, label, help } = attributes;
const { property, label, help } = attributes;
const [ price, setPrice ] = useEntityProp< string >(
'postType',
'product',
name
property
);
const inputProps = useCurrencyInputProps( {
value: price,
@ -61,7 +61,7 @@ export function Edit( {
<InputControl
{ ...inputProps }
id={ priceId }
name={ name }
name={ property }
label={ label || __( 'Price', 'woocommerce' ) }
/>
</BaseControl>

2
packages/js/product-editor/src/blocks/pricing/types.ts
View File

@ -4,7 +4,7 @@
import { BlockAttributes } from '@wordpress/blocks';
export interface PricingBlockAttributes extends BlockAttributes {
name: string;
property: string;
label: string;
help?: string;
}

60
packages/js/product-editor/src/blocks/radio/README.md Normal file
View File

@ -0,0 +1,60 @@
# woocommerce/product-radio-field block
Radio button field for the product editor.
![Product radio field](https://woocommerce.files.wordpress.com/2023/09/woocommerceproduct-radio-field.png)
## Attributes
### title
- **Type:** `String`
- **Required:** `Yes`
### description
- **Type:** `String`
- **Required:** `No`
### property
- **Type:** `String`
- **Required:** `Yes`
### options
- **Type:** `Array`
- **Required:** `Yes`
## Usage
Here's an example of the usage on the "Charge sales tax on" field in the Pricing section:
```php
$product_pricing_section->add_block(
[
'id' => 'product-sale-tax',
'blockName' => 'woocommerce/product-radio-field',
'order' => 30,
'attributes' => [
'title' => __( 'Charge sales tax on', 'woocommerce' ),
'property' => 'tax_status',
'options' => [
[
'label' => __( 'Product and shipping', 'woocommerce' ),
'value' => 'taxable',
],
[
'label' => __( 'Only shipping', 'woocommerce' ),
'value' => 'shipping',
],
[
'label' => __( "Don't charge tax", 'woocommerce' ),
'value' => 'none',
],
],
],
]
);
```

69
packages/js/product-editor/src/blocks/taxonomy/README.md
View File

@ -2,6 +2,55 @@
This is a block that displays a taxonomy field, allowing searching, selection, and creation of new items, to be used in a product context.
![Taxonomy block](https://woocommerce.files.wordpress.com/2023/09/woocommerceproduct-taxonomy-field.png)
## Attributes
### slug
- **Type:** `String`
- **Required:** `Yes`
The taxonomy slug.
### property
- **Type:** `String`
- **Required:** `Yes`
Property name in which the taxonomy value is stored in the product.
### label
- **Type:** `String`
- **Required:** `No`
Label that appears on top of the field.
### createTitle
- **Type:** `String`
- **Required:** `No`
Title of the dialog that appears when creating a new taxonomy.
### dialogNameHelpText
- **Type:** `String`
- **Required:** `No`
Help text that appears for the name field in the dialog that appears when creating a new taxonomy.
### parentTaxonomyText
- **Type:** `String`
- **Required:** `No`
Label for the parent taxonomy field in the dialog that appears when creating a new taxonomy.
## Usage
Please note that to use this block you need to have the custom taxonomy registered in the backend, attached to the products post type and added to the REST API. Here's a snippet that shows how to add an already registered taxonomy to the REST API:
```php
@ -49,3 +98,23 @@ function YOUR_PREFIX_rest_api_add_custom1_to_product( $product, $request, $creat
add_filter( 'woocommerce_rest_insert_product_object', 'YOUR_PREFIX_rest_api_add_custom1_to_product', 10, 3 );
```
Here's a snippet that shows how it is used for the Categories field:
```php
$product_catalog_section->add_block(
[
'id' => 'product-categories',
'blockName' => 'woocommerce/product-taxonomy-field',
'order' => 10,
'attributes' => [
'slug' => 'product_cat',
'property' => 'categories',
'label' => __( 'Categories', 'woocommerce' ),
'createTitle' => __( 'Create new category', 'woocommerce' ),
'dialogNameHelpText' => __( 'Shown to customers on the product page.', 'woocommerce' ),
'parentTaxonomyText' => __( 'Parent category', 'woocommerce' ),
],
]
);
```