{"id":251,"date":"2009-01-16T00:21:06","date_gmt":"2009-01-16T06:21:06","guid":{"rendered":"http:\/\/bililite.nfshost.com\/blog\/?p=251"},"modified":"2012-01-16T10:43:24","modified_gmt":"2012-01-16T16:43:24","slug":"jquery-css-parser","status":"publish","type":"post","link":"https:\/\/bililite.com\/blog\/2009\/01\/16\/jquery-css-parser\/","title":{"rendered":"jQuery CSS parser"},"content":{"rendered":"

Updated 2011-02-28; minor bug fix. Thanks, brian<\/a>!<\/p>\r\n

Every time I create or use a jQuery plugin, I realize that the assigning of behaviors to elements on the page is a design decision, not a programming one, and one that should be made by the guy in charge of the CSS, not the guy in charge of the javascript. Even when I'm the same guy, I want to wear each hat separately. But these presentational enhancements are written in javascript and applied in javascript. So my \"presentational\" code is in two different files:<\/p>\r\n

\r\n
style.css<\/dt>
\r\n.gallery a { border: 1px solid green }\r\n<\/code><\/pre><\/dd>\r\n
style.js<\/dt>
\r\n$('.gallery a').lightbox<\/a>({overlayBgColor: '#ddd'});\r\n<\/code><\/pre><\/dd>\r\n<\/dl>\r\n
I could put the presentational javascript in the HTML with $.metadata<\/a> but while that's fine for quick-and-dirty pages, it's evil<\/a> in production since it completely violates the separation of data\/structure\/presentation\/behavior.<\/p>\r\n
As I<\/a> and others<\/a> have noted before, the application of these plugins belongs in the stylesheet, and I finally got it to work:<\/p>\r\n
\r\n
style.css<\/dt>
\r\n.gallery a {\r\n  border: 1px solid green;\r\n  -jquery-lightbox: {overlayBgColor: '#ddd'};\r\n}\r\n<\/code><\/pre><\/dd>\r\n<\/dl>\r\n
and a single call to start it off: $(document).parsecss($.parsecss.jquery)<\/code> .<\/p>\r\n
Download the code<\/a>.<\/p>\r\n
See the demo<\/a>.<\/p>\r\n\r\n
Use<\/h4>\r\n
$(selector).parsecss(callback)<\/code> scans all <style><\/code> and <link type=\"text\/css\"><\/code> elements in $(selector)<\/code> or its descendents, parses each one and passes an object (details below<\/a>) to the callback function. It uses a callback because external stylesheets and @import<\/code> statements need to use AJAX, asynchronously. The parser is smart enough to understand media<\/code> attributes and statements.<\/p>\r\n
The supplied callback is the $.parsecss.jquery<\/code> function. That function finds properties that start with -jquery<\/code> and applies them to the matching elements. Generally, you would want to parse all the stylesheets in the document, $(document)<\/code>, so the simple call is: $(document).parsecss($.parsecss.jquery)<\/code>.<\/p>\r\n
The CSS<\/h4>\r\n
Some jargon: in the stylesheet
\r\n
foo {\r\n  bar: quux;\r\n  -bar-foo: quux-2;\r\n}\r\n\r\nfoo > foo {\r\n  bar: quux 2;\r\n}\r\n<\/code><\/pre>\r\n
foo { bar: quux; -bar-foo: quux-2}<\/code> is a statement, foo<\/code> is a selector, {bar: quux; -bar-foo: quux-2}<\/code> is its CSStext, -bar-foo: quux-2<\/code> is a declaration, -bar-foo<\/code> is its property and quux-2<\/code> is its value.<\/p>\r\n
$.parsecss.jquery<\/code><\/h4>\r\n
$.parsecss.jquery<\/code> is the callback function that implements the custom-jQuery code. It looks for properties that start with -jquery<\/code>. If the property is -jquery<\/code> alone, then it executes the value as a javascript statement for each matched element, $(selector).each(Function(value))<\/code>. For example:<\/p>\r\n
span.important {\r\n  -jquery: $(this).append('<span>I am important<\/span>')\r\n}<\/code><\/pre>\r\n
executes<\/p>\r\n
$('span.important').each(function() {$(this).append('<span>I am important!<\/span>')})<\/code><\/pre>\r\n
If the property is -jquery-show<\/code> or -jquery-hide<\/code>, then the normal show() and hide() are overridden for the matched elements to use the value as the arguments. It will recognize plugins and jQuery UI effects<\/a>. Examples (see below<\/a> how it parses the arguments):<\/p>\r\n
\r\na {\r\n  -jquery-show: fast; \/* $('a').show()<\/code> does $('a').show('fast')<\/code> *\/\r\n  -jquery-show: fadeIn 2000 \/* $('a').show()<\/code> does $('a').fadeIn(2000)<\/code> *\/\r\n  -jquery-show: fold {size: 5} slow \/* $('a').show()<\/code> does $('a').show('fold', {size: 5}, 'slow')<\/code> *\/\r\n  -jquery-hide: explode fast \/* $('a').hide()<\/code> does $('a').hide('explode', {}, 'fast')<\/code> It's smart enough to know that jQuery UI effects need an options object inserted *\/\r\n}<\/code><\/pre>\r\n
Using hide()<\/code> or show()<\/code> with any arguments overrides the CSS-imposed functions.<\/p>\r\n
Otherwise, if the property matches the regular expression \/-jquery-(.*)\/<\/code> then the (.*) is taken as a plugin name and the value is used for the arguments (see below<\/a> how it parses the arguments):<\/p>\r\n
.gallery a {\r\n  -jquery-lightbox: {overlayBgColor: '#ddd'}\r\n}<\/code><\/pre>\r\n
executes<\/p>\r\n
$('.gallery a').lightbox({overlayBgColor: '#ddd'});<\/code><\/pre>\r\n
Valid CSS?<\/h4>\r\n
Does including the -jquery<\/code> properties make the CSS invalid? Sort of. The easy answer is \"Who cares?\" \r\nThe CSS syntax specifies<\/a> that 
User agents must handle unexpected tokens encountered while parsing a declaration by reading until the end of the declaration, while observing the rules for matching pairs of (), [], {}, \"\", and ''<\/blockquote>\r\nThat means that the extensions described here will never cause errors in interpreting the rest of the CSS. Also, the specification says\r\n
Keywords and property names beginning with -' or '_' are reserved for vendor-specific extensions.<\/blockquote>\r\nSo, -jquery-show<\/code>, while not valid, is \"expected\" in real-life CSS, just like -moz-border-radius<\/code>.<\/p>\r\n
But, some people want CSS that passes the validator<\/a>. I adopted a solution similar to Microsoft's conditional comments<\/a>. Text surrounded by \/*@<\/code> and *\/<\/code> will be parsed by the parser despite being ignored by the browser.<\/p>\r\n
span.important {\r\n      font-weight: bold;\r\n\/*@   -jquery-after: '<span>!!!<\/span>'; *\/ \/* \"hide\" the jQuery CSS in the comments *\/\r\n}<\/code><\/pre>\r\n
$.livequery<\/code><\/h4>\r\n
What makes the combination of CSS and javascript so powerful is that CSS is \"live\": changes in the DOM are immediately rendered on the page (this is why Microsoft, when they invented it, called it DHTML<\/a>—Dynamic HTML). If the stylesheet says .important { font-weight: bold; color: red }<\/code> then running $('#x').addClass('important')<\/code> changes the text to red and bold. In addition, $('#x').removeClass('important')<\/code> changes the text back. The browser keeps track of all the elements and the selector in the CSS, and when an element starts to match the CSS is applied, and when it no longer matches, the browser knows how to \"undo\" the styling.<\/p>\r\n
jQuery plugins can't do this. The javascript is run at $(document).ready<\/code>, applied if the elements match at that moment, and that's it. This makes it much less useful, especially for AJAX-y sites that are constantly changing their elements.<\/p>\r\n
Enter Brandon Aaron's $.livequery<\/code> plugin<\/a>. It keeps track of the selectors used and overrides all the plugins that modify the DOM, and re-applies the javascript if need be. It also allows you to specify an \"unmatched\" function<\/a> that will be run when the element no longer matches. Obviously, you or the plugin programmer has to provide the \"undo\" ability; there's no way for $.livequery<\/code> to know how to do that.<\/p>\r\n
If $.livequery<\/code> is available, $.parsecss<\/code> can use it. Separate the two parts (match code\/unmatch code) with a !<\/code> (the exclamation point implies \"not\"):<\/p>\r\n
.important {\r\n  -jquery-css: font-weight bold ! font-weight normal ;\r\n}\r\n\/* yes, in real life you'd do font-weight: bold;  and not rely on javascript *\/\r\n<\/code><\/pre>\r\n
You can leave either side of the !<\/code> blank:<\/p>\r\n
.gallery a {\r\n  -jquery-lightbox: {overlayBgColor: '#ddd'} ! ; \/* the '!' means we'll use livequery *\/\r\n  -jquery-unbind: ! click; \/* remove the click handler when the element no longer matches\r\n}\r\n<\/code><\/pre>\r\n
Some notes on $.livequery<\/code>:<\/p>\r\n