Documentation

CRM_Core_Resources_CollectionAdderTrait

Class CRM_Core_Resources_CollectionTrait

This trait is a building-block for creating classes which maintain a list of resources. It defines a set of helper functions which provide syntactic sugar for calling the add() method. It implements most of the CollectionAdderInterface.

Methods

add() : array<string|int, mixed>: Add an item to the collection.
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
findCreateSettingSnippet() : array<string|int, mixed>: Locate the 'settings' snippet.
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.

add()

Add an item to the collection.


    public
    abstract                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).

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

findCreateSettingSnippet()

Locate the 'settings' snippet.


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

Parameters

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

Return values

array<string|int, mixed>

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>

CRM_Core_Resources_CollectionAdderTrait

Tags

Table of Contents

Methods

Methods

add()

Parameters

Tags

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

addString()

Parameters

Tags

Return values

addStyle()

Parameters

Tags

Return values

addStyleFile()

Parameters

Tags

Return values

addStyleUrl()

Parameters

Tags

Return values

addVars()

Parameters

Tags

Return values

findCreateSettingSnippet()

Parameters

Tags

Return values

mergeSettingOptions()

Parameters

Return values

mergeSettings()

Parameters

Return values

mergeStandardOptions()