You're not currently signed in.

How Jifty handles CSS and JavaScript

Jifty makes extensive use of CSS definitions and JavaScript. Like many things, building all those definitions incorporates a lot of magic behind the scenes. The standard header file web/templates/_elements/header inside the Jifty-provided template files simply uses the constructions Jifty->web->include_css or Jifty->web->include_javascript to produce all required things into the generated HTML page. However, when browsing the HTML-code for a generated page offers a huge list of JavaScript files to be included. Also the question might arise on how to enhance CSS definitions.

Both, CSS and JavaScript generation have a lot of things in common regarding their generation:

  • When in develop mode, the generated things are almost static. In case of CSS the static file web/static/css/main.css is included. JavaScripts are included from a predefined array, that is handled inside the Jifty::Web class.

  • If develop mode is turned off, a lot of magic occurs. Depending on the type of resource requested, the methods generate_css or generate_javascript are called. This results in doing some traversal, collecting all required things, caching the information in the Jifty->web object plus storing an MD5 hash of the stored information. In both cases, the location of the files are set to a non-existing filename inside the web/templates/__jifty/css or web/templates/__jifty/js directories. Both directories only consist of a dhandler (a Mason speciality that enables arbitrary non-existing files to deliver some meaningful result instead of a 404-error). The only thing, the dhandler delivers is the cached data for for required resource.

Collecting CSS

As mentioned above, in case of develop mode is turned off, all CSS resources are collected magically.

  • if the file main.css file exists in your application's directory share/web/static/css, it will be used, otherwise Jifty's default provided main.css file will get used.

  • In both cases, all CSS entries from the found file will get collected, all @import statements will get read, all entries will get concatenated into one stream of CSS instructions.

  • the collection plus a MD5 hash will get stored for retrieval by the dhandler.

Collecting JavaScripts

Alike the CSS generation, this only happens if develop mode is turned off. If develop mode is on, a series of <SCRIPT> tags is generated.

  • During construction of the Jift::Web object, an internal array variable that might get accessed with Jifty->web->javascript_libs is prefilled with a series of required JavaScript include files to get used.

  • Every required JavaScript file will be searched in your application's directory share/web/static/js or Jifty's directory web/static/js.

  • all collected files are concatenated (leaving a comment for every file getting processed) into one huge !JavaScript stream.

  • this concatenation plus a MD5 hash will get stored for retrieval by the dhandler.

Extending CSS

Jifty maintains two initially empty files, app-base.css and "app.css" that may get "overloaded" by simply providing these files in an application's share/web/static/css directory.

These two files will get included in different order, app-base.css being the very first and app.css getting included very late in the CSS construction process.

This means that general definitions that should apply to all subsequently encountered styles could easily get done in app-base.css whereas individual redefinitions, expansions or your application's own definitions could go into app.css.

Jifty's own definitions

Jifty provides a series of definitions that are responsible for a good look without any modification. Please note that not all of the used CSS classes are already defined, but they will provide a hook for modification of the general look. Some of the styles are listed below.

  • form_errors, error

    Error messages encountered during validation are displayed inside a <div> tag of class form_errors which initially is not yet defined. Every single error message is marked with a class error.

  • hints, warning, error

    These classes are used for displaying additional information for form fields.

  • form_field, mandatory, argument-$name

    Every form field including its label is packed inside a <div> tag with these classes (mandatory only given if the field is mandatory, of course), where $name is the field's name.

  • preamble

    This section is a <span> tag filled with a form field's preamble content that could contain additional instructions for the user. The content may be set by the preamble accessor method that is available for every Jifty::Web::Form::Field and its successors.

  • widget, button, button_as_link, combobox, combo-text, combo-button, combo-list, date, label, password, submit_button, reset, text, hidden, ajaxvalidation, ajaxcanonicalization, ajaxautocompletes

    These class names are used depending on the type of widget getting rendered.

  • autocomplete

    used for the autocomplete div.

  • toplevel, menu, context_menu, submenu, title, expand

    These classes are used in navigation bars.

  • jifty, results, messages

    These tree CSS classes are used to surround a message block displaying an action's messages after having run an action.

  • message, error, $moniker

    Every single message that is displayed in an action's result box is marked with the message's type plus the action's moniker as a CSS class name.

Extending JavaScript

To extend the JavaScript functions used you simply can:

  • place your own JavaScript file app.js (app is not your application name but the literal 'app'!) in your application's directory share/web/static/js. This file will get processed very late in the chain of includes giving you a chance to override any function you like.

  • create a JavaScript file app_behaviour.js in your application's directory share/web/static/js. See Jifty's default-provided file with the same name for more hints on what to do with it...

  • place any other-named (but not colliding) file in your application's share/web/static/js directory and use the following construct at a central location, preferably in the start method of your own-created application-class.

    Jifty->web->javascript_libs([ @{ Jifty->web->javascript_libs }, "yourJavascriptLib.js" ]);