Page Shadow - Filter syntax guide

This documentation is only applicable to version 2.11 of Page Shadow

The filter rules are used to fix the display of websites when the Increase page contrast and/or Invert the colors features are enabled. The fixes can relate to the disabling of the modification of the style of an element (background color, color of texts or links, inversion of the color) or the fact of forcing a style on an element. These rules make it possible, for example, to correct the display of certain elements that don't appear. You can write your own filter rules. If you have some knowledge of HTML/CSS, it's pretty straightforward. In a filter file, only one rule per line is possible.

You can use the extension's internal editor (Filters > Edit my filter) which has the appropriate syntax highlighting and which automatically auto-completes the rules you write.

Syntax

The syntax of a filter is of the following form: websiteOrWebpage[1]|rule[2]|cssSelector or parameter[3]

Each part of the filter is divided by a character | (vertical bar).

[1] websiteOrWebpage

The first part of the rule (websiteOrPage) indicates the website/web page on which the filter should be applied. This part can be of the following form:

  • A domain: for example eliastiksofts.com or www.eliastiksofts.com (these two domains are treated separately)
  • A webpage: for example https://www.eliastiksofts.com/fr/page-shadow/filters/guide/index.php
  • A rule with wildcards (can match a domain or a webpage): for example *eliastiksofts.com/en/* matches all the pages of the Eliastik's Softs website in English version
  • A regular expression (can match a domain or a webpage): for example /(.*)google.(.*)recaptcha(.*)/ match Google ReCaptcha

[2] rule

This part of the filter corresponds to the rule itself. There are several different rules that are recognized by the extension:

Standard rules
  • disableContrastFor : completely disables the Increase page contrast feature for one or more elements
  • forceTransparentBackground : forces a transparent background for one or more elements
  • disableBackgroundStylingFor : disables the background coloring by the Increase page contrast feature for one or more elements
  • disableTextColorStylingFor : disables the coloring of texts by the Increase page contrast feature for one or more elements
  • disableInputBorderStylingFor : disables the coloring of the borders of form fields by the Increase page contrast feature for one or more elements
  • disableLinkStylingFor : disables the coloring of links by the Increase page contrast feature for one or more elements
  • disableFontFamilyStylingFor : disables the modification of the font (custom themes) by the Increase page contrast features for one or more elements
  • disableElementInvertFor : disables the inversion of colors by the function Invert the colors for one or more elements
  • hasBackgroundImg : tells Page Shadow that one or more elements have a background image
  • forceCustomLinkColorFor : forces the modification of the color of the links by the feature Increase page contrast for one or more elements
  • forceCustomBackgroundColorFor : forces the modification of the background color by the feature Increase page contrast for one or more elements
  • forceCustomTextColorFor : forces the modification of the color of the texts by the feature Increase page contrast for one or more elements
  • disableShadowRootsCustomStyle : forces the disabling of the Shadow Roots styles by the Increase page contrast function for one or more elements
  • forceCustomVisitedLinkColor : forces the modification of the color of the visited links for one or more elements
  • disableCustomVisitedLinkColor : disables the modification of the color of visited links for one or more elements
  • forceFontFamilyStylingFor : forces custom font from custom themes for one or more elements
  • forceInputBorderStylingFor : forces the display of a border for one or more form fields
  • forceCustomLinkColorAsBackground : sets the background color of one or more elements to that of the links color from the theme
  • forceCustomTextColorAsBackground : sets the background color of one or more elements to that of the texts color from the theme
  • forceCustomLinkVisitedColorAsBackground : sets the background color of one or more elements to that of the visited links color from the theme
  • forceDisableDefaultBackgroundColor : forces the default background color of one or more elements to be disabled, to be used as a last resort
  • forceDisableDefaultBackground : forces the default background of one or more elements to be disabled, to be used as a last resort
  • forceDisableDefaultFontColor : forces the default font for one or more elements to be disabled, to be used as a last resort
  • enablePseudoElementsStyling : forces the extension to modify the style of :after and :before CSS pseudo-elements for one or more elements
  • overrideShadowRootsCustomStyle : same rule as disableShadowRootsCustomStyle
  • invertElementAsImage : enable colors invert of one or more elements as an image
  • invertElementAsVideo : enable colors invert of one or more elements as a video
  • invertElementAsBackground : enable colors invert of one or more elements as a background image
  • enableSelectiveInvert : enable selective invert of one or more elements
  • enablePseudoElementSelectiveInvert : enable selective invert of one or more pseudo-elements
  • invertPseudoElement : enable colors invert of one or more pseudo-elements
  • forcePseudoElementsTransparentBackground : force a transparent background on one or more pseudo-elements of an element
  • preserveBrightColor : tells Page Shadow that one or more elements have a brightly colored background/text, and treats them as such
  • hasBrightColorWithWhiteText/hasBrightColorWithBlackText : if an element is detected as having a brightly colored background (either automatically, or via the preserveBrightColor filter), forcibly displays the text in black or white.
Special rules

These rules change the way Page Shadow works internally. They allow you to enable or disable certain features.

  • enablePerformanceMode : activates performance mode for the website or webpage. This rule doesn't require a CSS selector. This is equivalent to disabling the analysis of web page elements, while retaining filter management. This can therefore cause display problems on some websites with the Increase page contrast feature (which can be compensated for with the standard rules on poorly displayed elements).
  • disablePerformanceMode : disables performance mode for the website or webpage. Rule intended to be combined with the rule enablePerformanceMode for example to enable performance mode for the whole website and to disable it for some pages.
  • disableTransparentBackgroundAutoDetect : disables automatic detection of transparent backgrounds, doesn't improve performance when disabled alone
  • enableTransparentBackgroundAutoDetect : enables automatic detection of transparent backgrounds (this feature is enabled by default)
  • opacityDetectedAsTransparentThreshold : sets the limit for which the automatic detection of transparent backgrounds treats an opacity as being a transparent background (by default any opacity less than or equal to 0.1 is treated as a transparent background)
  • enableMutationObserversForSubChilds : when enabled, the extension will loop through all the sub-elements of an element added to the page (enabled by default)
  • disableMutationObserversForSubChilds : disables browsing of all sub-elements of an element added to the page, may improve performance but may cause display issues
  • enableMutationObserverAttributes : enables the detection of attribute mutations (style or class in HTML), enabled by default
  • disableMutationObserverAttributes : disablesthe detection of attribute mutations, may improve performance
  • enableMutationObserverClass : enables the detection of mutations of the HTML class attribute (disabled by default)
  • disableMutationObserverClass : disables detection of HTML class attribute mutations, may improve performance
  • enableMutationObserverStyle : enables the detection of mutations of the HTML style attribute (enabled by default)
  • disableMutationObserverStyle : disables mutations detection of HTML style attribute, may improve performance
  • enableShadowRootStyleOverride : enables overriding of the default styles of Shadow Roots elements (enabled by default)
  • disableShadowRootStyleOverride : disables overriding of default styles of Shadow Roots elements, may improve performance on websites that use this feature
  • shadowRootStyleOverrideDelay : set the delay (by default 100 ms) necessary before analyzing an element which contains a Shadow Root to improve their detection, setting a delay less than or equal to 0 disables this feature
  • enableThrottleMutationObserverBackgrounds : enables the throttle of the processing of Mutation Observers, considerably improves performance. Disabled by default
  • disableThrottleMutationObserverBackgrounds : disables the throttle of the processing of Mutation Observers
  • delayMutationObserverBackgrounds : delay in ms applied to processing of Mutation Observers when the enableThrottleMutationObserverBackgrounds rule is enabled. Default to 0, which means that mutations are processed as soon as possible
  • throttledMutationObserverTreatedByCall : number of mutations to process on each call, default to 50. A large number reduces performance.
  • delayApplyMutationObserversSafeTimer : delay before reapplying Page Shadow settings after detection by Mutation Observers
  • enableObserveBodyChange/disableObserveBodyChange : observes the state change of the body element (deletion then creation of a new body element). Fixes issues with some websites (like Github) or SPA applications. Disabling this option may improve performance
  • observeBodyChangeTimerInterval : observing the state change of the body element relies on a timer that runs at a given interval (instead of using Mutation Observers). The interval is in ms
  • enableBrightColorDetection/disableBrightColorDetection : detect element with bright color, and if enabled by the user, disable the Increase contrast function for these elements. Disabling this option may improve performance
  • brightColorLightnessTresholdMin : if an element has a lightness value that is above this treshold but lower than the maximum, the element will be detected as bright color element
  • brightColorLightnessTresholdMax : if an element has a lightness value that is lower than this treshold but above the minimum, the element will be detected as bright color element
  • enableThrottleBackgroundDetection/disableThrottleBackgroundDetection : applies a delay to the element analysis on page load, which can improve performance on large pages
  • throttleBackgroundDetectionElementsTreatedByCall : sets the number of elements processed by each loop call when element analysis is throttled. A high value can impact performance
  • backgroundDetectionStartDelay : apply a delay before applying element analysis. By default 1 ms.
  • useBackgroundDetectionAlreadyProcessedNodes : use an already processed elements list for element analysis to avoid re-processing elements. May increase performance but may increase memory usage.
  • enableBrightColorDetectionSubelement/disableBrightColorDetectionSubelement : enables or disables processing of sub-elements of elements with bright colors. Disabling this option may potentially improve performance, but display problems may occur on some websites when using the feature Preserve element colors
  • observeDocumentChange : observes the change of state of the document (HTML element), and more specifically of the style attribute. Fixes issues with some websites that overwrite the style attribute value used to manage Page Shadow CSS variables. Disabling this option can improve performance.
  • observeDocumentChangeTimerInterval : observing the state change of the document (HTML) element relies on a timer that runs at a given interval (instead of using Mutation Observers). The interval is in ms.
  • enableDarkImageDetection/disableDarkImageDetection : enables or disables detection of images/backgrounds with a large number of dark colors (e.g. text and logos), in order to invert their colors if the setting Invert colors > Selective is enabled by the user. Disabling this option improves performance.
  • darkImageDetectionHslTreshold : if a pixel has a lightness value below this threshold, the pixel is considered dark. The maximum value is 1, the minimum is 0 (percentage).
  • brightColorLightnessTresholdTextMin : same as brightColorLightnessTresholdMin, but applies only to text elements.
  • brightColorSaturationTresholdMin : minimum saturation value (in HSL color space) to detect text as having a bright color.
  • enableNotMatchingFiltersDetection/disableNotMatchingFiltersDetection : if an element no longer matches one of the filters previously applied to it, the filter is removed from the element. Enabling this option can reduce performance and increase memory consumption, as Page Shadow needs to store information on elements that previously matched a given filter.
  • intervalApplyClassChanges : sets the interval (in ms) for CSS class changes on elements. Increasing the interval can improve performance.
  • classChangeMaxElementsTreatedByCall : number of elements processed (CSS class changes) at each interval. Increasing this number may reduce performance.
  • darkImageDetectionMinAlpha : the minimum value (in percentage) of the alpha channel required to analyze the pixel in an image. If the value is below this threshold, the pixel is ignored. Default 0.5 (for 50%).
  • darkImageDetectionBlockSize : when a pixel is detected as dark according to the brightness value, its surroundings are analyzed for transparent pixels. This value sets the number of pixels to be analyzed around the detected pixel.
  • darkImageDetectionTransparentPixelsRatio : when analyzing the neighborhood of the pixel detected as dark, sets the minimum ratio of transparent pixels required. If this ratio is exceeded, the image is detected as dark.
  • darkImageDetectionDarkPixelsRatio : when analyzing the neighborhood of the pixel detected as dark, sets the minimum ratio of additional dark pixels required (in relation to non-transparent pixels). If this ratio is exceeded, the image is detected as dark.
  • enableThrottleDarkImageDetection/disableThrottleDarkImageDetection : enables or disables the throttling of web page image analysis.
  • throttleDarkImageDetectionDelay : sets the delay (in ms) before executing the analysis of queued images. Increasing this delay can improve performance.
  • throttleDarkImageDetectionBatchSize : sets the number of queued images to be analyzed at once.
  • enableThrottleMutationObserverBackgroundsSubChilds/disableThrottleMutationObserverBackgroundsSubChilds : enables or disables the throttling of the analysis of the sub-children of an element detected by Mutation Observers.
  • delayMutationObserverBackgroundsSubchilds : sets the delay (in ms) before an element's sub-children are analyzed. Increasing this delay can improve performance.
  • throttledMutationObserverSubchildsTreatedByCall : sets the number of sub-children in the queue to be analyzed at once.
  • delayApplyClassChanges : applies an additional delay (in ms) before changing CSS classes on elements. Increasing the delay can improve performance.
  • throttleBackgroundDetectionMaxExecutionTime : if the execution of the call (element analysis) exceeds this execution time (in ms), the call is interrupted to free up resources. This considerably improves performance.
  • throttleDarkImageDetectionMaxExecutionTime : if the execution of the call (image analysis) exceeds this execution time (in ms), the call is interrupted to free up resources. This considerably improves performance.
  • throttledMutationObserverMaxExecutionTime : if call execution (mutation observers) exceeds this execution time (in ms), the call is interrupted to free up resources. This considerably improves performance.
  • throttledMutationObserverSubchildsMaxExecutionTime : if the execution of the call (analysis of an element's sub-children) exceeds this execution time (in ms), the call is interrupted to free up resources. This considerably improves performance.
  • applyClassChangesMaxExecutionTime : if the execution of the call (change of element CSS classes) exceeds this execution time (in ms), the call is interrupted to free up resources. This considerably improves performance.
  • autoThrottleBackgroundDetectionTime : if the throttling of element analysis is not enabled, it is activated automatically if the execution time exceeds this value (in ms). This prevents web pages from being blocked if the initial analysis execution time is too long.
  • enableThrottleApplyClassChanges/disableThrottleApplyClassChanges : enable or disable throttling Page Shadow's application of CSS class changes to elements. This can improve performance in certain scenarios.
  • enableURLChangeDetection/disableURLChangeDetection : enables or disables URL change detection on SPA (single page application) applications, allowing Page Shadow to reapply settings and filters based on the new URL. Disabling this option can improve performance on some websites that frequently change their URL.
  • enablePseudoElementsAnalysis/disablePseudoElementsAnalysis : enables or disables pseudo-element analysis. Disabling this option may improve performance, but may cause display problems.
  • enableDarkImageDetectionCache/disableDarkImageDetectionCache : enables or disables caching of images already analyzed by the analysis engine. This improves performance by avoiding the need to reanalyze images already analyzed. Only the URL and analysis results of images already analyzed are cached. The cache is per page.
  • darkImageDetectionMaxCacheSize : sets the maximum cache size (number of elements) for images already analyzed. If the size exceeds this threshold, the oldest analyses will be purged from the cache, to avoid excessive memory usage.
  • enableMutationObserverProcessNewestFirst/disableMutationObserverProcessNewestFirst : if this option is enabled, the most recent mutations will be given priority over the oldest. This has no impact on performance, and is only useful for certain websites.
  • enableSelectiveInvertPreserveColors/disableSelectiveInvertPreserveColors : if this option is enabled, the selective inversion filter will attempt to preserve the original colors while only inverting black and white.

It's possible to indicate several rules of the same type by separating them with a comma. The name of the rules is case sensitive.

[3] cssSelector or parameter

This part of the filter contains the CSS selector corresponding to the elements on which to apply the filter. You can specify multiple selectors by separating them with a comma. If the selector is not valid, the rule will be ignored. The CSS selector is processed by the function document.querySelectorAll within the extension code. For the full list of available CSS selectors, visit the MDN documentation.

This part can also correspond to a parameter that is not a CSS selector. For example, some special rules such as the following require a parameter (e.g. a number): opacityDetectedAsTransparentThreshold, shadowRootStyleOverrideDelay, delayMutationObserverBackgrounds, autoThrottleMutationObserverBackgroundsTreshold, throttledMutationObserverTreatedByCall, delayApplyMutationObserversSafeTimer, observeBodyChangeTimerInterval, brightColorLightnessTresholdMin, brightColorLightnessTresholdMax, throttleBackgroundDetectionElementsTreatedByCall, observeDocumentChangeTimerInterval, darkImageDetectionHslTreshold, darkImageDetectionDarkPixelCountTreshold, brightColorLightnessTresholdTextMin, brightColorSaturationTresholdMin, intervalApplyClassChanges, classChangeMaxElementsTreatedByCall, darkImageDetectionMinAlpha, darkImageDetectionBlockSize, darkImageDetectionTransparentPixelsRatio, darkImageDetectionDarkPixelsRatio, throttleDarkImageDetectionDelay, throttleDarkImageDetectionBatchSize, delayMutationObserverBackgroundsSubchilds, throttledMutationObserverSubchildsTreatedByCall, delayApplyClassChanges, throttleBackgroundDetectionMaxExecutionTime, throttleDarkImageDetectionMaxExecutionTime, throttledMutationObserverMaxExecutionTime, throttledMutationObserverSubchildsMaxExecutionTime, applyClassChangesMaxExecutionTime, autoThrottleBackgroundDetectionTime and darkImageDetectionMaxCacheSize. The shadowRootStyleOverrideDelay special rule also requires an additional parameter (the delay in ms).

Example rule

This filter is used to correct the display of Google ReCaptchas when the Increase page contrast feature is enabled. It disables the function for some elements that were hidden.

/(.*)google.(.*)recaptcha(.*)/|disableContrastFor|.rc-imageselect-checkbox,.rc-imageselect-checkbox *,.rc-button-default,.rc-button-default *,.rc-imageselect-candidates,.rc-imageselect-candidates *,.rc-imageselect-desc,.rc-imageselect-desc *

Create a complete filter rules file

It's possible to create a complete filter file. For this, it's necessary that the file begins with the following code which contains the metadata of the filter file:

#! Page Shadow Filter 1.0
#! Name: Filter title
#! Homepage: https://www.filterhomepage.com
#! Sourcename: Website source name (website name or other)
#! Version: Filter version
#! License: License
#! Expires: Number of days for the user-side filter cache to expire, followed by an automatic update
#! Description: Filter description

You must then write a filter rule per line.