Skip to content

Commit

Permalink
Merge pull request #632 from AdguardTeam/feature/AG-38479
Browse files Browse the repository at this point in the history 
[AG-38479] Updated userscript development section in extensions article
  • Loading branch information
@kurrx
kurrx authored Jan 13, 2025
2 parents 12196e7 + 99ef2dc commit dc9f079
Showing 1 changed file with 176 additions and 58 deletions.
234 changes: 176 additions & 58 deletions docs/general/extensions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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, '<div></div>');

/**
* 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", "<div></div>");
```

## Userstyles

Userstyles allow users to change the appearance of popular websites.
Expand Down

0 comments on commit dc9f079

Please sign in to comment.