diff --git a/docs/general/extensions.md b/docs/general/extensions.md index 0f85a6bb1a5..c08858dee0b 100644 --- a/docs/general/extensions.md +++ b/docs/general/extensions.md @@ -93,76 +93,62 @@ If you are developing your own userscript and want to test how it works with AdG #### Compatibility -#### Metadata block - -#### Supported properties - -```text -@name -@namespace -@description -@version -@match -@include -@exclude -@grant -@connect -@require -@resource -@downloadURL -@updateURL -@supportURL -@homepageURL -@homepage -@website -@source -@run-at -@noframes -@icon -@iconURL -@defaulticon -@icon64 -@icon64URL -``` - -#### Unsupported properties +##### Metadata block + +###### Supported properties + +- [`@name`](https://wiki.greasespot.net/Metadata_Block#@name) +- [`@namespace`](https://wiki.greasespot.net/Metadata_Block#@namespace) +- [`@description`](https://wiki.greasespot.net/Metadata_Block#@description) +- [`@version`](https://wiki.greasespot.net/Metadata_Block#@version) +- [`@match`](https://wiki.greasespot.net/Metadata_Block#@match) +- [`@include`](https://wiki.greasespot.net/Metadata_Block#@include) +- [`@exclude`](https://wiki.greasespot.net/Metadata_Block#@exclude) +- [`@grant`](https://wiki.greasespot.net/Metadata_Block#@grant) +- [`@connect`](https://www.tampermonkey.net/documentation.php#meta:connect) +- [`@require`](https://wiki.greasespot.net/Metadata_Block#@require) +- [`@resource`](https://wiki.greasespot.net/Metadata_Block#@resource) +- [`@downloadURL`](https://www.tampermonkey.net/documentation.php#meta:downloadURL) +- [`@updateURL`](https://www.tampermonkey.net/documentation.php#meta:updateURL) +- [`@homepage`, `@homepageURL`, `@source`, `@website`](https://www.tampermonkey.net/documentation.php#meta:homepage) +- [`@run-at`](https://wiki.greasespot.net/Metadata_Block#@run-at) +- [`@noframes`](https://wiki.greasespot.net/Metadata_Block#@noframes) +- [`@icon`, `@iconURL`, `@defaulticon`](https://www.tampermonkey.net/documentation.php#meta:icon) +- [`@icon64`, `@icon64URL`](https://www.tampermonkey.net/documentation.php#meta:icon64) + +###### Unsupported properties These properties will be simply ignored by AdGuard. -```text -@unwrap -``` +- [`@unwrap`](https://www.tampermonkey.net/documentation.php#meta:unwrap) -#### Supported GM functions +##### Supported GM functions AdGuard supports both old GM\_ functions and new GM4 API that use GM object. -#### Values - :::note All listed old Greasemonkey functions are deprecated but still supported. ::: -```text -GM.info / GM_info -GM.setValue / GM_setValue -GM.getValue / GM_getValue -GM.listValues / GM_listValues -GM.deleteValue / GM_deleteValue -GM.getResourceUrl / GM_getResourceURL -GM.setClipboard / GM_setClipboard -GM.xmlHttpRequest / GM_xmlhttpRequest -GM.openInTab / GM_openInTab -GM.notification -unsafeWindow -GM_getResourceText -GM_addStyle -GM_log -``` - -[Here](https://wiki.greasespot.net/GM.info) you can find more information about Greasemonkey API. +- [`GM.info`, `GM_info`](https://wiki.greasespot.net/GM.info) +- [`GM.setValue`, `GM_setValue`](https://wiki.greasespot.net/GM.setValue) +- [`GM.getValue`, `GM_getValue`](https://wiki.greasespot.net/GM.getValue) +- [`GM.listValues`, `GM_listValues`](https://wiki.greasespot.net/GM.listValues) +- [`GM.deleteValue`, `GM_deleteValue`](https://wiki.greasespot.net/GM.deleteValue) +- [`GM.getResourceUrl`, `GM_getResourceURL`](https://wiki.greasespot.net/GM.getResourceUrl) +- [`GM.setClipboard`, `GM_setClipboard`](https://wiki.greasespot.net/GM.setClipboard) +- [`GM.xmlHttpRequest`, `GM_xmlhttpRequest`](https://wiki.greasespot.net/GM.xmlHttpRequest) +- [`GM.openInTab`, `GM_openInTab`](https://wiki.greasespot.net/GM.openInTab) +- [`GM.notification`](https://wiki.greasespot.net/GM.notification) +- [`unsafeWindow`](https://wiki.greasespot.net/UnsafeWindow) +- [`GM_getResourceText`](https://www.tampermonkey.net/documentation.php#api:GM_getResourceText) +- [`GM_addStyle`](https://www.tampermonkey.net/documentation.php#api:GM_addStyle) +- [`GM_log`](https://www.tampermonkey.net/documentation.php#api:GM_log) +- [`GM.addElement`, `GM_addElement`](https://www.tampermonkey.net/documentation.php#api:GM_addElement) + +You can find more information about Greasemonkey API in [its manual](https://wiki.greasespot.net/Greasemonkey_Manual:API). #### Example @@ -196,13 +182,145 @@ GM_log // @grant GM_info // @grant GM_openInTab // @grant GM_registerMenuCommand -// @run-at document-start +// @grant GM_addElement +// @run-at document-start // ==/UserScript== !function(){( console.log("I am loaded!"); )}(); ``` +#### Trusted Types API + +AdGuard provides an instance of the `PolicyApi` class that allows you to manage Trusted Types in your userscripts. + +You can access the instance of this class by using the `ADG_policyApi` variable in your userscript. + +##### Properties + +- `name: string` — a name of the policy (Default is `"AGPolicy"`). +- `isSupported: boolean` — a flag indicating whether or not the Trusted Types API is supported by the current browser. + +##### Polyfilled methods + +- [`ADG_policyApi.createHTML`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy/createHTML). If not supported, returns `input: string`. +- [`ADG_policyApi.createScript`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy/createScript). If not supported, returns `input: string`. +- [`ADG_policyApi.createScriptURL`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy/createScriptURL). If not supported, returns `input: string`. +- [`ADG_policyApi.getAttributeType`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/getAttributeType). If not supported, returns `null`. +- [`ADG_policyApi.getPropertyType`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/getPropertyType). If not supported, returns `null`. +- [`ADG_policyApi.isHTML`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/isHTML). If not supported, returns `false`. +- [`ADG_policyApi.isScript`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/isScript). If not supported, returns `false`. +- [`ADG_policyApi.isScriptURL`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/isScriptURL). If not supported, returns `false`. + +##### Additional Types + +```typescript +/** + * Enum representation of the return values of the `getAttributeType` and + * `getPropertyType` methods of the native Trusted Types API. + * + * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/getAttributeType} + * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/getPropertyType} + */ +enum TrustedType { + HTML = 'TrustedHTML', + Script = 'TrustedScript', + ScriptURL = 'TrustedScriptURL', +} + +// You can access it like that inside of userscript +ADG_TrustedType.HTML // "TrustedHTML" + +/** + * Isomorphic trusted value type. If a browser supports the Trusted Types API, it will be one of the enum Trusted Types + * (`TrustedHTML`, `TrustedScript` or `TrustedScriptURL`); otherwise, it will be regular `string`. + * + * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedHTML} + * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedScript} + * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedScriptURL} + */ +type TrustedValue = string | TrustedHTML | TrustedScript | TrustedScriptURL; +``` + +##### Additional methods + +```typescript +/** + * Creates a Trusted Type depending on `type`: + * - `TrustedHTML` + * - `TrustedScript` + * - `TrustedScriptURL` + * - or returns `value` if none of them is applicable. + * + * @param type Trusted Type. + * @param value Value from which a Trusted Type is created. + * @param createArgs Additional arguments to be passed to the function represented by `TrustedTypePolicy`. + * @returns Created value. + */ +function create( + type: TrustedType, + value: string, + ...createArgs: unknown[] +): TrustedValue + + +// Example: Creates TrustedHTML +const trustedHTML = ADG_policyApi.create(ADG_TrustedType.HTML, '
'); + +/** + * Converts `value` of `attribute` into one of the Trusted Types: + * - `TrustedHTML` + * - `TrustedScript` + * - `TrustedScriptURL` + * - or returns `value` if none of them is applicable. + * + * @param tagName Name of an HTML tag. + * @param attribute Attribute. + * @param value Value of an attribute to be converted. + * @param elementNS Element namespace. If empty, defaults to the HTML namespace. + * @param attrNS Attribute namespace. If empty, defaults to null. + * @param createArgs Additional arguments to be passed to the function represented by `TrustedTypePolicy`. + * @returns Converted value. + */ +function convertAttributeToTrusted( + tagName: string, + attribute: string, + value: string, + elementNS?: string, + attrNS?: string, + ...createArgs: unknown[] +): TrustedValue + +// Example: Converts to TrustedScriptURL +const trustedScriptURL = ADG_policyApi.convertAttributeToTrusted("script", "src", 'SOME_URL'); +scriptElement.setAttribute("src", trustedScriptURL); + +/** + * Converts `value` of `property` into one of the Trusted Types: + * - `TrustedHTML` + * - `TrustedScript` + * - `TrustedScriptURL` + * - or returns `value` if none of them is applicable. + * + * @param tagName Name of an HTML tag. + * @param property Property. + * @param value Value of a property to be converted. + * @param elementNS Element namespace. If empty, defaults to the HTML namespace. + * @param createArgs Additional arguments to be passed to the function represented by `TrustedTypePolicy`. + * @returns Converted value. + */ +function convertPropertyToTrusted( + tagName: string, + property: string, + value: string, + elementNS?: string, + ...createArgs: unknown[] +): TrustedValue + +// Example: Converts to TrustedHTML +divElement.innerHTML = ADG_policyApi.convertPropertyToTrusted("div", "innerHTML", "
"); +``` + ## Userstyles Userstyles allow users to change the appearance of popular websites.