Update gallery docs
Mike Jolley
parent
faf83090f8
commit
c21e2207a2
|
|
@ -1,3 +1,13 @@
|
|||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
## Table of Contents
|
||||
|
||||
- [Backward Compatibility](#backward-compatibility)
|
||||
- [Roadmap](#roadmap)
|
||||
- [Feature requests](#feature-requests)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
WooCommerce has a minor release (e.g., 3.1, 3.2) every 3-4 months, typically per quarter. Each cycle consists of:
|
||||
|
||||
- 4-6 weeks development (1 sprint per week)
|
||||
|
|
|
|||
14
_Sidebar.md
14
_Sidebar.md
|
|
@ -1,11 +1,12 @@
|
|||
**Release Notes**
|
||||
- [2.6.x to 3.0.0 Developer Migration Notes](2.6.x-to-3.0.0-Developer-Migration-Notes)
|
||||
- [Enabling product gallery features (zoom, swipe, lightbox) in 3.0.0](Enabling-product-gallery-features-(zoom,-swipe,-lightbox)-in-3.0.0)
|
||||
- [Select2 fields not working in 3.0.x](https://github.com/woocommerce/woocommerce/wiki/Select2-fields-not-working-in-3.0.x)
|
||||
|
||||
**REST API**
|
||||
**REST API and CLI**
|
||||
- [Getting started with the REST API](https://github.com/woocommerce/woocommerce/wiki/Getting-started-with-the-REST-API)
|
||||
- [Contributing to the REST API](https://github.com/woocommerce/woocommerce/wiki/Contributing-to-the-WooCommerce-REST-API)
|
||||
- [WC CLI Overview](WC-CLI-Overview)
|
||||
- [WC CLI Commands](WC-CLI-Commands)
|
||||
|
||||
**CRUD & Data Descriptions**
|
||||
- [Database Description](https://github.com/woocommerce/woocommerce/wiki/Database-Description)
|
||||
|
|
@ -21,9 +22,9 @@
|
|||
- [Payment Token API](Payment-Token-API)
|
||||
- [Shipping Method API](Shipping-Method-API)
|
||||
|
||||
**CLI (Command line interface)**
|
||||
- [WC CLI Overview](WC-CLI-Overview)
|
||||
- [WC CLI Commands](WC-CLI-Commands)
|
||||
**Theming**
|
||||
- [Enabling product gallery features (zoom, swipe, lightbox)](Enabling-product-gallery-features-(zoom,-swipe,-lightbox))
|
||||
- [Template File Guidelines for Devs and Theme Authors](Template-File-Guidelines-for-Devs-and-Theme-Authors)
|
||||
|
||||
**Examples / Guides**
|
||||
- [How Taxes Work in WooCommerce](How-Taxes-Work-in-WooCommerce)
|
||||
|
|
@ -33,11 +34,10 @@
|
|||
- [wc_get_products and WC_Product_Query](https://github.com/woocommerce/woocommerce/wiki/wc_get_products-and-WC_Product_Query)
|
||||
- [Importer and Exporter](https://github.com/woocommerce/woocommerce/wiki/Product-CSV-Importer-&-Exporter)
|
||||
|
||||
**Contribution / Guidelines**
|
||||
**Contribution**
|
||||
- [Our Git Flow](https://github.com/woocommerce/woocommerce/wiki/WooCommerce-Git-Flow)
|
||||
- [How to ensure SCSS and scripts are minified](Contributing---How-to-ensure-SCSS-and-scripts-are-minified)
|
||||
- [CSS SASS coding guidelines and naming conventions](CSS-SASS-coding-guidelines-and-naming-conventions)
|
||||
- [Core Testing Checklist](https://github.com/woocommerce/woocommerce/wiki/Core-Testing-Checklist)
|
||||
- [String localisation guidelines](String-localisation-guidelines)
|
||||
- [Template File Guidelines for Devs and Theme Authors](Template-File-Guidelines-for-Devs-and-Theme-Authors)
|
||||
- [Deprecation in core](Deprecation-in-core)
|
||||
|
|
|
|||
|
|
@ -1,200 +0,0 @@
|
|||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
## Table of Contents
|
||||
|
||||
- [Use coding standards](#use-coding-standards)
|
||||
- [Template structure](#template-structure)
|
||||
- [Structuring templates logically](#structuring-templates-logically)
|
||||
- [Example template header](#example-template-header)
|
||||
- [Variables and PHP logic](#variables-and-php-logic)
|
||||
- [Localized strings](#localized-strings)
|
||||
- [Action and filter hooks](#action-and-filter-hooks)
|
||||
- [Function calls](#function-calls)
|
||||
- [Hook vs override - when to use what](#hook-vs-override---when-to-use-what)
|
||||
- [Overriding templates in plugins](#overriding-templates-in-plugins)
|
||||
- [Templates changes](#templates-changes)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
WooCommerce core contains a series of templates which control the overall layout of WooCommerce store pages. They can be found within the `woocommerce/templates` directory.
|
||||
|
||||
These templates can contain a mixture of:
|
||||
|
||||
- Content/text
|
||||
- Hooks
|
||||
- Conditional logic
|
||||
|
||||
Templates can be overridden by themes, child-themes, and plugins using filters.
|
||||
|
||||
Each template file has a `@version` which reflects the last version of WooCommerce to edit or include this template file. If your overridden version differs, there will be a warning on WooCommerce Status page; template files need to be kept updated as they may include important fixes.
|
||||
|
||||
The following guidelines outline how template files should be written, and what they should include.
|
||||
|
||||
## Use coding standards
|
||||
|
||||
All templates should follow the WordPress Coding Standards for [HTML](https://make.wordpress.org/core/handbook/best-practices/coding-standards/html/) and [PHP](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/).
|
||||
|
||||
## Template structure
|
||||
|
||||
### Structuring templates logically
|
||||
|
||||
Template files should be grouped together into folders to make it easy to tell which template file corresponds to which area of a shop. For example, all of the email templates are grouped together into an "emails" folder and all of the checkout page templates are grouped together into a "checkout" folder.
|
||||
|
||||
Within each template file, there should be a docblock at the top explaining the purpose of the template, where it is rendered, and what WooCommerce version it was last modified in. As a best-practice there should also be a check to make sure `ABSPATH` is defined followed by a call to `exit` if it is not defined.
|
||||
|
||||
After that section the HTML content of the page can be output. We encourage basic elements to be included in the actual template file, vs including all content via hooks. This is so the template file can be easily customized via a template override. If you do only hooks, it's difficult to know where content comes from or how to customize it.
|
||||
|
||||
The exception to this rule is *dynamic content*, or *blocks of content with no logical structure or order*.
|
||||
|
||||
An example of structure within a template file, let's say an orders table, would be:
|
||||
|
||||
- Intro text
|
||||
- Open table element.
|
||||
- Loop
|
||||
- Template include for each row
|
||||
- Close table element.
|
||||
|
||||
Note we would not hook this content in via a filter. Whilst it would allow full customization without a template file, that makes the template file almost impossible for a new user to fathom it's purpose or how to customize elements. Use actions and filters sparingly, only when the content has no logical order or is mostly dynamic.
|
||||
|
||||
### Example template header
|
||||
|
||||
```php
|
||||
<?php
|
||||
/**
|
||||
* Template Name and Description
|
||||
*
|
||||
* This template can be overridden by copying it to yourtheme/woocommerce/myaccount/template-name.php.
|
||||
*
|
||||
* HOWEVER, on occasion WooCommerce will need to update template files and you
|
||||
* (the theme developer) will need to copy the new files to your theme to
|
||||
* maintain compatibility. We try to do this as little as possible, but it does
|
||||
* happen. When this occurs the version of the template file will be bumped and
|
||||
* the readme will list any important changes.
|
||||
*
|
||||
* @see https://docs.woocommerce.com/document/template-structure/
|
||||
* @author Automattic
|
||||
* @package WooCommerce/Templates
|
||||
* @version 3.x.x
|
||||
*/
|
||||
|
||||
if ( ! defined( 'ABSPATH' ) ) {
|
||||
exit;
|
||||
}
|
||||
|
||||
// Add page content here.
|
||||
```
|
||||
|
||||
### Variables and PHP logic
|
||||
|
||||
Where possible, PHP logic should be ran outside of template files and variables passed in. Keeping logic outside of template files lessens the need to update them as often, because code can be changed outside of the file.
|
||||
|
||||
The `wc_get_template` function allows variables to be passed into the template file.
|
||||
|
||||
### Localized strings
|
||||
|
||||
When including strings in template files, ensure they use good grammar, use US English, do not use title-case, and do not contain HTML. If you need to include HTML code in a string, use `sprintf` to insert the content dynamically.
|
||||
|
||||
Strings need to be escaped. See: https://developer.wordpress.org/themes/theme-security/data-sanitization-escaping/#escaping-securing-output.
|
||||
|
||||
Filters should not added around text strings in template files without good reason. In most cases, `gettext` filters which run on all localized strings are adequate for customizations.
|
||||
|
||||
Elements wrapping strings (paragraph tags for instance) should not have unique HTML class names unless the element specifically needs special styling. This is rare.
|
||||
|
||||
### Action and filter hooks
|
||||
|
||||
- When content is dynamic, hooks may be used to insert content, rather than having logic in the template itself.
|
||||
- If making things like lists filterable, filters are preferable over `_start`/`_end` or `_before`/`_after` style hooks.
|
||||
- Hook names should have a `woocommerce_` prefix.
|
||||
- Hook names should be descriptive of the file/content context.
|
||||
- Hook names can include a suffix which indicates placement e.g. `_start` or `_end`.
|
||||
|
||||
Example; placing an action hook before and after a form may use `woocommerce_example_form_start` and `woocommerce_example_form_end`.
|
||||
|
||||
When adding new actions to a template file, document it's usage and what functions are hooked into it so people looking at the template know where content is being injected via. e.g.:
|
||||
|
||||
```php
|
||||
/**
|
||||
* woocommerce_before_shop_loop_item hook.
|
||||
*
|
||||
* @hooked woocommerce_template_loop_product_link_open - 10
|
||||
*/
|
||||
do_action( 'woocommerce_before_shop_loop_item' );
|
||||
```
|
||||
|
||||
### Function calls
|
||||
|
||||
Direct function calls are permitted, but if you have several blocks of content with no logical order, these can be hooked in instead using the above method.
|
||||
|
||||
## Hook vs override - when to use what
|
||||
|
||||
- Whenever possible use the hooks to add or remove content. This method is more robust than overriding the templates. If you have overridden a template, you have to update the template any time the file changes. If you are using the hooks, you will only have to update if the hooks change, which happens much less frequently.
|
||||
- If some structural change in HTML is necessary you should override a template.
|
||||
- Do not delete any of WooCommerce hooks when overriding a template. This would prevent plugins hooking in to add content.
|
||||
|
||||
## Overriding templates in plugins
|
||||
|
||||
Plugins can hook into `woocommerce_locate_template` in order to create a alternative templates directory within the plugin.
|
||||
|
||||
See the example code below that allows to override WooCommerce templates using a directory called `templates` inside a plugin:
|
||||
|
||||
```php
|
||||
/**
|
||||
* Get current plugin path.
|
||||
*
|
||||
* @return string
|
||||
*/
|
||||
function myplugin_get_plugin_path() {
|
||||
// Gets the absolute path to this plugin directory.
|
||||
return untrailingslashit( plugin_dir_path( __FILE__ ) );
|
||||
}
|
||||
|
||||
add_filter( 'woocommerce_locate_template', 'myplugin_woocommerce_locate_template', 10, 3 );
|
||||
|
||||
/**
|
||||
* Custom `/templates/` directory inside a plugin.
|
||||
*
|
||||
* @param string $template Full template path
|
||||
* @param string $template_name Template name
|
||||
* @param string $templates_directory Templates directory.
|
||||
* @return string
|
||||
*/
|
||||
function myplugin_woocommerce_locate_template( $template, $template_name, $templates_directory ) {
|
||||
$original_template = $template;
|
||||
|
||||
if ( ! $templates_directory ) {
|
||||
$templates_directory = WC()->template_url;
|
||||
}
|
||||
|
||||
// Plugin's custom templates/ directory
|
||||
$plugin_path = myplugin_get_plugin_path() . '/templates/';
|
||||
|
||||
// Look within passed path within the theme - this is priority.
|
||||
$template = locate_template(
|
||||
array(
|
||||
$templates_directory . $template_name,
|
||||
$template_name,
|
||||
)
|
||||
);
|
||||
|
||||
// Get the template from this plugin under /templates/ directory, if it exists.
|
||||
if ( ! $template && file_exists( $plugin_path . $template_name ) ) {
|
||||
$template = $plugin_path . $template_name;
|
||||
}
|
||||
|
||||
// Use default template if not found a suitable template under plugin's /templates/ directory.
|
||||
if ( ! $template ) {
|
||||
$template = $original_template;
|
||||
}
|
||||
|
||||
// Return what we found.
|
||||
return $template;
|
||||
}
|
||||
```
|
||||
|
||||
## Templates changes
|
||||
|
||||
We recommend using hooks, rather than overriding templates, because it means you don't need to update template files as often. We are doing big changes in major releases only so your code will be more reliable.
|
||||
|
||||
We reserve the right to deprecate templates, but when we do this the template should stay on WooCommerce core for a period of time before it gets removed. For example, we did this when we created the new "My Account" dashboard.
|
||||
|
||||
Excluding major changes and deprecated templates, we only do small fixes in minor or patch releases, and these types of changes should not cause issues for those of you who have already overridden any of our templates.
|
||||
|
|
@ -3,6 +3,7 @@
|
|||
## Table of Contents
|
||||
|
||||
- [Virtual orders do not have shipping addresses](#virtual-orders-do-not-have-shipping-addresses)
|
||||
- [Accessing `$item['item_meta']` directly](#accessing-itemitem_meta-directly)
|
||||
- [`get_qty_refunded_for_item` handling](#get_qty_refunded_for_item-handling)
|
||||
- [set_payment_method does not update meta values](#set_payment_method-does-not-update-meta-values)
|
||||
- [Data filters differ when extending classes with a different object type](#data-filters-differ-when-extending-classes-with-a-different-object-type)
|
||||
|
|
|
|||
|
|
@ -1,31 +0,0 @@
|
|||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
## Table of Contents
|
||||
|
||||
- [Disabling gallery features](#disabling-gallery-features)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
The new gallery introduced in 3.0.0 ([read here for more information](https://woocommerce.wordpress.com/2016/10/19/new-product-gallery-merged-in-to-core-for-2-7/)) uses Flexslider, Photoswipe, and the jQuery Zoom plugin to offer swiping, lightboxes and other neat features.
|
||||
|
||||
This new gallery is off by default for custom and 3rd party themes since it's common to disable the WooCommerce gallery and replace with your own. To enable the gallery, you can declare support like this
|
||||
|
||||
```
|
||||
add_theme_support( 'wc-product-gallery-zoom' );
|
||||
add_theme_support( 'wc-product-gallery-lightbox' );
|
||||
add_theme_support( 'wc-product-gallery-slider' );
|
||||
```
|
||||
|
||||
You do not have to support all 3; you can pick and choose. If a feature is not supported, the scripts will not be loaded and the gallery code will not execute on product pages.
|
||||
|
||||
## Disabling gallery features
|
||||
|
||||
Similarly, if gallery features are enabled, you can disable them with `remove_theme_support`:
|
||||
|
||||
```
|
||||
remove_theme_support( 'wc-product-gallery-zoom' );
|
||||
remove_theme_support( 'wc-product-gallery-lightbox' );
|
||||
remove_theme_support( 'wc-product-gallery-slider' );
|
||||
```
|
||||
|
||||
You can disable any parts; you do not need to disable all features.
|
||||
|
|
@ -1,3 +1,18 @@
|
|||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
## Table of Contents
|
||||
|
||||
- [Description](#description)
|
||||
- [Usage](#usage)
|
||||
- [WC_Product_Query Methods](#wc_product_query-methods)
|
||||
- [Parameters](#parameters)
|
||||
- [General](#general)
|
||||
- [Product](#product)
|
||||
- [Date](#date)
|
||||
- [Adding Custom Parameter Support](#adding-custom-parameter-support)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## Description
|
||||
|
||||
`wc_get_products` and `WC_Product_Query` provide a standard way of retrieving products that is safe to use and will not break due to database changes in future WooCommerce versions. Building custom WP_Queries or database queries is likely to break your code in future versions of WooCommerce as data moves towards custom tables for better performance. This is the best-practices way for plugin and theme developers to retrieve multiple products. `wc_get_products` and `WC_Product_Query` are similar to WordPress [`get_posts` and `WP_Query`](https://codex.wordpress.org/Class_Reference/WP_Query). Just like those, you pass in an array of arguments defining the criteria for the search.
|
||||
|
|
|
|||
Loading…
Reference in New Issue