Docs4dev
Docs
angularjs / 1.6 / api / ng / service / $scedelegate.html

Improve this Doc View Source $sceDelegate

  1. $sceDelegateProvider
  2. service in module ng

Overview

$sceDelegate is a service that is used by the $sce service to provide Strict Contextual Escaping (SCE) services to AngularJS.

For an overview of this service and the functionnality it provides in AngularJS, see the main page for SCE. The current page is targeted for developers who need to alter how SCE works in their application, which shouldn't be needed in most cases.

AngularJS strongly relies on contextual escaping for the security of bindings: disabling or modifying this might cause cross site scripting (XSS) vulnerabilities. For libraries owners, changes to this service will also influence users, so be extra careful and document your changes.

Typically, you would configure or override the $sceDelegate instead of the $sce service to customize the way Strict Contextual Escaping works in AngularJS. This is because, while the $sce provides numerous shorthand methods, etc., you really only need to override 3 core functions (trustAs, getTrusted and valueOf) to replace the way things work because $sce delegates to $sceDelegate for these operations.

Refer $sceDelegateProvider to configure this service.

The default instance of $sceDelegate should work out of the box with little pain. While you can override it completely to change the behavior of $sce, the common case would involve configuring the $sceDelegateProvider instead by setting your own whitelists and blacklists for trusting URLs used for loading AngularJS resources such as templates. Refer $sceDelegateProvider.resourceUrlWhitelist and $sceDelegateProvider.resourceUrlBlacklist

Usage

$sceDelegate();

Methods

  • trustAs(type, value);

    Returns a trusted representation of the parameter for the specified context. This trusted object will later on be used as-is, without any security check, by bindings or directives that require this security context. For instance, marking a string as trusted for the $sce.HTML context will entirely bypass the potential $sanitize call in corresponding $sce.HTML bindings or directives, such as ng-bind-html. Note that in most cases you won't need to call this function: if you have the sanitizer loaded, passing the value itself will render all the HTML that does not pose a security risk.

    See getTrusted for the function that will consume those trusted values, and $sce for general documentation about strict contextual escaping.

    Parameters

    Param Type Details
    type string

    The context in which this value is safe for use, e.g. $sce.URL, $sce.RESOURCE_URL, $sce.HTML, $sce.JS or $sce.CSS.
    value *

    The value that should be considered trusted.

    Returns

    *

    A trusted representation of value, that can be used in the given context.

  • valueOf(value);

    If the passed parameter had been returned by a prior call to $sceDelegate.trustAs, returns the value that had been passed to $sceDelegate.trustAs.

    If the passed parameter is not a value that had been returned by $sceDelegate.trustAs, it must be returned as-is.

    Parameters

    Param Type Details
    value *

    The result of a prior $sceDelegate.trustAs call or anything else.

    Returns

    *

    The value that was originally provided to $sceDelegate.trustAs if value is the result of such a call. Otherwise, returns value unchanged.

  • getTrusted(type, maybeTrusted);

    Takes any input, and either returns a value that's safe to use in the specified context, or throws an exception.

    In practice, there are several cases. When given a string, this function runs checks and sanitization to make it safe without prior assumptions. When given the result of a $sceDelegate.trustAs call, it returns the originally supplied value if that value's context is valid for this call's context. Finally, this function can also throw when there is no way to turn maybeTrusted in a safe value (e.g., no sanitization is available or possible.)

    Parameters

    Param Type Details
    type string

    The context in which this value is to be used (such as $sce.HTML).
    maybeTrusted *

    The result of a prior $sceDelegate.trustAs call, or anything else (which will not be considered trusted.)

    Returns

    *

    A version of the value that's safe to use in the given context, or throws an exception if this is impossible.

© 2010–2018 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://code.angularjs.org/1.6.9/docs/api/ng/service/$sceDelegate