Theming

Themes are what dictate the front-end style and functionality of your LiveWhale-powered website or calendar. You should be familiar with CSS, JavaScript, and HTML, and have SFTP access to the server in order to work with themes.

Your site will have at least two—and possibly many—themes:

  • The core theme ships with LiveWhale and contains all the basics, including default widget and calendar functionality. You should never edit the core theme, as your changes will be overwritten in the next upgrade. It is located at /livewhale/theme/core/.
  • The global theme is where most of your customizations should go. It is located at /_ingredients/themes/global/ and is used to override anything from the core theme (more on overriding in a moment).
  • Unlimited other themes you can create inside /_ingredients/themes/my-theme/ and use them on specific pages by adding <xphp var="theme">my-theme</xphp\> to the page, typically in the <head>. Note that theme names are case-sensitive.

Theme Inheritance

For every resource (CSS, JS, or calendar template) that LiveWhale loads, it will first check in the current theme (global or my-theme, if you have one set). If none exists there, it will then fallback to using that same file in the core theme.

Every page will use the global theme, unless you include <xphp var="exclude_global">true</xphp> in that page code (LiveWhale 1.6.2+).

This means to edit theme elements, simply copy or add files in the same folder structure as that in /core. Files in /global or /your-theme that are exactly the same filename fully replace the core file completely. If however, you add a file that does not exist in /core then it is additive. (This is more applicable to CSS and JS—see Resource Load Order below.)

Note: Best practices for theming dictate that you do not override completely the styles/common.less and styles/calendar.less, as you will then miss out on crucial updates to those files the next time you upgrade. Rather, you should create a calendar.less that first imports the core styles, and then customizes from there:

Example /_ingredients/theme/global/styles/calendar.less

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@import "../../../../livewhale/theme/core/styles/calendar.less";
@import "../../../../livewhale/theme/core/styles/vendor/lesshat.less";


/* =====================================================================
CUSTOM CALENDAR STYLES
===================================================================== */

// These colors are used in the core calendar styling.
// Setting them here will retroactively apply them to the above import,
// So you can quickly theme your entire calendar with your school's colors.
@highlight1: #999;
@highlight2: #333;

// Other customizations go below...

Resource Load Order

Since CSS load order can be important in some cases, understand that all /core styles are loaded first in the order dictated by LiveWhale. When you replace /core styles the replaced file in that original order, as if it was /core. Additive styles are loaded last. For example, assuming the following:

  • theme/core/styles/foo.css
  • theme/core/styles/bar.css
  • theme/my_theme/styles/foo.css
  • theme/my_theme/styles/foobar.css

The load order for the files could be either of the following, depending on the LW-dictated load order of foo and bar:

  1. theme/core/styles/bar.css
  2. theme/my_theme/styles/foo.css
  3. theme/my_theme/styles/foobar.css

OR

  1. theme/my_theme/styles/foo.css
  2. theme/core/styles/bar.css
  3. theme/my_theme/styles/foobar.css

CMS Commenting

When working on theming or template files, you may want to include comments for yourself that don’t get included in the page source that gets sent to the browser.

Since LiveWhale 1.7, you can prefix standard HTML comments with LW: and they will not be included in page output.

1
2
<!-- This comment will show up in the page source. -->
<!-- LW: This comment will NOT show up in the page source. -->