Merge pull request #49 from humanmade/backport-48-to-v7-branch

[Backport v7-branch] Documentation corrections

docs/consent/README.md

@@ -12,13 +12,13 @@ To keep up with the GDPR regulations and your company's privacy and cookie polic
 
 ## How does it work?
 
-Altis Consent is an API that is designed to handle how cookies and other types of data stored locally on a user's computer are registered in the code. By creating a registry of cookies and local storage, and defining what those cookies are used for, the API allows the software to intelligently use only those cookies that a user has granted access to.
-
-In order for this to work, all cookies and local storage used on a site must be registered in the way mentioned in the Altis developer documentation.
+Altis Consent is an API that is designed to help you manage when to load scripts that set cookies and other types of data stored locally on a user's computer. It allows you to subscribe to changes in a user's consent and use those events to trigger Google Tag Manager tags, or to lazily load other JavaScript that sets cookies.
 
 ## What does it do?
 
-Out of the box, the Consent API supports [Altis Analytics](docs://analytics/native/README.md) and [Google Tag Manager](docs://analytics/google-tag-manager/README.md). Using the controls provided on the Privacy page in the WP admin you can link your website's Privacy Policy and Cookie storage Policy page. There are options to control whether to grant the user a choice to select the types of cookies they want to consent to, or an option to allow all cookies or only functional cookies. You may also easily add a cookie consent banner message in the admin settings.
+Out of the box, the Consent API supports [Altis Analytics](docs://analytics/native/README.md) and [Google Tag Manager](docs://analytics/google-tag-manager/README.md). Using the controls provided on the Privacy page in the WP admin you can link your website's Privacy Policy and Cookie storage Policy page.
+
+There are options to control whether to grant the user a choice to select the types of cookies they want to consent to, or an option to allow all cookies or only functional cookies. You may also easily add a cookie consent banner message in the admin settings.
 
 In addition, a robust templating system and dozens of filters allow development teams to fully customize the options or the display of the banner, or only customize certain specific elements, based on a site's needs.
 
@@ -29,7 +29,11 @@ The API allows management of third party cookies if it is configured so. See the
 Altis' personalization features track user data using first-party cookies and are supported by default.
 
 ## Does the API help categorize the type of cookies?
-Out of the box, [five categories](./Consent-API.md#consent-categories) are provided: functional, marketing, statistics, statistics-anonymous and preferences. More categories can be [added via a filter](./Filter-Reference.md#altisconsentcategories).
+Altis does not do any automatic categorisation of your cookies. It provides the means for users to control their consent and for you to respond to changes in that consent. Determining which scripts fall into which category needs to be manually determined and can vary by geographical location.
+
+Out of the box, [five categories](./consent-api.md#consent-categories) are provided: `functional`, `marketing`, `statistics`, `statistics-anonymous` and `preferences`. More categories can be [added via a filter](./filter-reference.md#altisconsentcategories).
+
+**Note:** `functional` and `statistics-anonymous` categories are always allowed by default. This can be modified using the [`altis.consent.always_allow_categories` filter](./filter-reference.md#altisconsentalways_allow_categories).
 
 ## Configuration
 Altis Consent is active by default. However, if your project is already using an alternative consent system and you would like to disable Altis Consent, this can be done in the project's `composer.json` file:
@@ -48,4 +52,4 @@ Altis Consent is active by default. However, if your project is already using an
 }
 ```
 
-Alternatively, you can use the [`altis.consent.should_display_banner`](./Filter-Reference.md#altisconsentshould_display_banner) filter or the [admin "Display Cookie Consent Banner" setting](./Privacy-Settings-page.md#Dispay-Cookie-Consent-Banner) to disable the banner. Note that neither of these two options will completely disable the Consent API itself, and all associated JavaScript will still load on the page.
+Alternatively, you can use the [`altis.consent.should_display_banner`](./filter-reference.md#altisconsentshould_display_banner) filter or the [admin "Display Cookie Consent Banner" setting](./privacy-settings-page.md#Dispay-Cookie-Consent-Banner) to disable the banner. Note that neither of these two options will completely disable the Consent API itself, and all associated JavaScript will still load on the page.

docs/consent/Consent-API.md → docs/consent/consent-api.md

@@ -6,7 +6,15 @@ The Consent API is a developer API to read and register consent categories, to a
 
 The Consent API adds two new concepts: a `consent_type` and a consent `category`. Categories are used to group user data by its intended usage, e.g. `marketing`. `consent_type` defines whether consent is `optin`, `optout` or some other type defined in the code.
 
-The default consent type can be set in the code. The Altis Consent module defaults the consent type to `optin`. This means that user data stored locally will only be used if a user explicitly _allows_ access. If the default `consent_type` is set to `optout`, user data will be assumed to be okay to use unless a user explicitly _disallows_ access.
+The default consent type can be set in the code. The Altis Consent module defaults the consent type to `optin`, except for the `functional` and `statistics-anonymous` categories. This tells you that user data stored locally should only be used if a user explicitly _allows_ access. If the default `consent_type` is set to `optout`, user data will be assumed to be okay to use unless a user explicitly _disallows_ access.
+
+The default categories `functional` and `statistics-anonymous` that are allowed by default can be modified using the `altis.consent.always_allow_categories` filter. The example below will make only the `functional` category allowed by default:
+
+```php
+add_filter( 'altis.consent.always_allow_categories', function () {
+    return [ 'functional' ];
+} );
+```
 
 Other consent types can be defined within the code.
 

docs/consent/Filter-Reference.md → docs/consent/filter-reference.md

@@ -1,16 +1,15 @@
 # Filter Reference
+## `altis.consent.always_allow_categories`
 
-## `altis.consent.allowlisted_categories`
-
-An array of always allowed consent categories.
+An array of always allowed consent categories. Defaults to "functional" and "statistics-anonymous".
 
 ### Parameters
 
 **`$allowlisted_categories`** _(array)_ An array of default categories to consent to automatically.
 
 ### Source
 
-File: [`inc/namespace.php`](https://github.com/humanmade/altis-consent/blob/master/inc/namespace.php)  
+File: [`inc/namespace.php`](https://github.com/humanmade/altis-consent/blob/master/inc/namespace.php)
 
 ## `altis.consent.consent_settings_fields`
 
@@ -73,7 +72,7 @@ The Altis Privacy page saved options. If you create new options for the Privacy
 
 ### Parameters
 
-**`$validated`** _(array)_ An array of validated data.  
+**`$validated`** _(array)_ An array of validated data.
 
 **`$dirty`** _(array)_ An array of unvalidated data.
 
@@ -83,7 +82,7 @@ File: [`inc/settings.php`](https://github.com/humanmade/altis-consent/blob/maste
 
 ## `altis.consent.default_banner_message`
 
-The default cookie consent banner message. This is the text that appears in the WordPress WYSIWYG editor on the Altis Privacy page by default, before it's been saved. 
+The default cookie consent banner message. This is the text that appears in the WordPress WYSIWYG editor on the Altis Privacy page by default, before it's been saved.
 
 ### Parameters
 

docs/consent/Function-Reference.md → docs/consent/function-reference.md

@@ -1,13 +1,13 @@
 # PHP Function Reference
 
-**Note:** All the functions in the Altis Consent plugin use the `Altis\Consent` namespace except where noted.
+**Note:** All functions are in the Altis Consent plugin use the `Altis\Consent` namespace except where noted.
 
 ## `load_consent_banner`
 
-Loads the templates used to display the cookie consent banner. The path to the banner can be customized using the [`altis.consent.consent_banner_path`](/Filter-Reference#altisconsentconsent_banner_path) filter.
+Loads the templates used to display the cookie consent banner. The path to the banner can be customized using the [`altis.consent.consent_banner_path`](./filter-reference.md#altisconsentconsent_banner_path) filter.
 
 * Uses [`load_template`](https://developer.wordpress.org/reference/functions/load_template/)
-* See [`altis.consent.consent_banner_path`](/Filter-Reference#altisconsentconsent_banner_path)
+* See [`altis.consent.consent_banner_path`](./filter-reference.md#altisconsentconsent_banner_path)
 
 ### Example
 ```php
@@ -20,10 +20,10 @@ function render_consent_banner() : string {
 
 ## `should_display_banner`
 
-Determines whether the banner should be displayed. Uses the `display_banner` setting defined in the admin but can be filtered by using the [`altis.consent.should_display_banner`](/Filter-Reference#altisconsentshould_display_banner) filter.
+Determines whether the banner should be displayed. Uses the `display_banner` setting defined in the admin but can be filtered by using the [`altis.consent.should_display_banner`](./filter-reference.md#altisconsentshould_display_banner) filter.
 
 * Uses [`Settings\get_consent_option`](#settingsget_consent_option)
-* See [`altis.consent.should_display_banner`](/Filter-Reference#altisconsentshould_display_banner)
+* See [`altis.consent.should_display_banner`](./filter-reference.md#altisconsentshould_display_banner)
 
 ### Return
 
@@ -43,7 +43,7 @@ function load_consent_banner() {
 
 Returns the default consent cookie prefix.
 
-* See [`altis.consent.cookie_prefix`](/Filter-Reference#altisconsentcookie_prefix)
+* See [`altis.consent.cookie_prefix`](./filter-reference.md#altisconsentcookie_prefix)
 
 ### Return
 
@@ -60,7 +60,7 @@ wp_localize_script( 'altis-consent', 'altisConsent', [
 
 Returns the active consent types.
 
-* See [`altis.consent.types`](/Filter-Reference#altisconsenttypes)
+* See [`altis.consent.types`](./filter-reference.md#altisconsenttypes)
 
 ### Return
 
@@ -77,7 +77,7 @@ wp_localize_script( 'altis-consent', 'altisConsent', [
 
 Returns a list of active consent categories.
 
-* See [`altis.consent.categories`](/Filter-Reference#altisconsentcategories)
+* See [`altis.consent.categories`](./filter-reference.md#altisconsentcategories)
 
 ### Return
 
@@ -94,7 +94,7 @@ wp_localize_script( 'altis-consent', 'altisConsent', [
 
 Returns a list of active possible consent values.
 
-* See [`altis.consent.values`](/Filter-Reference#altisconsentvalues)
+* See [`altis.consent.values`](./filter-reference.md#altisconsentvalues)
 
 ### Return
 
@@ -129,7 +129,7 @@ if ( ! Consent\validate_consent_item( $category, 'category' ) ) {
 
 ## `get_cookie_policy_url`
 
-Retrieves the URL to the cookie policy page. Can be filtered by the [`altis.consent.cookie_policy_url`](/Filter-Reference#altisconsentcookie_policy_url) filter.
+Retrieves the URL to the cookie policy page. Can be filtered by the [`altis.consent.cookie_policy_url`](./filter-reference.md#altisconsentcookie_policy_url) filter.
 
 * Uses [`Settings\get_consent_option`](#settingsget_consent_option)
 * Uses [`get_post_type`](http://developer.wordpress.org/reference/functions/get_post_type/)
@@ -175,7 +175,7 @@ $cookie_expiration = Altis\Consent\Settings\get_consent_option( 'cookie_expirati
 
 **Note:** Defined in the `Altis\Consent\Settings` namespace.
 
-Gets the default banner message. Filterable with the [`altis.consent.default_banner_message`](/Filter-Reference#altisconsentdefault_banner_message) filter.
+Gets the default banner message. Filterable with the [`altis.consent.default_banner_message`](./filter-reference.md#altisconsentdefault_banner_message) filter.
 
 ### Return
 

docs/consent/google-tag-manager.md

@@ -2,7 +2,7 @@
 
 Support for Google Tag Manager is provided via GTM's data layer variable. When either the page loads or consent is subsequently changed the data layer is updated allowing you to create triggers based on the consent given.
 
-The event name is `altis-consent-changed` and the variable is named `altisConsent`. The variable data is a list of the [consent categories](./Consent-API.md#consent-categories) currently given for example "functional, statistics-anonymous".
+The event name is `altis-consent-changed` and the variable is named `altisConsent`. The variable data is a list of the [consent categories](./consent-api.md#consent-categories) currently given for example "functional, statistics-anonymous".
 
 ## Creating the Variable