← All changes | documentation/how-to-add-new-addon.md +35 -15 3.1.0 → 4.7.4 View file →

		@@ -1,32 +1,52 @@
1		-# How to add new addon
	1	+# How to add a new addon
2	2
	3	+This document explains how the CookieBot plugin can be expanded with addons to block cookies set by specific third-party WordPress Themes and Plugins.
	4	+
	5	+Addon classes
	6	+---
	7	+Every addon is contained in its own class.
	8	+- All addon classes should be located in a subdirectory of [src/addons/controller/addons](../src/addons/controller/addons)
	9	+- Addon classes for third party plugins should extend the `Base_Cookiebot_Plugin_Addon` abstract class.
	10	+- Addon classes for third party themes should extend the `Base_Cookiebot_Theme_Addon` abstract class.
	11	+- There is also a miscellaneous `Base_Cookiebot_Other_Addon` abstract class, which is used for WordPress core features like embedded videos.
	12	+
	13	+Addons with alternative versions
	14	+---
	15	+Addons can return a different addon class for each incompatible version.
	16	+ - The `ALTERNATIVE_ADDON_VERSIONS` class constant should contain an array of strings.
	17	+ - Each array key should correspond to a valid semver version number of the plugin or theme.
	18	+ - Each array value should point to the classname of the addon for that previous plugin/theme version.
	19	+ - One example is the [Custom_Facebook_Feed](../src/addons/controller/addons/custom_facebook_feed/Custom_Facebook_Feed.php) addon, which had to block its cookies in a different manner for [an older version](../src/addons/controller/addons/custom_facebook_feed/Custom_Facebook_Feed_Version_2_17_1.php)
	20	+
3	21	Steps
4	22	---
5	23
6		-1. Add new addon to addons.json
7		-2. Create a directory in addons/controller/addons
8		-3. Create a class in that new directory (copy class from another addon and adjust the namespace, classname and methods.)
9		-4. Edit 'load_configuration' method. That is the only method that needs to be worked on to block the cookies. You can create your own method from there.
10		-5. Test
11		-6. Create integration test if you did use dependencies from the addon plugin. (We run daily tests to see if the dependencies from the addons plugin are still valid.)
12		-7. Send a pull-request in github
	24	+1. Add a new addon to [src/addons/addons.php](../src/addons/addons.php)
	25	+2. Create a directory in [src/addons/controller/addons](../src/addons/controller/addons)
	26	+3. Create a class in that new directory (copy class from another addon and adjust the namespace, classname, interfaces and methods.)
	27	+4. Edit the `load_addon_configuration` method. This is the only method that needs to be worked on in order to block the cookies.
	28	+5. Update all variables and methods according to the addon plugin.
	29	+6. Test
	30	+7. Create integration test if you did use dependencies from the addon plugin. (We run daily tests to see if the dependencies from the addons plugin are still valid.)
	31	+8. Send a pull-request in github
13	32
14	33	Example
15	34	---
16		-1. New addon to addons.json
	35	+1. New addon to [src/addons/addons.php](../src/addons/addons.php)
17	36
18		- ```json
19		- "Add_To_Any": {
20		- "class": "cookiebot_addons\\controller\\addons\\add_to_any\\Add_To_Any"
21		- },
	37	+ ```php
	38	+ Litespeed_Cache::class,
	39	+ matomo::class,
	40	+ Instagram_Feed::class,
	41	+ Add_To_Any::class,
22	42	```
23	43
24		-2. Create directory 'add_to_any' in controller/addons
	44	+2. Create directory 'add_to_any' in src/addons/controller/addons
25	45
26	46	3. Create a class 'Add_To_Any' in 'add_to_any' directory (copy class from another addon and rename everything accordingly)
27	47
28		-5. Go to 'load_configuration' method and rename the callback function to make it give more sense. Write your cookie-blocking logic in that function. You can find more information about how to block cookies in [how-to-block-cookies](how-to-block-cookies.md).
	48	+5. Go to 'load_addon_configuration' method. Write your cookie-blocking logic in that function. You can find more information about how to block cookies in [how-to-block-cookies](how-to-block-cookies.md).
29	49
30	50	6. Test if the cookies are blocked.
31	51
32	52	7. Create integration test for the addon dependencies: https://github.com/CybotAS/CookiebotAddons/blob/develop/tests/integration/addons/test-add-to-any.php