You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/terms/explanation/filters.md
+14-16Lines changed: 14 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,36 +5,34 @@ weight: 3
5
5
6
6
# Filters
7
7
8
-
Filters solve [noise]({{< relref "/terms/guideline/declaring/#usual-noise" >}}) issues in terms versions that cannot be addressed with direct selection or removal of content using CSS selectors or range selectors.
8
+
Filters enable solving [noise]({{< relref "/terms/guideline/declaring/#usual-noise" >}}) issues in versions that cannot be addressed with direct selection or removal of content using selectors.
9
9
10
10
## When filters are needed
11
11
12
-
Filters are necessary when standard CSS selectors and range selectors cannot adequately address noise in terms versions. They provide a solution for complex content manipulation that goes beyond simple selection and removal.
13
-
14
12
Use filters when:
15
13
16
-
-**CSS selectors are insufficient**, for example when noise appears within content that can't be targeted with selectors or [range selectors]({{< relref "terms/explanation/range-selectors" >}}) with the [`select`]({{< relref "terms/reference/declaration/#ref-select" >}}) and [`remove`]({{< relref "terms/reference/declaration/#ref-remove" >}}) properties.
17
-
-**Content is dynamically generated**, for example when elements change on each page load with tracking parameters in URLs (like `utm_source`, `utm_medium`) or dynamic elements with changing classes or IDs.
18
-
-**Complex tasks are needed**, for example when content transformation is required such as converting images to base64 to store them in the terms version or converting date-based content to a more stable format (like "Updated X days ago" to "Last updated on YYYY-MM-DD").
14
+
-**Content selectors are insufficient**, for example when noise appears within content that can't be targeted with CSS selectors or [range selectors]({{< relref "terms/explanation/range-selectors" >}}) with the [`select`]({{< relref "terms/reference/declaration/#ref-select" >}}) and [`remove`]({{< relref "terms/reference/declaration/#ref-remove" >}}) properties.
15
+
-**Content is dynamically generated**, for example when elements change on each page load with changing classes or IDs that cannot be targeted with [attribute selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors).
16
+
-**Complex tasks are needed**, for example when content transformation is required such as converting images to base64 to store them in the terms version or converting date-based content to a stable format (like “Updated X days ago” to “Last updated on YYYY-MM-DD”).
19
17
20
18
## How filters work
21
19
22
-
Filters are JavaScript functions that receive a JSDOM document instance and can manipulate the DOM structure directly. They modify the document structure and content in-place and they run sequentially in the order specified in the declaration.
20
+
Filters are JavaScript functions that can manipulate the DOM structure directly. They modify the document structure and content in-place.
23
21
24
22
## Filter design principles
25
23
26
-
When designing filters, follow these core principles:
24
+
Filters should follow these core principles:
25
+
26
+
-**Specific**: target only the noise to remove. Avoid broad selectors that might accidentally remove important content.
27
27
28
-
-**Be specific**: target only the noise you want to remove. Avoid broad selectors that might accidentally remove important content.
28
+
> For example, if a filter converts relative dates to absolute dates, make sure to scope the targeted dates. This might translate to selecting with `.metadata time`, not `time`, which might also affect important effective dates within the terms content.
29
29
30
-
> For example, if your filter converts relative dates to absolute dates, use `.metadata time` not `time` which might also affect important effective dates within the terms content.
30
+
-**Idempotent**: filters should produce the same result even if run multiple times on their own output. This ensures consistency.
31
31
32
-
-**Be idempotent**: filters should produce the same result even if run multiple times on their own output. This ensures consistency and prevents unexpected behavior.
32
+
> For example, if a filter adds section numbers like "1." to headings, it should check if the numbers already exist, to prevent "1. Privacy Policy" from becoming "1. 1. Privacy Policy" on repeated runs.
33
33
34
-
> For example, if your filter adds section numbers like "1." to headings, check if numbers already exist to prevent "1. Privacy Policy" from becoming "1. 1. Privacy Policy" on repeated runs.
34
+
-**Efficient**: DOM queries should be optimised and filters should avoid unnecessary operations, processing only the elements needed.
35
35
36
-
-**Be efficient**: use efficient DOM queries and avoid unnecessary operations. Process only the elements you need to modify.
37
-
38
-
> For example, if your filter updates timestamp elements with a specific class, use `document.querySelector('.timestamp')` instead of `document.querySelectorAll('*')` followed by filtering for timestamp elements.
36
+
> For example, if a filter updates timestamp elements with a specific class, using `document.querySelectorAll('.timestamp')` is more efficient than `document.querySelectorAll('*')` followed by filtering for timestamp elements.
39
37
40
-
-**Be safe**: filters should not accidentally remove important content. The generated version should always be checked after adding a filter to ensure it still contains the whole terms content.
38
+
-**Safe**: filters must not accidentally remove important content. The generated version should always be checked after adding a filter to ensure it still contains the whole terms content.
Copy file name to clipboardExpand all lines: content/terms/how-to/apply-filters.md
+26-24Lines changed: 26 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,45 +5,47 @@ weight: 7
5
5
6
6
# How to apply filters
7
7
8
-
This guide explains how to apply filters to existing declarations to remove meaningless content that changes on each page load or that cannot be removed with CSS selectors to avoid noise in the terms changes history.
8
+
This guide explains how to add filters to existing declarations to remove meaningless content that cannot be removed with CSS selectors, to prevent noise in the versions.
9
9
10
10
## Prerequisites
11
11
12
-
- An existing terms declaration file
13
-
-Identified the noise you want to remove and ensure it cannot be removed with CSS selectors with the [`remove`]({{< relref "terms/reference/declaration/#ref-remove" >}}) property.
12
+
- An existing terms declaration file.
13
+
-Having already identified the noise to remove and having double-checked it cannot be removed with CSS selectors with the [`remove`]({{< relref "terms/reference/declaration/#ref-remove" >}}) property.
14
14
15
15
## Step 1: Check for built-in filters
16
16
17
-
Built-in filters are pre-defined functions that handle common noise patterns. They're the easiest way to clean up content without writing custom code.
17
+
Built-in filters are pre-defined functions that handle common noise patterns. They are the easiest way to clean up content.
18
18
19
19
Review the available [built-in filters]({{< relref "/terms/reference/built-in-filters" >}}) to find if one matches your needs.
20
20
21
-
If you find a suitable built-in filter, proceed to [Step 2](#step-2-declare-the-filter), otherwise you will need to create a custom filter.
21
+
If you find a suitable built-in filter, proceed to [Step 3](#step-3-declare-the-filter), otherwise you will need to create a custom filter.
22
22
23
-
### Create a custom filter (optional)
23
+
##Step 2: Create a custom filter _(optional)_
24
24
25
-
If no built-in filter matches your needs, you'll need to create a custom filter. This requires JavaScript knowledge and familiarity with DOM manipulation.
25
+
If no built-in filter matches your needs, you will need to create a custom filter. This requires JavaScript knowledge and familiarity with DOM manipulation.
26
26
27
-
####Create the filter file
27
+
### Create the filter file
28
28
29
-
Create a JavaScript file with the same name as your service declaration but with `.filters.js` extension. For example, if your declaration is `declarations/MyService.json`, create `declarations/MyService.filters.js`.
29
+
Create a JavaScript file in the same folder and with the same name as your service declaration, but with `.filters.js` extension.
30
30
31
-
#### Write the filter function
31
+
> For example, if your declaration is `declarations/MyService.json`, create `declarations/MyService.filters.js`.
32
32
33
-
Define your filter function following this signature:
33
+
### Write the filter function
34
+
35
+
Define your filter function with the following signature:
@@ -84,20 +86,20 @@ Result after applying the filter:
84
86
+ <p class="session-id">Last updated on 2023-12-07</p>
85
87
```
86
88
87
-
## Step 2: Declare the filter
89
+
## Step 3: Declare the filter
88
90
89
-
Open your service declaration file (e.g.,`declarations/MyService.json`) and locate the `filter` property of the specific terms you want to apply the filter to. If it doesn't exist, add it as an array.
91
+
Open your service declaration file (e.g. `declarations/MyService.json`) and locate the `filter` property of the specific terms you want to apply the filter to. If it doesn't exist, add it as an array.
90
92
91
93
### Filter without parameters
92
94
93
-
For filters that don't require parameters, add the filter name as a string:
95
+
For filters that don’t require parameters, add the filter name as a string:
@@ -107,16 +109,16 @@ For filters that don't require parameters, add the filter name as a string:
107
109
}
108
110
```
109
111
110
-
### Parameterized filter
112
+
### Filter with parameters
111
113
112
-
For filters that require parameters, use an object format, for example with the built-in filter `removeQueryParams` to remove query parameters from URLs:
114
+
For filters that take parameters, use an object format, for example with the built-in filter `removeQueryParams` to remove query parameters from URLs:
0 commit comments