LiveWhale Support

Documentation»Themes and Ingredients

Themes and Ingredients

Using LiveWhale’s theming tools, you can customize almost every aspect of your site’s look-and-feel. For specifics about calendar theming, check out the Theming LiveWhale Calendar onboarding guide.

Themes

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/ (e.g., /_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.

The Ingredients Folder

Theme files and other front-end customizations are organized into a folder called “ingredients.” This top-level folder (mysite.edu/_ingredients/) combines a number of other folders into one convenient place.

Tip: Make sure to include the /_ingredients/ folder under version control, if that is in use on your site.

What goes in /_ingredients/ ?

On a new installation of LiveWhale, the ingredients folder will contain:

  • /_ingredients/themes/ – This is the first place LiveWhale will look for theme files. A new installation comes with a /global theme sub-folder, and you can create as many additional theme sub-folders as you like.

  • /ingredients/templates/ – This is our recommended location for page templates. LiveWhale will still respect your config settings to specify details template locations. However, these settings are now optional and only override the default path in /_ingredients. Don’t forget: you can create as many sub-folders as you need to keep your site templates organized, and can grant permissions based on folder (office groups get access to _ingredients/templates/office, for instance).

  • /_ingredients/backend/ – This makes it easier than ever to customize the LiveWhale backend interface. Simply upload a backend.css (or backend.less, if your server has LESS enabled) into this folder and LiveWhale will load it whenever the backend interfaces pages in use. You could also put a custom WYSIWYG style in here.

  • /_ingredients/extras/ – is for anything you don’t want to include with your theme. Nothing you put in this folder will be included automatically on the site, so it’s great for plugin code, where you want to drop in a script folder and call its components yourself using `<script>` and `<style>`. Note: scripts, fonts, etc. that your theme depends on should go into /themes/assets/.</style\></script\>

Recommendations

If your site uses any of the following folders, you may want to move them into the ingredients folder as well. Note: Migrating these folders into ingredients will break any absolute or relative links to these resources. Make sure you are prepared to update all links before moving folders.

  • /includes
  • /scripts
  • /styles

Understanding 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.

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 

"../../../../livewhale/theme/core/styles/calendar.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

If you’re working with multiple CSS/LESS/SCSS files in your theme, they will generally be loaded alphabetically. One tip is to prefix those files numerically 0-bootstrap.scss, 1-dependency.scss, 2-styles.scss so you can have more control over load order.

Theme 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.

You can prefix standard HTML comments with LW: and they will not be included in page output. 

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

On this page