Documentation

CRM_Core_Resources
in package

CRM

implements CRM_Core_Resources_CollectionAdderInterface uses CRM_Core_Resources_CollectionAdderTrait

This class facilitates the loading of resources such as JavaScript files and CSS files.

Any URLs generated for resources may include a 'cache-code'. By resetting the cache-code, one may force clients to re-download resource files (regardless of any HTTP caching rules).

TODO: This is currently a thin wrapper over CRM_Core_Region. We should incorporte services for aggregation, minimization, etc.

Interfaces

CRM_Core_Resources_CollectionAdderInterface: The collection-adder interface provides write-only support for a collection.

Constants

DEFAULT_REGION = 'page-footer'
DEFAULT_WEIGHT = 0

Properties

$ajaxPopupsEnabled : bool: Are ajax popup screens enabled.
$addedBundles : array<string|int, mixed>: Any bundles that have been added.
$addedCoreResources : array<string|int, mixed>: Added core resources.
$addedSettings : array<string|int, mixed>: Added settings.
$cacheCode : string: A value to append to JS/CSS URLs to coerce cache resets.
$cacheCodeKey : string: The name of a setting which persistently stores the cacheCode.
$paths : Paths
$_singleton : CRM_Core_Resources: We don't have a container or dependency-injection, so use singleton instead
$extMapper : CRM_Extension_Mapper
$strings : CRM_Core_Resources_Strings

Methods

__construct() : mixed: Construct a resource manager.
add() : array<string|int, mixed>: Add an item to the collection.
addBundle() : static: Assimilate all the resources listed in a bundle.
addCacheCode() : string
addCoreResources() : CRM_Core_Resources: This adds CiviCRM's standard css and js to the specified region of the document.
addCoreStyles() : CRM_Core_Resources: This will add CiviCRM's standard CSS
addMarkup() : static: Add an HTML blob.
addModule() : static: Add an ECMAScript module (ESM) to the current page (<SCRIPT TYPE=MODULE>).
addModuleFile() : static: Add an ECMAScript Module (ESM) from file to the current page (<SCRIPT TYPE=MODULE SRC=...>).
addModuleUrl() : static: Add an ECMAScript Module (ESM) by URL to the current page (<SCRIPT TYPE=MODULE SRC=...>).
addPermissions() : static: Export permission data to the client to enable smarter GUIs.
addScript() : static: Add a JavaScript file to the current page using <SCRIPT SRC>.
addScriptFile() : static: Add a JavaScript file to the current page using <SCRIPT SRC>.
addScriptUrl() : static: Add a JavaScript URL to the current page using <SCRIPT SRC>.
addSetting() : static: Add JavaScript variables to the root of the CRM object.
addSettingsFactory() : static: Add JavaScript variables to the global CRM object via a callback function.
addString() : static: Add translated string to the js CRM object.
addStyle() : static: Add a CSS content to the current page using <STYLE>.
addStyleFile() : static: Add a CSS file to the current page using <LINK HREF>.
addStyleUrl() : static: Add a CSS file to the current page using <LINK HREF>.
addVars() : static: Add JavaScript variables to CRM.vars
filterMinify() : string: Determine the minified file name.
findCreateSettingSnippet() : array<string|int, mixed>: Locate the 'settings' snippet.
flushStrings() : CRM_Core_Resources: Flushes cached translated strings.
getCacheCode() : string
getL10nJsParams() : array<string|int, mixed>: Get the params used to render crm-l10n.js Gets called above the caching layer and then used in the render function below
getPath() : bool|string: Determine file path of a resource provided by an extension.
getSettings() : mixed: Helper fn for addSettingsFactory.
getStrings() : CRM_Core_Resources_Strings
getUrl() : mixed: Determine public URL of a resource provided by an extension.
glob() : array<string|int, mixed>: Evaluate a glob pattern in the context of a particular extension.
isAjaxMode() : bool
isFullyFormedUrl() : bool: Checks if the given URL is fully-formed
mergeSettingOptions() : array<string|int, mixed>: Given the "$options" for "addSetting()" (etal), normalize the contents and potentially add more.
mergeSettings() : array<string|int, mixed>
mergeStandardOptions() : array<string|int, mixed>: Given the "$options" for "addScriptUrl()" (etal), normalize the contents and potentially add more.
renderL10nJs() : mixed: Create dynamic script for localizing js widgets.
renderMenubarStylesheet() : mixed
resetCacheCode() : CRM_Core_Resources
setCacheCode() : CRM_Core_Resources
singleton() : CRM_Core_Resources: Get or set the single instance of CRM_Core_Resources.
getEntityRefMetadata() : array<string|int, mixed>: Provide a list of available entityRef filters.
getQuickAddForms() : array<string|int, mixed>: Gets links to "Quick Add" forms, for use in Autocomplete widgets
getSettingRegion() : CRM_Core_Region

DEFAULT_REGION


    public
        mixed
    DEFAULT_REGION
    = 'page-footer'

DEFAULT_WEIGHT


    public
        mixed
    DEFAULT_WEIGHT
    = 0

$ajaxPopupsEnabled

Are ajax popup screens enabled.


    public
        bool
    $ajaxPopupsEnabled

$addedBundles

Any bundles that have been added.


    protected
        array<string|int, mixed>
    $addedBundles
     = []

Format is ($bundleName => bool).

$addedCoreResources

Added core resources.


    protected
        array<string|int, mixed>
    $addedCoreResources
     = []

Format is ($regionName => bool).

$addedSettings

Added settings.


    protected
        array<string|int, mixed>
    $addedSettings
     = []

Format is ($regionName => bool).

$cacheCode

A value to append to JS/CSS URLs to coerce cache resets.


    protected
        string
    $cacheCode
     = \NULL

$cacheCodeKey

The name of a setting which persistently stores the cacheCode.


    protected
        string
    $cacheCodeKey
     = \NULL

$paths


    protected
        Paths
    $paths

$_singleton

We don't have a container or dependency-injection, so use singleton instead


    private
    static    CRM_Core_Resources
    $_singleton

$extMapper


    private
        CRM_Extension_Mapper
    $extMapper
     = \NULL

$strings


    private
        CRM_Core_Resources_Strings
    $strings
     = \NULL

__construct()

Construct a resource manager.


    public
                    __construct(CRM_Extension_Mapper $extMapper, CRM_Core_Resources_Strings $strings[, string|null $cacheCodeKey = NULL ]) : mixed

Parameters

$extMapper : CRM_Extension_Mapper: Map extension names to their base path or URLs.
$strings : CRM_Core_Resources_Strings: JS-localization cache.
$cacheCodeKey : string|null = NULL: Random code to append to resource URLs; changing the code forces clients to reload resources

add()

Add an item to the collection.


    public
                    add(array<string|int, mixed> $snippet) : array<string|int, mixed>

Parameters

$snippet : array<string|int, mixed>

Return values

array<string|int, mixed> —

The full/computed snippet (with defaults applied).

addBundle()

Assimilate all the resources listed in a bundle.


    public
                    addBundle(iterable<string|int, mixed>|string|CRM_Core_Resources_Bundle $bundle) : static

Parameters

$bundle : iterable<string|int, mixed>|string|CRM_Core_Resources_Bundle: Either bundle object, or the symbolic name of a bundle, or a list of bundles. Note: For symbolic names, the bundle must be a container service ('bundle.FOO').

Return values

static

addCacheCode()


    public
                    addCacheCode(string $url) : string

Parameters

$url : string

Return values

string

addCoreResources()

This adds CiviCRM's standard css and js to the specified region of the document.


    public
                    addCoreResources([string $region = 'html-header' ]) : CRM_Core_Resources

It will only run once.

Parameters

$region : string = 'html-header'

Return values

CRM_Core_Resources

addCoreStyles()

This will add CiviCRM's standard CSS


    public
                    addCoreStyles([string $region = 'html-header' ]) : CRM_Core_Resources

Parameters

$region : string = 'html-header'

Return values

CRM_Core_Resources

addMarkup()

Add an HTML blob.


    public
                    addMarkup(string $markup, array<string|int, mixed> ...$options) : static

Ex: addMarkup('

Hello world!

', ['weight' => 123]);

Parameters

$markup : string: HTML code.
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addMarkup(string $code, int $weight, string $region).

Return values

static

addModule()

Add an ECMAScript module (ESM) to the current page (<SCRIPT TYPE=MODULE>).


    public
                    addModule(string $code, array<string|int, mixed> ...$options) : static

Ex: addModule('alert("Hello world");', ['weight' => 123]);

Parameters

$code : string: JavaScript source code.
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addModule(string $code, int $weight, string $region).

Return values

static

addModuleFile()

Add an ECMAScript Module (ESM) from file to the current page (<SCRIPT TYPE=MODULE SRC=...>).


    public
                    addModuleFile(string $ext, string $file, array<string|int, mixed> ...$options) : static

Ex: addModuleFile('myextension', 'myscript.js', ['weight' => 123]);

Parameters

$ext : string: Extension name; use 'civicrm' for core.
$file : string: File path -- relative to the extension base dir.
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addModuleFile(string $code, int $weight, string $region, mixed $translate).

Return values

static

addModuleUrl()

Add an ECMAScript Module (ESM) by URL to the current page (<SCRIPT TYPE=MODULE SRC=...>).


    public
                    addModuleUrl(string $url, array<string|int, mixed> ...$options) : static

Ex: addModuleUrl('http://example.com/foo.js', ['weight' => 123])

Parameters

$url : string
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addModuleUrl(string $url, int $weight, string $region).

Return values

static

addPermissions()

Export permission data to the client to enable smarter GUIs.


    public
                    addPermissions(string|iterable<string|int, mixed> $permNames) : static

Parameters

$permNames : string|iterable<string|int, mixed>: List of permission names to check/export.

Return values

static

addScript()

Add a JavaScript file to the current page using <SCRIPT SRC>.


    public
                    addScript(string $code, array<string|int, mixed> ...$options) : static

Ex: addScript('alert("Hello world");', ['weight' => 123]);

Parameters

$code : string: JavaScript source code.
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addScript(string $code, int $weight, string $region).

Return values

static

addScriptFile()

Add a JavaScript file to the current page using <SCRIPT SRC>.


    public
                    addScriptFile(string $ext, string $file, array<string|int, mixed> ...$options) : static

Ex: addScriptFile('myextension', 'myscript.js', ['weight' => 123]);

Parameters

$ext : string: Extension name; use 'civicrm' for core.
$file : string: File path -- relative to the extension base dir.
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addScriptFile(string $code, int $weight, string $region, mixed $translate).

Return values

static

addScriptUrl()

Add a JavaScript URL to the current page using <SCRIPT SRC>.


    public
                    addScriptUrl(string $url, array<string|int, mixed> ...$options) : static

Ex: addScriptUrl('http://example.com/foo.js', ['weight' => 123])

Parameters

$url : string
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addScriptUrl(string $url, int $weight, string $region).

Return values

static

addSetting()

Add JavaScript variables to the root of the CRM object.


    public
                    addSetting(array<string|int, mixed> $settings, array<string|int, mixed> ...$options) : static

This function is usually reserved for low-level system use. Extensions and components should generally use addVars instead.

Parameters

$settings : array<string|int, mixed>: Data to export.
$options : array<string|int, mixed>: Not used. Positional equivalence: addSetting(array $settings, string $region).

Return values

static

addSettingsFactory()

Add JavaScript variables to the global CRM object via a callback function.


    public
                    addSettingsFactory(callable $callable) : static

Parameters

$callable : callable

Return values

static

addString()

Add translated string to the js CRM object.


    public
                    addString(string|array<string|int, mixed> $text[, string|null $domain = 'civicrm' ]) : static

It can then be retrived from the client-side ts() function Variable substitutions can happen from client-side

Note: this function rarely needs to be called directly and is mostly for internal use. See CRM_Core_Resources::addScriptFile which automatically adds translated strings from js files

Simple example: // From php: CRM_Core_Resources::singleton()->addString('Hello'); // The string is now available to javascript code i.e. ts('Hello');

Example with client-side substitutions: // From php: CRM_Core_Resources::singleton()->addString('Your %1 has been %2'); // ts() in javascript works the same as in php, for example: ts('Your %1 has been %2', {1: objectName, 2: actionTaken});

NOTE: This function does not work with server-side substitutions (as this might result in collisions and unwanted variable injections) Instead, use code like: CRM_Core_Resources::singleton()->addSetting(array('myNamespace' => array('myString' => ts('Your %1 has been %2', array(subs))))); And from javascript access it at CRM.myNamespace.myString

Parameters

$text : string|array<string|int, mixed>
$domain : string|null = 'civicrm'

Return values

static

addStyle()

Add a CSS content to the current page using <STYLE>.


    public
                    addStyle(string $code, array<string|int, mixed> ...$options) : static

Ex: addStyle('p { color: red; }', ['weight' => 100]);

Parameters

$code : string: CSS source code.
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addStyle(string $code, int $weight, string $region).

Return values

static

addStyleFile()

Add a CSS file to the current page using <LINK HREF>.


    public
                    addStyleFile(string $ext, string $file, array<string|int, mixed> ...$options) : static

Ex: addStyleFile('myextension', 'mystyles.css', ['weight' => 100]);

Parameters

$ext : string: Extension name; use 'civicrm' for core.
$file : string: File path -- relative to the extension base dir.
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addStyle(string $code, int $weight, string $region).

Return values

static

addStyleUrl()

Add a CSS file to the current page using <LINK HREF>.


    public
                    addStyleUrl(string $url, array<string|int, mixed> ...$options) : static

Ex: addStyleUrl('http://example.com/foo.css', ['weight' => 100]);

Parameters

$url : string
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addStyleUrl(string $code, int $weight, string $region).

Return values

static

addVars()

Add JavaScript variables to CRM.vars


    public
                    addVars(string $nameSpace, array<string|int, mixed> $vars, array<string|int, mixed> ...$options) : static

Example: From the server: CRM_Core_Resources::singleton()->addVars('myNamespace', array('foo' => 'bar')); Access var from javascript: CRM.vars.myNamespace.foo // "bar"

Parameters

$nameSpace : string: Usually the name of your extension.
$vars : array<string|int, mixed>: Data to export.
$options : array<string|int, mixed>: Open-ended list of key-value options. See CollectionInterface docs. Positional equivalence: addVars(string $namespace, array $vars, string $region).

Return values

static

filterMinify()

Determine the minified file name.


    public
                    filterMinify(string $ext, string $file) : string

Parameters

$ext : string
$file : string

Return values

string —

An updated $fileName. If a minified version exists and is supported by system policy, the minified version will be returned. Otherwise, the original.

findCreateSettingSnippet()

Locate the 'settings' snippet.


    public
                &    findCreateSettingSnippet([array<string|int, mixed> $options = [] ]) : array<string|int, mixed>

Parameters

$options : array<string|int, mixed> = []

Return values

array<string|int, mixed>

flushStrings()

Flushes cached translated strings.


    public
                    flushStrings() : CRM_Core_Resources

Return values

CRM_Core_Resources

getCacheCode()


    public
                    getCacheCode() : string

Return values

string

getL10nJsParams()

Get the params used to render crm-l10n.js Gets called above the caching layer and then used in the render function below


    public
            static        getL10nJsParams() : array<string|int, mixed>

Return values

array<string|int, mixed>

getPath()

Determine file path of a resource provided by an extension.


    public
                    getPath(string $ext[, string|null $file = NULL ]) : bool|string

Parameters

$ext : string: extension name; use 'civicrm' for core.
$file : string|null = NULL: file path -- relative to the extension base dir.

Return values

bool|string —

full file path or FALSE if not found

getSettings()

Helper fn for addSettingsFactory.


    public
                    getSettings([mixed $region = NULL ]) : mixed

Parameters

$region : mixed = NULL

getStrings()


    public
                    getStrings() : CRM_Core_Resources_Strings

Return values

CRM_Core_Resources_Strings

getUrl()

Determine public URL of a resource provided by an extension.


    public
                    getUrl(string $ext[, string $file = NULL ][, bool $addCacheCode = FALSE ]) : mixed

Parameters

$ext : string: extension name; use 'civicrm' for core.
$file : string = NULL: file path -- relative to the extension base dir.
$addCacheCode : bool = FALSE

glob()

Evaluate a glob pattern in the context of a particular extension.


    public
                    glob(string $ext, string|array<string|int, mixed> $patterns[, null|int $flags = 0 ]) : array<string|int, mixed>

Parameters

$ext : string: Extension name; use 'civicrm' for core.
$patterns : string|array<string|int, mixed>: Glob pattern; e.g. "*.html".
$flags : null|int = 0: See glob().

Return values

array<string|int, mixed> —

List of matching files, relative to the extension base dir.

isAjaxMode()


    public
            static        isAjaxMode() : bool

Return values

bool —

is this page request an ajax snippet?

isFullyFormedUrl()

Checks if the given URL is fully-formed


    public
            static        isFullyFormedUrl(string $url) : bool

Parameters

$url : string

Return values

bool

mergeSettingOptions()

Given the "$options" for "addSetting()" (etal), normalize the contents and potentially add more.


    public
            static        mergeSettingOptions(array<string|int, mixed> $splats[, array<string|int, mixed> $defaults = [] ]) : array<string|int, mixed>

Parameters

$splats : array<string|int, mixed>

A list of options, as represented by the splat mechanism ("...$options"). This may appear in one of two ways:

New (String Index): as in addFoo($foo, array $options)
Old (Numeric Index): as in addFoo($foo, int $weight = X, string $region = Y, bool $translate = X)

$defaults : array<string|int, mixed> = []

List of values to merge into $options.

Return values

array<string|int, mixed>

mergeSettings()


    public
            static        mergeSettings(array<string|int, mixed> $settings, array<string|int, mixed> $additions) : array<string|int, mixed>

Parameters

$settings : array<string|int, mixed>
$additions : array<string|int, mixed>

Return values

array<string|int, mixed> —

combination of $settings and $additions

mergeStandardOptions()

Given the "$options" for "addScriptUrl()" (etal), normalize the contents and potentially add more.


    public
            static        mergeStandardOptions(array<string|int, mixed> $splats[, array<string|int, mixed> $defaults = [] ]) : array<string|int, mixed>

Parameters

$splats : array<string|int, mixed>

A list of options, as represented by the splat mechanism ("...$options"). This may appear in one of two ways:

New (String Index): as in addFoo($foo, array $options)
Old (Numeric Index): as in addFoo($foo, int $weight = X, string $region = Y, bool $translate = X)

$defaults : array<string|int, mixed> = []

List of values to merge into $options.

Return values

array<string|int, mixed>

renderL10nJs()

Create dynamic script for localizing js widgets.


    public
            static        renderL10nJs(GenericHookEvent $e) : mixed

Params come from the function above

Parameters

$e : GenericHookEvent

renderMenubarStylesheet()


    public
            static        renderMenubarStylesheet(GenericHookEvent $e) : mixed

Parameters

$e : GenericHookEvent

resetCacheCode()


    public
                    resetCacheCode() : CRM_Core_Resources

Return values

CRM_Core_Resources

setCacheCode()


    public
                    setCacheCode(mixed $value) : CRM_Core_Resources

Parameters

$value : mixed

Return values

CRM_Core_Resources

singleton()

Get or set the single instance of CRM_Core_Resources.


    public
            static        singleton([CRM_Core_Resources|null $instance = NULL ]) : CRM_Core_Resources

Parameters

$instance : CRM_Core_Resources|null = NULL: New copy of the manager.

Return values

CRM_Core_Resources

getEntityRefMetadata()

Provide a list of available entityRef filters.


    protected
            static        getEntityRefMetadata() : array<string|int, mixed>

Return values

array<string|int, mixed>

getQuickAddForms()

Gets links to "Quick Add" forms, for use in Autocomplete widgets


    private
            static        getQuickAddForms(int|null $cid) : array<string|int, mixed>

Parameters

$cid : int|null

Return values

array<string|int, mixed>

getSettingRegion()


    private
                    getSettingRegion([string|null $region = NULL ]) : CRM_Core_Region

Parameters

$region : string|null = NULL: Optional request for a specific region. If NULL/omitted, use global default.

Return values

CRM_Core_Region

CRM_Core_Resources in package CRM implements CRM_Core_Resources_CollectionAdderInterface uses CRM_Core_Resources_CollectionAdderTrait

Tags

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

DEFAULT_REGION

DEFAULT_WEIGHT

Properties

$ajaxPopupsEnabled

$addedBundles

$addedCoreResources

$addedSettings

$cacheCode

$cacheCodeKey

$paths

$_singleton

$extMapper

$strings

Methods

__construct()

Parameters

add()

Parameters

Tags

Return values

addBundle()

Parameters

Return values

addCacheCode()

Parameters

Return values

addCoreResources()

Parameters

Return values

addCoreStyles()

Parameters

Return values

addMarkup()

Parameters

Tags

Return values

addModule()

Parameters

Tags

Return values

addModuleFile()

Parameters

Tags

Return values

addModuleUrl()

Parameters

Tags

Return values

addPermissions()

Parameters

Tags

Return values

addScript()

Parameters

Tags

Return values

addScriptFile()

Parameters

Tags

Return values

addScriptUrl()

Parameters

Tags

Return values

addSetting()

Parameters

Tags

Return values

addSettingsFactory()

Parameters

Tags

Return values

CRM_Core_Resources
in package

CRM

implements CRM_Core_Resources_CollectionAdderInterface uses CRM_Core_Resources_CollectionAdderTrait