Event syntax
How to use events
All events must be prefixed by a colon and always appear at the end of the event selector, like this:
#myDiv:click {
... do something
}You can comma-separate events, like this:
#myDiv:click, #myDiv2:click, .mainContent .someDivs:mouseover {
... do something
}Internally, only one event is set up as an event listener. When an element receives an event, Active CSS looks to see if the event matches something in the config. If it finds a match, it runs the event on that particular element.
Although the syntax in Active CSS looks very similar to CSS, the way it is used is fundamentally different.
To compare a difference between CSS and Active CSS, CSS will apply all styles to a class selector at the same time as shown below:
.menuItem {
background-color: #fff;
}So all elements with the class "menuItem" get the background-color of #fff.
But in Active CSS, the event only runs on the particular node that receives the event:
For example:
.menuItem:click {
add-class: .selected;
}In that example, the add-class command will only run on the element that actually receives the click event. So it won't run on all elements that have the class "menuItem". It will only run on the element that receives the click event that has the class "menuItem".
You don't have to worry about redeclaring event listeners when you add new elements to the page, as Active CSS works dynamically. The config will always run as expected and work with the latest DOM contents. This is very useful, as you don't have to worry about redeclaring event listeners when elements come back onto a page, which you would have to do in native JavaScript if you were assigning events to specific elements.
Technical notes
You can write Active CSS events for the click event, mouseover event, in fact, ALL DOM EVENTS.
See here for a list of the basic DOM events you can use:
https://developer.mozilla.org/en-US/docs/Web/Events
if the event is a valid DOM event that follows regular event listener rules, it will work in Active CSS. It will not work with non-DOM web APIs that do not bubble up to the window or document.body nodes or that do not apply to DOM nodes or elements.
For shadow DOMs, it follows the standard rules of shadow DOM event bubbling. If you are not sure what those are, don't worry about it :) You should check out shadow DOM event handling on the interwebs. We might add some docs on that later on.
Internally there is a very permissive approach to event handling. It will literally run anything. Active CSS will add a window event listener to every new type of event found in the config, but only do it once for the window object, so there is actually only ever one "physical" event listener per event. If an event is not a valid event in your config, nothing will happen.
Having an extremely flexible approach to event handling has several benefits:
- You can play around with new events as they get developed by the browser manufacturer.
- We don't have to maintain a list of all possible browser events in the core, which means the core size is smaller.
- Any external synthetic events you create can be used with Active CSS. This is an advanced JavaScript technique and most people won't ever need to use this for regular websites. See here for more information on synthetic events: https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events
As developers of Active CSS and being just regular website builders, we have not tried all the DOM events available, so we are sure the potential of using Active CSS with all the different possible events has yet to be fully realized. It is unlikely most people will need all the events that are out there in the browsers. The browser guys who work tirelessly to build JavaScript APIs include a lot of new things in new releases, and unless you monitor the releases closely it is easy to miss the newer programming possibilities, let alone actually try them out in production projects.
Please do let us know if you do anything useful with a little known event, and don't see it documented anywhere clearly, and we'll put you on our website somewhere and highlight what you did or recommend it as a practice for a certain scenario.
Troubleshooting - Safari click events not working
This isn't particularly an Active CSS problem - it's just a thing with Safari and click events - but it's worth a mention. You may find your click events work on every other browser except Safari.
A possible solution is to put onclick="void(0);" into the body tag. Ie. <body onclick="void(0);" etc... >
We haven't put this solution into the core as this is a browser quirk and the solution is majorly hack, and really it is up to the programmer to decide what to do in this case. It does the job. There may be a better solution out there. This should fix the problem though should you run into it.
Noticeable delay on click events on mobile
Don't panic! Active CSS is not slow on mobile. This is another mobile browser quirk probably brought about due to the browser developers sorting out touch/pinch/zoom events, and all that sort of stuff from the old days. You will find that there is no delay on "a" tags, but there can sometimes be a delay on "div" and other tags. The solution is to either make your website un-zoomable, or make all your elements "a" tags. The first option is possibly more practical, although not so accessibility-friendly.
The full solution is on this page: https://developers.google.com/web/updates/2013/12/300ms-tap-delay-gone-away
Troubleshooting - Other events not working
Again, this is not really an Active CSS issue. You would also run into this with native JavaScript events that you set up. Sometimes a mouseover or click event does not fire and it leaves you puzzled. In this scenario there is still an event firing, but it is not firing on the element that you are expecting. If you right-click on the element in question and go to the browser element inspector, it will highlight the element that is actually receiving the event. This should give you a clue.
Active CSS does not drill down into multiple child elements to set off events - it will follow the DOMs natural hierarchy for its internal bubbling upwards through the parent nodes. It follows the native path of bubbling at all times. Hence this is why the element is not being touched. It is responding higher up the DOM tree.
You could change the config to trigger on the element that is actually receiving the event. Often that is the quickest fix. If you are finding that this sort of thing is happening a lot due to lots of serious CSS tweaking, you might want to get your CSS into a more finished state before writing your events, to save yourself some time.
Alternatively, if an element is in the way and it wouldn't make sense to change the config, to stop that element picking up the event, you can use CSS "pointer-events: none;" on that element, which will disable events for that element and its content. You would need to then use CSS "pointer-events: auto;" on the valid target element inside so that events can be received on it.
Check out CSS pointer-events on the interwebs for more info.