func

Syntax

func: (function name) [par1 [par2 [par3 etc.]]] [every (time)] [after (time)][, (function name)...];

function name = Name of the JavaScript function to call. This should be in the window scope and accessible as a function.

par1, par2, par3,. etc. = a space-delimited list of parameters that you want a function to receive. Ensure substituted variables are enclosed when needed in double-quotes, eg. "{@data-ref}", so that spaces within the variable contents are handled correctly in the command itself. All parameters are available in the function in an array as the second parameter in your receiving function. The first parameter received by your function will always contain an object of useful variables related to the event - see the table below for a full list and the example at the bottom of the page for more details.

A further note on parameters: All variables are substituted into action commands internally before actually reaching the action command. Because of this, ensure all string variables have double-quotes around them where needed when being passed into action commands. Otherwise you may find variables get split by the space characters and come over into the receiving function as multiple parameters. Just always put quotes around string variables to solve this.

This command will run an external JavaScript function, and pass a single object to it as a parameter, which will contain information on the event that triggered the function call. The function call is synchronous.

The purpose of this command is to enable you to perform actions externally to Active CSS in a custom function that you have written, in response to a Active CSS event.

The func command is used like this:

#myButton:click {
    func: myExternalFunction;
}

If you need to respond to a boolean result of a function for use in a conditional statement, you should look at "if-func" in the Conditionals documentation section.

Every function call is sent an object variable, which is less scarier than it sounds. In the core it is called "o", which is just shorthand for "object" and less to type. It's not a thing - you can change it to something other than "o" if you want. One character is just a lot less to type when one starts using the variables in the object, so "o" is consistently used throughout the Active CSS core.

Your JavaScript function will accept the o variable like this:

function myExternalFunction(o) {
    console.log('What goodies have you sent me in o?');
    console.log(o);
}

The object ("o" in our case) contains the variables below which you can now use. You can quickly get elements related to the function call, or just ignore them entirely and do your own thing. Write your JavaScript in the usual way outside of Active CSS, to manage state, or call other functions, etc.

Contents of o:

o.actName	The name of the action command that called this function - it will always be "func" here.
o.actPos	The position in the action value, 0, 1, etc. - you can call more than one function if you comma-delimit them.
o.actVal	The full evaluated action value.
o.actValSing	The singular un-evaluated action value that called the function.
o.ajaxObj	If func is called from an afterAjax type of event, this contains the "o" object from the event that triggered the ajax call.
o.activeID	The internal reference to the target selector assigned. You shouldn't ever change this.
o.doc	The document object where the target selector can be found.
o.e	The event object.
o.event	The name of the event.
o.file	The config file where the function call is written.
o.func	The name of the function that was called. It will always be "_aFunc" here.
o.line	The line in the config file where you can find the function call.
o.obj	The event selector element itself, that received the event.
o.origActVal	The full comma delimited un-evaluated action value of the func action command.
o.origSecSel	The name of the target selector this function was called from. If it contains "&" it means the target selector was the event selector.
o.passCond	A space delimited list of any conditionals that were passed.
o.primSel	The name of the event selector. Internally this is called the primary selector.
o.rules	An array of all the action commands and un-evaluated values in the target selector declaration.
o.secSel	The internal target selector reference, which is used internally to locate the target selector with querySelector if necessary. Internally this is called the secondary selector. This is not always a consistent value or object type, and it is more for internal Active CSS use. For referencing the target selector in your function or custom action command, use o.secSelObj, which will always give you the valid target selector element. Remember that classes will get converted to a specific element by the time it reaches an action command. Action commands only occur on a single element and will get run multiple times if a class, tag reference, etc. is used for a target selector.
o.secSelObj	The target selector element itself. Internally this is called the secondary selector.
o.compRef	Internal reference to a shadow DOM host or scoped variables area, if applicable.
o.compDoc	The shadow DOM or scoped component object this event is occurring in, if applicable.
o.component	The name of the component this event is occurring in, if applicable.

Some "o" variables are useful, especially o.secSelObj which contains the target selector element itself.

Target selectors addressed to multiple items will call a function multiple times. Each time it will have a different o.secSelObj.

These variables are similar to the ones that you will have available to you if you have used the "create-command" action command. They are just named a bit differently, to save bytes in the core. "primSel" and "secSel" were the original names of the event selector and target selector respectively in the core.

An example use of the "func" command attached to a cookie consent button could look like this:

#cookieConsentYes:click {
    func: activateGoogleAnalytics;
}

The accompanying external JavaScript function which is kept in a proper JavaScript file and NOT lumped in with your Active CSS config would look like this:

function activateGoogleAnalytics(o) {
    alert('You just called the activateGoogleAnalytics function.');
}

To access a specific variable in your JavaScript you would do something like this:

function myAmazingJavaScriptFunction(o) {
    console.log('The event selector was ' + o.primSel);
}

You access all the event variables in this way. At this point in the event flow, within the function, you can do whatever you want, you can perform your own DOM manipulation, do body scrolling handling which can only be done with JavaScript, send a message to a random iframe, roll-your-own ajax, resize your menu which uses weird calculations that you don't think CSS can handle but probably can, activate Google Analytics after the all-important user consent click - basically whatever you want in the event flow. You can additionally call Active CSS action commands from within your function which means you can also trigger off Active CSS events from within your function.

in the full example below, the exact JavaScript function that is called looks like this. It contains the second parameter containing an array of extra parameters sent to the function:

function myExternalFunction(o, pars) {
    console.log('o:');
    console.log(o);
    console.log('pars:');
    console.log(pars);
    alert('I am in myExternalFunction!');
}

A note on referencing Active CSS variables using the func command

You cannot access Active CSS variables externally in the window scope, so they are not available via the func command. This is an intentional security measure. Active CSS variables can only be accessed from within JavaScript that is placed actually inside the Active CSS config files. Then you can access them after declaring them with the special "vars" command before using them in your JavaScript. See the documentation on regular variables for how to do that.

 

func