From fff711f8927248883acb8f459f7e0810561b66a6 Mon Sep 17 00:00:00 2001 From: Mike Little Date: Wed, 3 Jul 2024 18:34:57 +0100 Subject: [PATCH 1/2] Reformat docs files after linting This changes all the docs files to be formatted correctly after linting. The main changes are line length, spaces instead of tabs, and addition of alt text for images. Resolves link to issue #1280 --- docs/README.md | 12 +- docs/consent/README.md | 82 +++++--- docs/consent/consent-api.md | 30 ++- docs/consent/filter-reference.md | 88 ++++++--- docs/consent/function-reference.md | 84 +++++--- docs/consent/google-tag-manager.md | 67 ++++--- docs/consent/javascript-reference.md | 24 +-- docs/consent/privacy-settings-page.md | 32 +++- docs/consent/template-architecture.md | 54 ++++-- docs/privacy-api/README.md | 264 ++++++++++++++------------ 10 files changed, 458 insertions(+), 279 deletions(-) diff --git a/docs/README.md b/docs/README.md index bd8a2ad..dcdab81 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,13 @@ # Privacy -Altis is committed to prividing frameworks, tooling and, where possible, integrations with other modules and platforms to enable customers to build privacy-first solutions. +Altis is committed to providing frameworks, tooling and, where possible, integrations with other modules and platforms to enable +customers to build privacy-first solutions. -Privacy is a core capabiliity for the modern web and something every customer and project has to deal with. Right now, a diverse array of solutions are available for web applications, and each requires custom integration work to get the most out of them. +Privacy is a core capability for the modern web and something every customer and project has to deal with. Right now, a diverse +array of solutions are available for web applications, and each requires custom integration work to get the most out of them. -Altis provides a consistent method for dealing with acquiring consent, managing user data and documenting privacy measures. In addition, we integrate and provide the controls for managing privacy in Altis' built-in features including analytics, personalization and Google Tag Manager. +Altis provides a consistent method for dealing with acquiring consent, managing user data and documenting privacy measures. In +addition, we integrate and provide the controls for managing privacy in Altis' built-in features including analytics, +personalization and Google Tag Manager. -Privacy is provided within Altis as a first-class component. \ No newline at end of file +Privacy is provided within Altis as a first-class component. diff --git a/docs/consent/README.md b/docs/consent/README.md index 87fd9cb..a72b07b 100644 --- a/docs/consent/README.md +++ b/docs/consent/README.md @@ -1,55 +1,89 @@ # Altis Consent -The Altis Consent API provides a website administrator (you) with a centralized and consistent way of obtaining data privacy consent from your website's visitors. Data privacy consent refers to how user data is tracked, collected, or stored on a website. +The Altis Consent API provides a website administrator (you) with a centralized and consistent way of obtaining data privacy consent +from your website's visitors. Data privacy consent refers to how user data is tracked, collected, or stored on a website. -### Web Cookies -A website uses cookies to track user behaviour on the website. Cookies can be thought of as belonging to one of two broad types: first-party cookies, set by the server or code on the domain itself, and third-party cookies served by scripts included from other domains or services (such as Google Analytics). Depending on their function, these cookies can further be categorized into functional or operational cookies, marketing or personalization cookies, or cookies used for statistical data. While functional cookies are necessary for a smooth user experience, other cookies, such as marketing cookies that track user preferences, are not essential for a website's performance. General Data Protection Regulation (GDPR) governs user data privacy and protection and stipulates that businesses require appropriate consent from website visitors before they are served any such cookies. +## Web Cookies -We created this framework to help you readily obtain consent from your website users for various cookies that will be served on your website. With the features available in the API, a website's visitor will be able to control the _types_ of data or cookies that can be stored and shared if you choose to offer that level of control. +A website uses cookies to track user behaviour on the website. Cookies can be thought of as belonging to one of two broad types: +first-party cookies, set by the server or code on the domain itself, and third-party cookies served by scripts included from other +domains or services (such as Google Analytics). Depending on their function, these cookies can further be categorized into +functional or operational cookies, marketing or personalization cookies, or cookies used for statistical data. While functional +cookies are necessary for a smooth user experience, other cookies, such as marketing cookies that track user preferences, are not +essential for a website's performance. General Data Protection Regulation (GDPR) governs user data privacy and protection and +stipulates that businesses require appropriate consent from website visitors before they are served any such cookies. + +We created this framework to help you readily obtain consent from your website users for various cookies that will be served on your +website. With the features available in the API, a website's visitor will be able to control the _types_ of data or cookies that can +be stored and shared if you choose to offer that level of control. ## Why should I use it? -To keep up with the GDPR regulations and your company's privacy and cookie policies. GDPR regulations mandate that businesses need user consent before they can collect or track any visitor data. This tool helps you create a cookie consent banner out of the box. With the banner options, a user can choose to select the cookies (data) that can be collected by the website. The framework lets you manage first party and third party cookies. + +To keep up with the GDPR regulations and your company's privacy and cookie policies. GDPR regulations mandate that businesses need +user consent before they can collect or track any visitor data. This tool helps you create a cookie consent banner out of the box. +With the banner options, a user can choose to select the cookies (data) that can be collected by the website. The framework lets you +manage first party and third party cookies. ## How does it work? -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. +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. +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. +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. +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. ## What about third-party cookies? -The API allows management of third party cookies if it is configured so. See the [JavaScript Reference](./javascript-reference.md) to see how this can be done. + +The API allows management of third party cookies if it is configured so. See the [JavaScript Reference](./javascript-reference.md) +to see how this can be done. ## Can I manage user data tracked through Altis' personalization features? + Altis' personalization features track user data using first-party cookies and are supported by default. ## Does the API help categorize the type of cookies? -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). +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 geographic 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). +**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: + +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: ```json { - "extra": { - "altis": { - "modules": { - "privacy": { - "consent": false - } - } - } - } + "extra": { + "altis": { + "modules": { + "privacy": { + "consent": false + } + } + } + } } ``` -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. diff --git a/docs/consent/consent-api.md b/docs/consent/consent-api.md index 1bac81e..9193a03 100644 --- a/docs/consent/consent-api.md +++ b/docs/consent/consent-api.md @@ -1,14 +1,21 @@ # Consent API -The Consent API is a developer API to read and register consent categories, to allow consent management and other plugins to work together, improving compliance. +The Consent API is a developer API to read and register consent categories, to allow consent management and other plugins to work +together, improving compliance. ## How does it work? -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 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`, 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 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: +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 () { @@ -28,18 +35,25 @@ Cookies or any other form of local storage that are used exclusively for statist * **statistics-anonymous** -Cookies or any other form of local storage that are used exclusively for anonymous statistical purposes (Anonymous Analytics Cookies), that are placed on a first party domain, and that do not allow identification of particular individuals. +Cookies or any other form of local storage that are used exclusively for anonymous statistical purposes (Anonymous Analytics +Cookies), that are placed on a first party domain, and that do not allow identification of particular individuals. * **marketing** -Cookies or any other form of local storage required to create user profiles to send advertising or to track the user on a website or across websites for similar marketing purposes. +Cookies or any other form of local storage required to create user profiles to send advertising or to track the user on a website or +across websites for similar marketing purposes. * **functional** -Functional cookies or any other form of local storage are any kind of user data that is required for the proper functionality of a site that cannot be disabled without affecting a user's ability to navigate the site. An example is the cookies that WordPress stores to handle user sign-ins for administrators -- if these cookies were blocked, an administrator would not be able to use the site. In these cases, the technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user. +Functional cookies or any other form of local storage are any kind of user data that is required for the proper functionality of a +site that cannot be disabled without affecting a user's ability to navigate the site. An example is the cookies that WordPress +stores to handle user sign-ins for administrators -- if these cookies were blocked, an administrator would not be able to use the +site. In these cases, the technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a +specific service explicitly requested by the subscriber or user. * **preferences** -Cookies or any other form of local storage that can not be seen as statistics, statistics-anonymous, marketing or functional, and where the technical storage or access is necessary for the legitimate purpose of storing preferences. +Cookies or any other form of local storage that can not be seen as statistics, statistics-anonymous, marketing or functional, and +where the technical storage or access is necessary for the legitimate purpose of storing preferences. Additional consent categories can be defined within a site's code. diff --git a/docs/consent/filter-reference.md b/docs/consent/filter-reference.md index 16f0197..b49cd86 100644 --- a/docs/consent/filter-reference.md +++ b/docs/consent/filter-reference.md @@ -1,4 +1,5 @@ # Filter Reference + ## `altis.consent.always_allow_categories` An array of always allowed consent categories. Defaults to "functional" and "statistics-anonymous". @@ -19,13 +20,13 @@ Settings fields that appear on the Altis Privacy page. **`$fields`** _(array)_ An array of settings fields with unique IDs, titles and callback functions in the following format: -``` +```php $fields = [ - [ - 'id' => 'unique_setting_id', - 'title' => __( 'Rendered Setting Label', 'altis-consent' ), - 'callback' => __NAMESPACE__ . '\\setting_callback_function', - ], + [ + 'id' => 'unique_setting_id', + 'title' => __( 'Rendered Setting Label', 'altis-consent' ), + 'callback' => __NAMESPACE__ . '\\setting_callback_function', + ], ]; ``` @@ -41,12 +42,12 @@ The available banner options to display on the options page. **`$options`** _(array)_ An array of cookie banner options in the following format: -``` +```php $options = [ - [ - 'value' => 'none', - 'label' => __( 'Allow/Deny All Cookies', 'altis-consent' ), - ], + [ + 'value' => 'none', + 'label' => __( 'Allow/Deny All Cookies', 'altis-consent' ), + ], ]; ``` @@ -56,7 +57,9 @@ File: [`inc/settings.php`](https://github.com/humanmade/altis-consent/blob/maste ## `altis.consent.privacy_policy_message` -The actual text that displays above the Privacy Policy Page setting on the Privacy page. This language can be altered or removed entirely using this filter. The original text that displays duplicates the text that existed on the original WordPress core Privacy page. +The actual text that displays above the Privacy Policy Page setting on the Privacy page. This language can be altered or removed +entirely using this filter. The original text that displays duplicates the text that existed on the original WordPress core Privacy +page. ### Parameters @@ -68,13 +71,14 @@ File: [`inc/settings.php`](https://github.com/humanmade/altis-consent/blob/maste ## `altis.consent.validate_privacy_options` -The Altis Privacy page saved options. If you create new options for the Privacy page, you must use this filter to add and validate that new option data. +The Altis Privacy page saved options. If you create new options for the Privacy page, you must use this filter to add and validate +that new option data. ### Parameters **`$validated`** _(array)_ An array of validated data. -**`$dirty`** _(array)_ An array of unvalidated data. +**`$dirty`** _(array)_ An array of data not yet validated. ### Source @@ -82,7 +86,8 @@ 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 @@ -94,9 +99,12 @@ File: [`inc/settings.php`](https://github.com/humanmade/altis-consent/blob/maste ## `altis.consent.allowed_policy_page_values` -An array of allowed policy pages we can create. Used by [`render_secondary_button function`](). The default pages that can be created are `privacy_policy` and `cookie_policy`. +An array of allowed policy pages we can create. Used +by [`render_secondary_button function`](./function-reference.md#settingsrender_secondary_button). The +default pages that can be created are `privacy_policy` and `cookie_policy`. -If new policy pages should be created on a settings page using `render_secondary_button`, this filter must be used to allow those pages. +If new policy pages should be created on a settings page using `render_secondary_button`, this filter must be used to allow those +pages. ### Parameters @@ -122,7 +130,8 @@ File: [`inc/settings.php`](https://github.com/humanmade/altis-consent/blob/maste ## `altis.consent.consent_banner_path` -The path to the consent banner template. Within the Altis Consent module, this template loads all the other templates. Overriding this setting allows you to create your own custom banner templates +The path to the consent banner template. Within the Altis Consent module, this template loads all the other templates. Overriding +this setting allows you to create your own custom banner templates ### Parameters @@ -133,6 +142,7 @@ The path to the consent banner template. Within the Altis Consent module, this t File: [`inc/functions.php`](https://github.com/humanmade/altis-consent/blob/master/inc/functions.php) ### Example + ```php // Override the default consent banner templates. add_filter( 'altis.consent.consent_banner_path', __DIR__ . '/path/to/your/template.php' ); @@ -140,7 +150,8 @@ add_filter( 'altis.consent.consent_banner_path', __DIR__ . '/path/to/your/templa ## `altis.consent.should_display_banner` -Whether to display the banner. This filter defaults to the value of the `display_banner` setting, or `false` if that's not set. Using this filter allows you to hijack the display of the banner based on external logic. +Whether to display the banner. This filter defaults to the value of the `display_banner` setting, or `false` if that's not set. +Using this filter allows you to hijack the display of the banner based on external logic. ### Parameters @@ -151,6 +162,7 @@ Whether to display the banner. This filter defaults to the value of the `display File: [`inc/functions.php`](https://github.com/humanmade/altis-consent/blob/master/inc/functions.php) ### Example + ```php add_filter( 'altis.consent.should_display_banner', function ( bool $display_banner ) : bool { // Don't display if the page ID is 10. @@ -179,6 +191,7 @@ The consent cookie prefix. **`$cookie_prefix`** _(string)_ The consent cookie prefix. Default is `altis_consent`. ### Example + ```php add_filter( 'altis.consent.cookie_prefix', function() { return 'some_other_prefix'; @@ -194,6 +207,7 @@ The allowed consent types. **`$types`** _(array)_ The list of consent types. Defaults are `optin` and `optout`. ### Example + ```php add_filter( 'altis.consent.types', function( $types ) { $types[] = 'none'; @@ -207,9 +221,11 @@ The allowed consent categories. ### Parameters -**`$categories`** _(array)_ The list of consent categories. Defaults are `functional`, `preferences`, `statistics`, `statistics-anonymous`, `marketing`. +**`$categories`** _(array)_ The list of consent categories. Defaults +are `functional`, `preferences`, `statistics`, `statistics-anonymous`, `marketing`. ### Example + ```php add_filter( 'altis.consent.categories', function( $categories ) { $categories[] = 'personalization'; @@ -223,9 +239,11 @@ The consent categories with labels for end user display. ### Parameters -**`$categories`** _(array)_ The list of consent categories with labels. Defaults are "Functional", "Preferences", "Statistics", "Anonymous statistics" and "Marketing". +**`$categories`** _(array)_ The list of consent categories with labels. Defaults are "Functional", "Preferences", "Statistics", " +Anonymous statistics" and "Marketing". ### Example + ```php // Changing the 'preferences' category label to 'Settings'. add_filter( 'altis.consent.category_labels', function( $categories ) { @@ -243,6 +261,7 @@ The possible consent values. **`$values`** _(array)_ The list of consent values. Defaults are `allow`, `deny`. ### Example + ```php add_filter( 'altis.consent.values', function( $values ) { $values[] = 'other'; @@ -292,7 +311,8 @@ File: [`tmpl/consent-banner.php`](https://github.com/humanmade/altis-consent/blo ## `altis.consent.no_option_saved_message` -The message that displays in the `consent-banner.php` template if no consent options have been saved in the admin. This message can potentially be overridden if using your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)). +The message that displays in the `consent-banner.php` template if no consent options have been saved in the admin. This message can +potentially be overridden if using your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)). ### Parameters @@ -328,7 +348,8 @@ File: [`tmpl/consent-banner.php`](https://github.com/humanmade/altis-consent/blo ## `altis.consent.preferences_updated_message` -The message that displays when a user saves their cookie consent preference. This message can potentially be overridden if using your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)). +The message that displays when a user saves their cookie consent preference. This message can potentially be overridden if using +your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)). ### Parameters @@ -340,7 +361,9 @@ File: [`tmpl/consent-updated.php`](https://github.com/humanmade/altis-consent/bl ## `altis.consent.apply_cookie_preferences_button_text` -The button text for the Apply Changes button, when cookie category preferences are displayed. This message can potentially be overridden if using your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)) or if categories are not displayed as part of the cookie consent banner. +The button text for the Apply Changes button, when cookie category preferences are displayed. This message can potentially be +overridden if using your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)) or if +categories are not displayed as part of the cookie consent banner. ### Parameters @@ -352,7 +375,8 @@ File: [`tmpl/cookie-preferences.php`](https://github.com/humanmade/altis-consent ## `altis.consent.cookie_consent_policy_link_text` -The hyperlinked message that links to the Cookie Policy page. Defaults to "Read our cookie policy". This message can potentially be overridden if using your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)). +The hyperlinked message that links to the Cookie Policy page. Defaults to "Read our cookie policy". This message can potentially be +overridden if using your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)). ### Parameters @@ -364,7 +388,8 @@ File: [`tmpl/cookie-consent-policy.php`](https://github.com/humanmade/altis-cons ## `altis.consent.cookie_consent_policy_template_path` -The path to the cookie consent policy template. This template displays the link to the cookie policy page if a cookie policy page has been set in the Altis Privacy options. +The path to the cookie consent policy template. This template displays the link to the cookie policy page if a cookie policy page +has been set in the Altis Privacy options. ### Parameters @@ -376,7 +401,8 @@ File: [`tmpl/button-row.php`](https://github.com/humanmade/altis-consent/blob/ma ## `altis.consent.accept_all_cookies_button_text` -The text to display in the "accept all cookies" button. This message can potentially be overridden if using your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)). +The text to display in the "accept all cookies" button. This message can potentially be overridden if using your own templates ( +see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)). ### Parameters @@ -388,7 +414,8 @@ File: [`tmpl/button-row.php`](https://github.com/humanmade/altis-consent/blob/ma ## `altis.consent.accept_only_functional_cookies_button_text` -The text to display in the "accept only functional cookies" button. This message can potentially be overridden if using your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)). +The text to display in the "accept only functional cookies" button. This message can potentially be overridden if using your own +templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)). ### Parameters @@ -400,7 +427,8 @@ File: [`tmpl/button-row.php`](https://github.com/humanmade/altis-consent/blob/ma ## `altis.consent.cookie_preferences_button_text` -The text to display in the "cookie preferences" button. This message can potentially be overridden if using your own templates (see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)) or if cookie consent categories are not displayed. +The text to display in the "cookie preferences" button. This message can potentially be overridden if using your own templates ( +see [`altis.consent.consent_banner_path`](#altisconsentconsent_banner_path)) or if cookie consent categories are not displayed. ### Parameters @@ -409,3 +437,5 @@ The text to display in the "cookie preferences" button. This message can potenti ### Source File: [`tmpl/button-row.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/button-row.php) + + diff --git a/docs/consent/function-reference.md b/docs/consent/function-reference.md index c733e99..268c4ac 100644 --- a/docs/consent/function-reference.md +++ b/docs/consent/function-reference.md @@ -4,12 +4,14 @@ ## `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.md#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.md#altisconsentconsent_banner_path) ### Example + ```php function render_consent_banner() : string { ob_start(); @@ -20,16 +22,18 @@ 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.md#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.md#altisconsentshould_display_banner) ### Return -_(bool)_ Whether the banner should be displayed. +`bool`: Whether the banner should be displayed. ### Example + ```php function load_consent_banner() { // Check if we need to load the banner. @@ -47,9 +51,10 @@ Returns the default consent cookie prefix. ### Return -_(string)_ The consent cookie prefix. Defaults to `altis_consent`. +`string`: The consent cookie prefix. Defaults to `altis_consent`. ### Example + ```php wp_localize_script( 'altis-consent', 'altisConsent', [ 'cookiePrefix' => cookie_prefix(), @@ -64,9 +69,10 @@ Returns the active consent types. ### Return -_(array)_ The list of currently allowed consent types. Defaults are `optin` and `optout`. +`array`: The list of currently allowed consent types. Defaults are `optin` and `optout`. ### Example + ```php wp_localize_script( 'altis-consent', 'altisConsent', [ 'consentTypes' => consent_types(), @@ -81,9 +87,11 @@ Returns a list of active consent categories. ### Return -_(array)_ The list of currently allowed consent categories. Defaults are `functional`, `preferences`, `statistics`, `statistics-anonymous`, and `marketing`. +`array`: The list of currently allowed consent categories. Defaults +are `functional`, `preferences`, `statistics`, `statistics-anonymous`, and `marketing`. ### Example + ```php wp_localize_script( 'altis-consent', 'altisConsent', [ 'categories' => consent_categories(), @@ -98,9 +106,11 @@ Returns a list of consent categories with labels. ### Return -_(array)_ The list of currently allowed consent categories. Defaults are "Functional", "Preferences", "Statistics", "Anonymous statistics" and "Marketing". +`array`: The list of currently allowed consent categories. Defaults are "Functional", "Preferences", "Statistics", "Anonymous +statistics" and "Marketing". ### Example + ```php wp_localize_script( 'altis-consent', 'altisConsent', [ 'labels' => consent_category_labels(), @@ -113,12 +123,14 @@ Returns the label for a given consent category. ### Parameters -**`$category`** _(string)_ The category to get the label for. +* **`$category`** `string` The category to get the label for. + ### Return -_(string)_ The label or an empty string if the `$category` is unknown. +`string`: The label or an empty string if the `$category` is unknown. ### Example + ```php echo esc_html( Consent\get_category_label( 'preferences' ) ); ``` @@ -131,9 +143,10 @@ Returns a list of active possible consent values. ### Return -_(array)_ A list of possible consent values. Defaults are `allow` and `deny`. +`array`: A list of possible consent values. Defaults are `allow` and `deny`. ### Example + ```php wp_localize_script( 'altis-consent', 'altisConsent', [ 'values' => consent_values(), @@ -146,23 +159,28 @@ Validates a consent item (either a consent _type_, _category_ or _value_). ### Parameters -**`$item`** _(string)_ The value to validate. -**`$item_type`** _(string)_ The type of value to validate. Possible options are `types` (consent types, see [`consent_types`](#consent_types)), `categories` (consent categories, see [`consent_categories`](#consent_categories)), or `values` (consent values, see [`consent_values`](#consent_values)). +* **`$item`** `string` The value to validate. +* **`$item_type`** `string` The type of value to validate. Possible options are `types` (consent types, +see [`consent_types`](#consent_types)), `categories` (consent categories, see [`consent_categories`](#consent_categories)), +or `values` (consent values, see [`consent_values`](#consent_values)). ### Return -_(string|bool)_ The validated string or `false` if unable to validate. Triggers a warning if either the `$item_type` or the `$item` is invalid. +`string`|`bool`: The validated string or `false` if unable to validate. Triggers a warning if either the `$item_type` or the `$item` +is invalid. ### Example + ```php if ( ! Consent\validate_consent_item( $category, 'category' ) ) { - // Do something. + // Do something. } ``` ## `get_cookie_policy_url` -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. +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/) @@ -170,13 +188,14 @@ Retrieves the URL to the cookie policy page. Can be filtered by the [`altis.cons ### Return -_(string)_ The cookie policy page URL. +`string`: The cookie policy page URL. ### Example + ```php
- +
``` @@ -191,15 +210,17 @@ Get a specific consent option, if one exists. If no parameters are passed, retur ### Parameters -**`$option`** _(mixed)_ (Optional) A consent option name. The option must exist in the `cookie_consent_options` group. Default is an empty string. If no value is passed, all the saved `cookie_consent_options` option values will be returned. - -**`$default`** _(mixed)_ (Optional) A default value to return if no option for that value has been set. Default is an empty string. Requires an `$option` parameter to be passed. +* **`$option`** `mixed` (Optional) A consent option name. The option must exist in the `cookie_consent_options` group. Default +is an empty string. If no value is passed, all the saved `cookie_consent_options` option values will be returned. +* **`$default`** `mixed` (Optional) A default value to return if no option for that value has been set. Default is an empty string. +Requires an `$option` parameter to be passed. ### Return -_(mixed)_ The value for the requested option, or an array of all `cookie_consent_options` if nothing was passed. +`mixed`: The value for the requested option, or an array of all `cookie_consent_options` if nothing was passed. ### Example + ```php $cookie_expiration = Altis\Consent\Settings\get_consent_option( 'cookie_expiration', 30 ); ``` @@ -208,13 +229,15 @@ $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.md#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 -_(string)_ The default cookie consent banner message. +`string`: The default cookie consent banner message. ### Example + ```php use Altis\Consent\Settings; @@ -233,13 +256,16 @@ Used to create the Create Policy Page buttons, but can be filtered and used for ### Parameters -**`$button_text`** _(string)_ The text to display in the button. - -**`$value`** _(string)_ The button value. On the settings page, this is used to determine the type of policy page the buttons create. - -**`$type`** _(string)_ The html button type. The default value is `'submit'`, and valid values are `'submit'`, `'reset'`, and `'button'`. Invalid values revert to `'submit'`. +* **`$button_text`** `string` The text to display in the button. +* **`$value`** `string` The button value. On the settings page, this is used to determine the type of policy page the buttons +create. +* **`$type`** `string` The HTML button type. The default value is `'submit'`, and valid values are `'submit'`, `'reset'`, +and `'button'`. Invalid values revert to `'submit'`. ### Example + ```php -Settings\render_secondary_button( __( 'Create Cookie Policy Page', 'altis-consent' ), 'cookie_policy' ); +Settings\render_secondary_button( _```'Create Cookie Policy Page', 'altis-consent' ), 'cookie_policy' ); ``` + + diff --git a/docs/consent/google-tag-manager.md b/docs/consent/google-tag-manager.md index ed02ffc..9419ff2 100644 --- a/docs/consent/google-tag-manager.md +++ b/docs/consent/google-tag-manager.md @@ -1,8 +1,9 @@ # Google Tag Manager Consent Integration -Support for Google Tag Manager (GTM) can be added via GTM's data layer variable. +Support for Google Tag Manager (GTM) can be added via the data layer variable. -You will need to add the following PHP file to your application somewhere and load it. It can be a `mu-plugin`, or part of a theme for example. +You will need to add the following PHP file to your application somewhere and load it. It can be a `mu-plugin`, or part of a theme +for example. ```php diff --git a/docs/consent/privacy-settings-page.md b/docs/consent/privacy-settings-page.md index 2182a3b..1222f19 100644 --- a/docs/consent/privacy-settings-page.md +++ b/docs/consent/privacy-settings-page.md @@ -1,43 +1,57 @@ # Privacy Settings Page -Out of the box, Altis Consent provides a robust and configurable Privacy Settings page. This page allows you to define policy pages for cookies and privacy, data retention length and the level of user preferences to display, as well as configure the precise wording of your cookie consent banner. +Out of the box, Altis Consent provides a robust and configurable Privacy Settings page. This page allows you to define policy pages +for cookies and privacy, data retention length and the level of user preferences to display, as well as configure the precise +wording of your cookie consent banner. ![Privacy Settings page](https://raw.githubusercontent.com/wiki/humanmade/altis-consent/images/Altis_Consent_Privacy_Settings.png) ## Privacy Policy Page -The first section focuses on the Privacy Policy page itself. The text above explains why setting a Privacy Policy page is important. The precise wording of this information can be altered by a development team. Once a Privacy Policy page is created and set, it can be linked to in menus on the site. +The first section focuses on the Privacy Policy page itself. The text above explains why setting a Privacy Policy page is important. +The precise wording of this information can be altered by a development team. Once a Privacy Policy page is created and set, it can +be linked to in menus on the site. ![Privacy Policy page setting](https://raw.githubusercontent.com/wiki/humanmade/altis-consent/images/Altis_Consent_Privacy_Policy.png) ## Display Cookie Consent Banner -The next several controls cover data retention and cookie consent. The first one simply determines whether or not to display a consent banner on the site. This is a global control, but it can be configured in the code if there are specific pages that should or should not display the banner. By default, selecting the "Display Consent Banner" option will display the banner on all pages until consent has been given. If you do not want or need to display a consent banner on your site, this can be set to "Do not display banner" and the other controls around cookie consent on this page can be disregarded. +The next several controls cover data retention and cookie consent. The first one simply determines whether or not to display a +consent banner on the site. This is a global control, but it can be configured in the code if there are specific pages that should +or should not display the banner. By default, selecting the "Display Consent Banner" option will display the banner on all pages +until consent has been given. If you do not want or need to display a consent banner on your site, this can be set to "Do not +display banner" and the other controls around cookie consent on this page can be disregarded. ![Display Consent Banner setting](https://raw.githubusercontent.com/wiki/humanmade/altis-consent/images/Altis_Consent_Display_Cookie_Consent_Banner.png) ## Cookie Expiration -The cookie expiration setting controls how long cookie and local storage data is stored. The default is 30 days. After that period of time, the cookies/local storage will expire and the user will be prompted again to consent to sharing that data. All cookie data registered through the Altis Consent module expires at the same time, to ensure consistency, allow the length of time to be controlled universally in the admin, and prevent any user data from being used after the consent cookie has expired. +The cookie expiration setting controls how long cookie and local storage data is stored. The default is 30 days. After that period +of time, the cookies/local storage will expire and the user will be prompted again to consent to sharing that data. All cookie data +registered through the Altis Consent module expires at the same time, to ensure consistency, allow the length of time to be +controlled universally in the admin, and prevent any user data from being used after the consent cookie has expired. ![Cookie Expiration setting](https://raw.githubusercontent.com/wiki/humanmade/altis-consent/images/Altis_Consent_Cookie_Expiration.png) ## Consent Banner Options -The Consent Banner Options setting allows an administrator to determine the type of banner to display. By default, there are two options -- display only the choice to accept only functional cookies or all cookies, or additionally allow a site visitor to choose from all the available cookie categories to personalize the type of data they are okay with sharing. +The Consent Banner Options setting allows an administrator to determine the type of banner to display. By default, there are two +options -- display only the choice to accept only functional cookies or all cookies, or additionally allow a site visitor to choose +from all the available cookie categories to personalize the type of data they are okay with sharing. ![Consent Banner Options setting](https://raw.githubusercontent.com/wiki/humanmade/altis-consent/images/Altis_Consent_Banner_Options.png) ## Consent Banner Message -The Consent Banner Message setting allows an administrator to set the message that displays on the consent banner. A default is set and used if nothing is changed. The field uses a simple what-you-see-is-what-you-get editor, to allow basic formatting and links to be used without any coding necessary. +The Consent Banner Message setting allows an administrator to set the message that displays on the consent banner. A default is set +and used if nothing is changed. The field uses a simple what-you-see-is-what-you-get editor, to allow basic formatting and links to +be used without any coding necessary. ![Consent Banner Message setting](https://raw.githubusercontent.com/wiki/humanmade/altis-consent/images/Altis_Consent_Banner_Message.png) ## Cookie Policy Page -Like the Privacy Policy page setting, the Cookie Policy page setting allows you to define a page designated for your cookie or data retention policy. This cookie policy page can be referenced within the code once it has been defined. +Like the Privacy Policy page setting, the Cookie Policy page setting allows you to define a page designated for your cookie or data +retention policy. This cookie policy page can be referenced within the code once it has been defined. ![Cookie Policy Page setting](https://raw.githubusercontent.com/wiki/humanmade/altis-consent/images/Altis_Consent_Cookie_Policy_Page.png) - - diff --git a/docs/consent/template-architecture.md b/docs/consent/template-architecture.md index 283b750..d932559 100644 --- a/docs/consent/template-architecture.md +++ b/docs/consent/template-architecture.md @@ -1,12 +1,17 @@ # Template Architecture -The Altis Consent module comes with a default banner that can be customized via the [filters](./filter-reference.md) provided for the messaging and button text. However, those templates can be replaced entirely or only specific templates can be replaced by your own in a theme or plugin. +The Altis Consent module comes with a default banner that can be customized via the [filters](./filter-reference.md) provided for +the messaging and button text. However, those templates can be replaced entirely or only specific templates can be replaced by your +own in a theme or plugin. The default banner templates are located in the `/tmpl` directory. ## Overriding the default templates -Overriding the default templates is easy. You can either override all of them using the [`altis.consent.consent_banner_path` filter](./filter-reference.md#altisconsentconsent_banner_path) and defining the path to your main consent banner template file. Or you can override individual templates, keeping the others, by using the filters for the given template path (see below). +Overriding the default templates is easy. You can either override all of them using +the [`altis.consent.consent_banner_path` filter](./filter-reference.md#altisconsentconsent_banner_path) and defining the path to +your main consent banner template file. Or you can override individual templates, keeping the others, by using the filters for the +given template path (see below). ### Example @@ -22,30 +27,55 @@ add_filter( 'altis.consent.cookie_preferences_template_path', get_template_direc ### `consent-banner.php` -The main template file is [`tmpl/consent-banner.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/consent-banner.php). This file path can be customized with the [`altis.consent.consent_banner_path` filter](./filter-reference.md#altisconsentconsent_banner_path) and is loaded with the [load_consent_banner](./function-reference.md#load_consent_banner) function. +The main template file +is [`tmpl/consent-banner.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/consent-banner.php). This file path can +be customized with the [`altis.consent.consent_banner_path` filter](./filter-reference.md#altisconsentconsent_banner_path) and is +loaded with the [`load_consent_banner`](./function-reference.md#load_consent_banner) function. -This template loads the [`consent-updated`](#consent-updatedphp), [`cookie-preferences`](#cookie-preferencesphp) (if applicable), and [`button-row`](#button-rowphp) templates. +This template loads the [`consent-updated`](#consent-updatedphp), [`cookie-preferences`](#cookie-preferencesphp) (if applicable), +and [`button-row`](#button-rowphp) templates. ### `consent-updated.php` -This template displays the "preferences updated" messaging which can be filtered independently with the [`altis.consent.preferences_updated_message` filter](./filter-reference.md#altisconsentpreferences_updated_message). It is located at [`tmpl/consent-updated.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/consent-updated.php) but the template can be overridden with the [`altis.consent.consent_updated_template_path` filter](./filter-reference.md#altisconsentconsent_updated_template_path). +This template displays the "preferences updated" messaging which can be filtered independently with +the [`altis.consent.preferences_updated_message` filter](./filter-reference.md#altisconsentpreferences_updated_message). It is +located at [`tmpl/consent-updated.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/consent-updated.php) but the +template can be overridden with +the [`altis.consent.consent_updated_template_path` filter](./filter-reference.md#altisconsentconsent_updated_template_path). ### `cookie-preferences.php` -This template pulls in the cookie consent categories from `WP_CONSENT_API::$config`, loops through them, and displays options for users to customize the types of cookie tracking they would like to allow. It uses the [`altis.consent.apply_cookie_preferences_button_text` filter](./filter-reference.md#altisconsentapply_cookie_preferences_button_text) for the "apply changes" button. +This template pulls in the cookie consent categories from `WP_CONSENT_API::$config`, loops through them, and displays options for +users to customize the types of cookie tracking they would like to allow. It uses +the [`altis.consent.apply_cookie_preferences_button_text` filter](./filter-reference.md#altisconsentapply_cookie_preferences_button_text) +for the "apply changes" button. -The built-in CSS is designed to display the cookie preferences panel when the cookie preferences button is clicked. When the panel is displayed, the "allow only functional cookies" and "allow all cookies" buttons are hidden in favor of the more granular controls the preferences panel offers. +The built-in CSS is designed to display the cookie preferences panel when the cookie preferences button is clicked. When the panel +is displayed, the "allow only functional cookies" and "allow all cookies" buttons are hidden in favor of the more granular controls +the preferences panel offers. -The template is located at [`tmpl/cookie-preferences.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/cookie-preferences.php). +The template is located +at [`tmpl/cookie-preferences.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/cookie-preferences.php). ## `button-row.php` -This template pulls in the banner message from the options saved on the Altis Privacy page (or displays the [default banner message](./function-reference.md#settingsget_default_banner_message)), loads the [`cookie-consent-policy.php`](#cookie-consent-policyphp) template, and displays buttons to "accept all cookies" or "accept only functional cookies". If more granular controls are set in the admin to allow users to select which categories of cookies they want to accept, it will also display a "cookie preferences" button. +This template pulls in the banner message from the options saved on the Altis Privacy page (or displays +the [default banner message](./function-reference.md#settingsget_default_banner_message)), loads +the [`cookie-consent-policy.php`](#cookie-consent-policyphp) template, and displays buttons to "accept all cookies" or "accept only +functional cookies". If more granular controls are set in the admin to allow users to select which categories of cookies they want +to accept, it will also display a "cookie preferences" button. -The template is located at [`tmpl/button-row.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/button-row.php) but the template can be overridden with the [`altis.consent.button_row_template_path` filter](./filter-reference.md#altisconsentbutton_row_template_path). +The template is located at [`tmpl/button-row.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/button-row.php) but +the template can be overridden with +the [`altis.consent.button_row_template_path` filter](./filter-reference.md#altisconsentbutton_row_template_path). ## `cookie-consent-policy.php` -This template displays a link to the cookie consent policy. The link is generated by pulling the saved option from the Altis Privacy page. If no cookie policy page has been defined, the template isn't loaded in `button-row.php`. The link text is filterable using the [`altis.consent.cookie_consent_policy_link_text` filter](./filter-reference.md#altisconsentcookie_consent_policy_link_text). +This template displays a link to the cookie consent policy. The link is generated by pulling the saved option from the Altis Privacy +page. If no cookie policy page has been defined, the template isn't loaded in `button-row.php`. The link text is filterable using +the [`altis.consent.cookie_consent_policy_link_text` filter](./filter-reference.md#altisconsentcookie_consent_policy_link_text). -The template is located at [`tmpl/cookie-consent-policy.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/cookie-consent-policy.php), but the template can be overridden with the [`altis.consent.cookie_consent_policy_template_path` filter](./filter-reference.md#altisconsentcookie_consent_policy_template_path). +The template is located +at [`tmpl/cookie-consent-policy.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/cookie-consent-policy.php), but +the template can be overridden with +the [`altis.consent.cookie_consent_policy_template_path` filter](./filter-reference.md#altisconsentcookie_consent_policy_template_path). diff --git a/docs/privacy-api/README.md b/docs/privacy-api/README.md index adec571..177bc53 100644 --- a/docs/privacy-api/README.md +++ b/docs/privacy-api/README.md @@ -1,10 +1,13 @@ # Privacy API -The CMS provides extensible privacy tools including a default privacy policy page and hooks for additional code to suggest content for it, as well as the ability to register user data export and deletion callbacks. +The CMS provides extendable privacy tools including a default privacy policy page and hooks for additional code to suggest content +for it, as well as the ability to register user data export and deletion callbacks. ## Privacy Policy Page -The privacy policy page is automatically generated as a draft with basic information related to the operation of the CMS along with headings for sections that should be filled out with more detailed information such as what analytics and trackers are running on the site. +The privacy policy page is automatically generated as a draft with basic information related to the operation of the CMS along with +headings for sections that should be filled out with more detailed information such as what analytics and trackers are running on +the site. [The default page is available to edit here](internal://admin/post.php?post=3&action=edit). @@ -34,7 +37,8 @@ The standard content hierarchy is as follows: ### Using an Existing or Alternative Page -Under the [Settings > Privacy admin menu item](internal://admin/privacy.php) it is possible to select which page you would like to use as the privacy policy page. +Under the [Settings > Privacy admin menu item](internal://admin/privacy.php) it is possible to select which page you would like to +use as the privacy policy page. ![Privacy page settings screen](../assets/privacy-page-settings.png) @@ -48,31 +52,35 @@ $privacy_page_id = get_option( 'wp_page_for_privacy_policy' ); **`wp_add_privacy_policy_content( string $identifier, string $policy_text )`** -This function will provide an editor working on the privacy policy page with prompts for content they can add and the code or feature it relates to. The text should aim to answer one of the default headings described above. +This function will provide an editor working on the privacy policy page with prompts for content they can add and the code or +feature it relates to. The text should aim to answer one of the default headings described above. -If you need to provide information that fits under multiple sections you can make multiple calls to this function to make it easier for editors to pull out the relevant content where needed. +If you need to provide information that fits under multiple sections you can make multiple calls to this function to make it easier +for editors to pull out the relevant content where needed. It is recommended to link out to any 3rd party privacy policies where relevant. ```php // Must be called on the `admin_init` hook. add_action( 'admin_init', function () { - $policy_text = sprintf( - __( 'The Google Analytics feature collects information - about your browser and how you interact with the website. - If you are logged in this information may be associated with - your account. You can learn more by visiting the - Google Privacy Policy page.' - ), - 'https://policies.google.com/privacy?hl=en' - ); - wp_add_privacy_policy_content( 'google-analytics', $policy_text ); + $policy_text = sprintf( + __( 'The Google Analytics feature collects information + about your browser and how you interact with the website. + If you are logged in this information may be associated with + your account. You can learn more by visiting the + Google Privacy Policy page.' + ), + 'https://policies.google.com/privacy?hl=en' + ); + wp_add_privacy_policy_content( 'google-analytics', $policy_text ); } ); ``` ## Personal Data Exports -When a user makes a request for an export of their personal data a confirmation request should be sent to them via the [Export Personal Data tool](internal://admin/tools.php?page=export_personal_data) by filling in their email address and clicking send. +When a user makes a request for an export of their personal data a confirmation request should be sent to them via +the [Export Personal Data tool](internal://admin/tools.php?page=export_personal_data) by filling in their email address and clicking +send. ![Personal Data Export admin screen](../assets/data-export.png) @@ -80,94 +88,100 @@ Once they have confirmed their request a zip file is created and emailed to them ### Extending Personal Data Export -By default the export will contain any data known to be associated with the requester's email address such as comments or posts. Some code may extend the platform in such a way that it cannot determine all the data associated with the user automatically. +By default the export will contain any data known to be associated with the user's email address such as comments or posts. +Some code may extend the platform in such a way that it cannot determine all the data associated with the user automatically. To extend the data export use the `wp_privacy_personal_data_exporters` filter: ```php add_filter( 'wp_privacy_personal_data_exporters', function ( array $exporters ) : array { - $exporters['form-responses'] = [ - 'exporter_friendly_name' => __( 'Form Response Exporter' ), - 'callback' => 'form_response_exporter', - ]; - return $exporters; + $exporters['form-responses'] = [ + 'exporter_friendly_name' => __( 'Form Response Exporter' ), + 'callback' => 'form_response_exporter', + ]; + return $exporters; } ); ``` -The `form_response_exporter` callback function receives the requester's email address and is responsible for collecting the custom data. +The `form_response_exporter` callback function receives the user's email address and is responsible for collecting the custom +data. -The function should paginate results to avoid timeouts and performance issues. To help with this core checks the value of `done` in the returned array and if false will call the function again with the `$page` argument incremented by 1. +The function should paginate results to avoid timeouts and performance issues. To help with this core checks the value of `done` in +the returned array and if false will call the function again with the `$page` argument incremented by 1. The following example exports data from a hypothetical `form_responses` custom post type: ```php function form_response_exporter( string $email, int $page = 1 ) : array { - $export_items = []; - - // Fetch form responses from this email address. - $responses = new WP_Query( [ - 'posts_per_page' => 300, - 'paged' => $page, - 'post_type' => 'form_responses', - 'meta_key' => 'email', - 'meta_value' => $email, - ] ); - - foreach ( $responses->posts as $post ) { - // Most item IDs should look like postType-postID - // If you don't have a post, comment or other ID to work with, - // use a unique value to avoid having this item's export - // combined in the final report with other items of the same id. - $item_id = sprintf( 'form-responses-%d', $post->ID ); - - // Core group IDs include 'comments', 'posts', etc. - // But you can add your own group IDs as needed. - $group_id = 'form-responses'; - - // Optional group label. Core provides these for core groups. - // If you define your own group, the first exporter to - // include a label will be used as the group label in the - // final exported report. - $group_label = __( 'Form Responses' ); - - // Add as many items in the item data array as needed. - $data = [ - [ - 'name' => __( 'Message' ), - 'value' => $post->post_content, - ], - [ - 'name' => __( 'Interests' ), - 'value' => implode( ', ', get_post_meta( $post->ID, 'interests' ) ), - ], - // ... more fields ... - ]; - - // Exported items must match this array structure. - $export_items[] = [ - 'group_id' => $group_id, - 'group_label' => $group_label, - 'item_id' => $item_id, - 'data' => $data, - ]; - } - - // Must return an array of data and a "done" flag. - return [ - 'data' => $export_items, - 'done' => $responses->have_posts(), - ]; + $export_items = []; + + // Fetch form responses from this email address. + $responses = new WP_Query( [ + 'posts_per_page' => 300, + 'paged' => $page, + 'post_type' => 'form_responses', + 'meta_key' => 'email', + 'meta_value' => $email, + ] ); + + foreach ( $responses->posts as $post ) { + // Most item IDs should look like postType-postID + // If you don't have a post, comment or other ID to work with, + // use a unique value to avoid having this item's export + // combined in the final report with other items of the same id. + $item_id = sprintf( 'form-responses-%d', $post->ID ); + + // Core group IDs include 'comments', 'posts', etc. + // But you can add your own group IDs as needed. + $group_id = 'form-responses'; + + // Optional group label. Core provides these for core groups. + // If you define your own group, the first exporter to + // include a label will be used as the group label in the + // final exported report. + $group_label = __( 'Form Responses' ); + + // Add as many items in the item data array as needed. + $data = [ + [ + 'name' => __( 'Message' ), + 'value' => $post->post_content, + ], + [ + 'name' => __( 'Interests' ), + 'value' => implode( ', ', get_post_meta( $post->ID, 'interests' ) ), + ], + // ... more fields ... + ]; + + // Exported items must match this array structure. + $export_items[] = [ + 'group_id' => $group_id, + 'group_label' => $group_label, + 'item_id' => $item_id, + 'data' => $data, + ]; + } + + // Must return an array of data and a "done" flag. + return [ + 'data' => $export_items, + 'done' => $responses->have_posts(), + ]; } ``` ## Erasing Personal Data -Following a similar mechanism to the personal data export should a user request that their personal data be deleted you can send a confirmation email to them via the [Tools > Erase Personal Data page](internal://admin/tools.php?page=remove_personal_data). +Following a similar mechanism to the personal data export should a user request that their personal data be deleted you can send a +confirmation email to them via the [Tools > Erase Personal Data page](internal://admin/tools.php?page=remove_personal_data). -Once confirmed all known data associated with their email address will be deleted. Note the data deleted does not extend to any backups as those are not covered under "making a reasonable effort to remove all data" in accordance with GDPR. +Once confirmed all known data associated with their email address will be deleted. Note the data deleted does not extend to any +backups as those are not covered under "making a reasonable effort to remove all data" in accordance with GDPR. -Should a site ever need to be restored from a backup it is important to go back through previous data removal requests and ensure the data was either already removed or to remove it again. +Should a site ever need to be restored from a backup it is important to go back through previous data removal requests and ensure +the data was either already removed or to remove it again. ### Extending Personal Data Erasers @@ -177,54 +191,55 @@ A date deletion callback can be registered via the `wp_privacy_personal_data_era ```php add_filter( 'wp_privacy_personal_data_erasers', function ( array $erasers ) : array { - $erasers['form_response_eraser'] = [ - 'eraser_friendly_name' => __( 'Form Response Eraser' ), - 'callback' => 'form_response_eraser', - ]; - return $erasers; + $erasers['form_response_eraser'] = [ + 'eraser_friendly_name' => __( 'Form Response Eraser' ), + 'callback' => 'form_response_eraser', + ]; + return $erasers; } ); ``` -The following example shows the deletion of the hypothetical `form_responses` custom post type from earlier and takes the exact same arguments of email address and page: +The following example shows the deletion of the hypothetical `form_responses` custom post type from earlier and takes the exact same +arguments of email address and page: ```php function form_response_eraser( string $email, $page = 1 ) : array { - // Fetch form responses from this email address. - $responses = new WP_Query( [ - 'posts_per_page' => 300, - 'paged' => $page, - 'post_type' => 'form_responses', - 'meta_key' => 'email', - 'meta_value' => $meail, - ] ); - - $items_removed = 0; - $items_retained = 0; - $messages = []; - - foreach ( $responses->posts as $post ) { - // Force detete the post. - $success = wp_delete_post( $post->ID, true ); - - if ( $success ) { - $items_removed++; - } else { - $items_retained++; - $messages[] = sprintf( __( 'Form Response ID %d could not be deleted.' ), $post->ID ); - } - } - - return [ - // Number of items removed. - 'items_removed' => $items_removed, - // Number of items retained. - 'items_retained' => $items_retained, - // Optional messages for response. - 'messages' => $messages, - // Whether we have more data to go through. - 'done' => $responses->have_posts(), - ]; + // Fetch form responses from this email address. + $responses = new WP_Query( [ + 'posts_per_page' => 300, + 'paged' => $page, + 'post_type' => 'form_responses', + 'meta_key' => 'email', + 'meta_value' => $meail, + ] ); + + $items_removed = 0; + $items_retained = 0; + $messages = []; + + foreach ( $responses->posts as $post ) { + // Force detete the post. + $success = wp_delete_post( $post->ID, true ); + + if ( $success ) { + $items_removed++; + } else { + $items_retained++; + $messages[] = sprintf( __( 'Form Response ID %d could not be deleted.' ), $post->ID ); + } + } + + return [ + // Number of items removed. + 'items_removed' => $items_removed, + // Number of items retained. + 'items_retained' => $items_retained, + // Optional messages for response. + 'messages' => $messages, + // Whether we have more data to go through. + 'done' => $responses->have_posts(), + ]; } ``` @@ -244,7 +259,8 @@ Allows modifying the email text sent to users with their data export download li ## Capabilities -The privacy features have some custom capabilities allowing for non-admins or custom user roles to be able to manage personal data exports and deletion. +The privacy features have some custom capabilities allowing for non-admins or custom user roles to be able to manage personal data +exports and deletion. **`erase_others_personal_data`** From 42c555d327fda07e2fc6c07190259bc2469ef4c8 Mon Sep 17 00:00:00 2001 From: Mike Little Date: Mon, 15 Jul 2024 12:49:34 +0100 Subject: [PATCH 2/2] Update travis modules reference --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index ed3df12..268926b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,7 +1,7 @@ # Import Travis configuration from dev-tools repo version: ~> 1.0 import: - - source: humanmade/altis-dev-tools:travis/module.yml@f1fd9a5 + - source: humanmade/altis-dev-tools:travis/module.yml@0bfa112a mode: deep_merge_append # Add your custom config below, which will merge with the default module config from the section above.