Setting Up LiveWhale

There are a myriad ways to configure LiveWhale and LiveWhale Calendar to behave exactly as you wish. This page is a growing reference list for which settings live where and how to use them. If you have questions about configuration, please don’t hesitate to ask.

global.config.php

1
2
3
4
5
6
7
8
9
$_LW->IMAGE_THUMB_WIDTH=80; 		// width for widget thumbnails (default: 80)
$_LW->IMAGE_THUMB_HEIGHT=80; // height for widget thumbnails (default: 80)
$_LW->IMAGE_THUMB_WIDTH_FEED=80; // width for widget thumbnails in RSS/ICAL feeds (default: 80)
$_LW->IMAGE_THUMB_HEIGHT_FEED=80; // height for widget thumbnails in RSS/ICAL feeds (default: 80)
$_LW->IMAGE_PREVIEW_SM_WIDTH=374; // default width for small backend image previews (default: 374)
$_LW->IMAGE_PREVIEW_LG_WIDTH=650; // default width for large backend image previews (default: 650)
$_LW->IMAGE_PREVIEW_LG_HEIGHT=500; // default height for large backend image previews (default: 500)
$_LW->IMAGE_WIDGET_WIDTH=250; // default image width for details pages (default: 250)
$_LW->IMAGE_WIDGET_HEIGHT=false; // default image height for details pages (default: none)

private.config.php

When setting required fields for events, we recommend that you limit those requirements to the event editor using code like this. Reason being, if you make such fields required globally, it can block events from being loaded in from your Linked Calendars, if they’re missing those fields.

1
2
3
4
5
6
7
8
9
if ($_LW->page=='events_edit' || $_LW->page=='events_sub_edit') { // add additional requirements for events
$_LW->REGISTERED_MODULES['events']['data_types']['events']['fields_required'][]='categories';
$_LW->REGISTERED_MODULES['events']['data_types']['events']['fields_required'][]='summary';
$_LW->REGISTERED_MODULES['events']['data_types']['events']['fields_required'][]='description';
$_LW->REGISTERED_MODULES['events']['data_types']['events']['fields_required'][]='location';
$_LW->REGISTERED_MODULES['events']['data_types']['events']['fields_required'][]='contact_info';
$_LW->REGISTERED_MODULES['events']['data_types']['events']['fields_required'][]='cost_type';
$_LW->REGISTERED_MODULES['events']['data_types']['events']['fields_required'][]='date_time';
}

The same also holds true for customizing maximum field lengths:

1
2
3
if ($_LW->page=='events_edit') { // limit event summary to 130 characters in the editor
$_LW->REGISTERED_MODULES['events']['data_types']['events']['fields_length']['summary']=['summary', 130];
};

Allowing external services for iframes and scripts

Unknown javascripts and iframe pages can introduce viruses and malware to unsuspecting site visitors, and you’d get that big red warning page attached to your site if Google finds them before you do. So to protect your site and its visitors, LiveWhale does not allow you to paste any unknown <iframe>s and <script>s into pages or dynamic content like stories and events.

But naturally, there are services and sites that you do trust to supply clean content, so LiveWhale allows you to maintain a list of allowed domains that can be embedded. Once the base URL is added, any user can insert both <iframe>s and <script>s.

To allow a domain, you add a statement to one of your LiveWhale client configuration files. You can allow just a specific domain, or everything from that site/service as shown below.

1
2
3
4
5
// an explicit domain
$_LW->CONFIG['HOSTNAME_ALLOWLIST'][]='some.great.domain.tld';

// the star is a wildcard, so any google site/service is fine.
$_LW->CONFIG['HOSTNAME_ALLOWLIST'][]='*.google.com';

Note: In LiveWhale 2.0.1 and before this setting was called HOSTNAME_WHITELIST.
Since LiveWhale 2.0.2 it’s been renamed HOSTNAME_ALLOWLIST, but the old syntax is supported for backwards-compatibility.

Add as many as you like— one per line— as shown above. (Order is not important.) To which LiveWhale configuration file you add these statements determines where the service is to be available for dropping in <iframe>s and <script>s.

/livewhale/client/global.config.php
Adding the statements to the global scope is the most common, as you will probably want the service available both when editing pages and when editing stories and events.

/livewhale/client/global.public.php
Adding the statements to the public scope would make the service available only when editing pages.

/livewhale/client/global.private.php
Adding the statements to the private scope would make the service available only when editing content like stories and events.

Removing timezones from iCal (Outlook)

Anytime you subscribe to a LiveWhale Calendar feed or use the auto-generatd “Add to my calendar” link, you are downloading an iCal feed (.ics file).

We have seen that some versions of Outlook ignore timezone instructions in .ics files. If you’d like, you can add the following setting to livewhale/client/global.config.php as a workaround:

1
$_LW->CONFIG['ENABLE_UTC_ONLY_ICAL']=1; // disable timezones in iCal output

This removes timezone definitions from your iCal exports and instead puts everything in UTC (Coordinated Universal Time).

Customizing image crop aspect ratios (LiveWhale 1.7.1+)

In LiveWhale 1.7.1+ you can set your own custom aspect ratios for the image crop tool. The defaults are 1:1, 3:2, 2:3, 4:3, and 3:4, but you can add to or override those by adapting the following example and adding it to livewhale/client/global.config.php.

Your aspect ratios must be expressed in whole numbers (width:height), and you can name your custom aspect ratio (like “Profile” or “Featured” in the example).

1
2
3
4
5
6
7
8
9
$_LW->CONFIG['IMAGE_CROP_ASPECT_RATIOS']=[
'1:1',
'3:2',
'2:3',
'4:3',
'3:4',
'Profile'=>'100:163',
'Featured'=>'7:4',
];

Then, your custom list of aspect ratios will be included in the image cropping tool:

Custom cropping aspect ratios

Adding a “Small image” button to the image auto fill options (LiveWhale 2.5.0+)

In LiveWhale 2.5.0+ you can add a configurable “Small image” button to the Add/Edit Image tool’s auto fill options, beneath the “Full column” and “Half column” buttons.

Small image button

When adding or editing an image, clicking the “Small image” button will set the image width to your configured pixel setting, making it easier to maintain visual consistency across multiple pieces of content.

To enable this button, add the following to livewhale/client/global.config.php:

1
$_LW->CONFIG['SMALL_IMAGE_WIDTH']=300; // adds a "Small Image" button to Insert Image that sets the image width to 300px

Configuring LiveWhale to not add responsive code to certain videos or embeds

LiveWhale automatically detects all <object> and <embed> tags, or any <iframe> referencing Vimeo or YouTube, and uses a plugin called FitVids to wrap them in <div class="fluid-width-video-wrapper"></div> which makes them responsive.

Sometimes, though, you might have specialized cases where your theme code is already making a video responsive, and you don’t want this extra markup. Prior to LiveWhale 2.6.0, you could wrap such videos in class="fitvidsignore" and they would be skipped.

Since LiveWhale 2.6.0, you can add additional classes to a configurable list in livewhale/client/global.config.php to have videos inside them also skipped by FitVids.

1
$_LW->CONFIG['FITVIDS_IGNORE_CLASSES']=['hero-video','another-ignore-class'];
1
2
3
4
<!-- with the above config, this will not be wrapped in div.fluid-width-video-wrapper -->
<div class="hero-video">
<iframe src="//www.youtube.com/embed/etc..."></iframe>
</div>