Tips and tricks for optimizing LiveWhale development

Naomi Royall
Tips and Tricks for
LiveWhale Development
2016

Getting the Ingredients Together
Global theme plus theme for special feature

Script numbers control loading order.
Modernizr need to go in site head.

Default widget format templates.
New defaults for different themes.

Widgets.less gets used by the widget editor preview.

Widget preview.

Template structure.
Separate templates for different group types.
Details templates are used for dynamic content.

Global can contain site-wide templates.

Includes contains reusable template elements.
<widget type="file"><arg id="path">/_ingredients/templates/includes/head.html</arg></widget>

Office templates group.

- Set up group template permissions.
- Save group.
- Set default page editing templates.
- Used when anyone in that group
creates a new page.
Default Templates

Default Templates www.nursing.upenn.edu/its/

Looking Out for Opportunities (or Potential Headaches)
- Do I need a new template?
- Would it be best to create a new theme?
- Themes keep styles, JavaScript and templates cleanly compartmentalized.
- Protect the rest of your site from experimental work.
- LESS is automatically compiled for you and error logs are generated.
- Simply add the theme variable to the page. You can place it in an editable area.
<xphp var="theme">timeline</xphp>

Keeping Widgets in Check Widgets → All Widgets
The widget manager shows us which widgets are used where. Only works for saved widgets.

Keeping Widgets in Check
- Use widget names that can easily be understood at a glance.
- The name can be changed any time. The widget ID is the only part used by LiveWhale.
- Add a thoughtful widget description:
- a summary of what it does
- why it is unique
- an example of where the widget is used

Keeping Widgets in Check
- Duplicate an existing widget when you’d like to alter the appearance for a new use-case.
- Or, carefully add the widget to the page and change one or two arguments with the source
code button (mother widget method).

- Save widgets in the widget manager.
- Keeps everything neat and organized…
- Which helps us to fix widgets
- Makes it easy to duplicate widgets
Avoid Stray Widgets!

- Only show html if a variable exists (you can nest conditionals two levels deep):
{<div class="news-date"> {date} </div><div class="news-summary"> |summary| </div>}
- Show another widget variable if a variable is empty:
{!summary:location_title}
- Remove markup from a variable by appending _clean (useful for removing links):
{title_clean}
Widget Formatting Options

- For regular content, from any group.
- Used when anyone creates a new widget.
- Useful for global widgets.
- Use the class .lw_widget_news
to style the widget (applies to
all news widgets).
- Different default formats for each theme: /theme/fancy-theme/widgets/news.format.html
Widget Default Format Templates

Remove the stuff you don’t need.
Clean Markup: for unique, snazzy widgets.
No need for list of items here!
An <article> would be better.
Always add custom classes to
widgets when styling is unique:
- “Apply custom class”
- “Wrap widget with markup”

Add classes required for jQuery plugins.
Wrap widget output with markup: <div class="fancy-slider">{widget}</div>
Format results with:
<article class="fancy-slider-item" style="background-image:url({image_src});">
<a class="link" hef="{href}"></a>
<h4 class="headline">{headline}</h4>
<div class="summary">{summary}</div>
</article>
Clean Markup: for unique, snazzy widgets.

More Advanced Widgets
- Use xphp page variables to change widget content on a page-by-page basis.
- Use xphp group variables to change widget content on a per-group basis.
- Example: Show events tagged with the page title:

Example: Featured Topics www.nursing.upenn.edu

Example: Featured Topics
Display tagged widget content:
<widget id="49_news_research_stories_topics_details">
<if var="has_news"/>
<xphp var="tags"/>
<arg id="tag">research</arg>
</widget>
<widget type="galleries_inline">
<if var="has_galleries"/>
<xphp var="tags"/>
</widget>

Example: Featured Topics
Show next and previous tags:
<widget type="tags">
<arg id="header">Next Topic:</arg>
<arg id="max">1</arg>
<arg id="min_items">3</arg>
<arg id="only_starred">true</arg>
<arg id="min_size">1</arg>
<arg id="max_size">1</arg>
<arg id="item_url">/details/tags.php</arg>
<arg id="filter" name="title" action="greater_than"><xphp var="tag_title"/></arg>
<arg id="sort_order">alphabetical</arg>
<arg id="clean_markup">true</arg>
</widget>

Example: Profiles Search
Use Quick Access to search through the results of a saved widget:
<h2>Quickly browse faculty by research area or keyword:</h2>
<form class="quickaccess-form">
<label class="screen-reader-text" for="faculty-quicksearch">Search faculty</label>
<input id="faculty-quicksearch" class="lw_qa_widget_88" type="text"
placeholder="Search faculty" data-qa-none-found="No faculty found.">
</form>

Example: Profiles Search
Use the data attribute to search over profile fields without displaying them in the results:
<widget type="profiles">
<arg id="type">Faculty</arg>
<arg id="paginate">false</arg>
<arg id="sort_order">alphabetical</arg>
<arg id="format"><a href="{href}" data-keywords="{profiles_78_clean}
{tags_starred_clean}">{name_clean}</a></arg>
</widget>
Search over name, “Faculty Expertise” and starred profile tags.

While we’re talking about search…
Use data-qa-none-found to change the no results message:
<input type="text" id="quicksearch" class="lw_qa lw_qa_widget_60" name="q"
placeholder="Search programs, people, practice areas" autocomplete="off"
data-qa-none-found="No quick results found. Press Enter to search." data-qa-max-results="20"
value="">

- Use the .editable class to make an area editable.
<div id="sidebar-content" class="editable optional">

</div>
- Each editable element must have a unique ID.
- The .optional class allows that element to be hidden if
it doesn’t contain any content.
- When this element is hidden, the body gets class
.sidebar-content_hidden
Mastering the Page Editor

- Use the .sidebar-content_hidden class to change the page
layout when there’s no sidebar content.
body.sidebar-content_hidden .main-content {
width: 100%;
}
- Use the .editable class to add site-wide styles that only
apply to editable areas.
.editable .lw_image {
margin-bottom: 10px;
max-width: 100%;
height:auto;
}

- Include a clearfix on all editable areas.
.editable:before,
.editable:after {
content:'';
display: table;
clear: both;
}
- Add header styling for editable areas that may not apply
to headers on the homepage etc.
.editable h2 {
font-size: 26px;
color: red;
}

Use the class .lw_editor_on to change the appearance while the page is being edited.
Use the widget editor to
add the class .empty when
there’s no image.
<arg id="no_results">
<div class="header-image
empty"></div>
</arg>

Example: display a suggestion to include a header image on the page.
.header-image.empty {
display:none;
}
.lw_editor_on .header-image.empty {
display: block;
background-color: #ccc;
}
.lw_editor_on .header-image.empty:after {
content: 'Tag an image "header image" to appear here.';
display: block;
}

Mastering the Page Editor www.ursinus.edu/uc-magazine/

Example: Insert images in the page editor and move them around after the page is saved.
/* position title image left of article divider */
#title img {
position: absolute;
left: 0;
top: 0;
transform: translate(-90.5%, -7%);
}
/* this treatment allows images to be positioned correctly and stay visible */
.lw_editor_on #title img {
position: relative;
transform: translateX(0);
}

- Add buttons to the page editor toolbar.
$_LW->CONFIG['TOOLBAR_ADD_BUTTONS']=array('blockquote’, ‘hr');
- Edit the Formats dropdown to provide more styling options.
$_LW->REGISTERED_APPS['pages_editor']['custom']['style_formats']= array(
array('title'=>'Text styles:','selector'=>'p,h2,h4'),
array('title'=>'Small type','selector'=>'p,h2,h4','classes'=>'font-small'),
array('title'=>'Link styles:','selector'=>'a'),
array('title'=>'Button','selector'=>'a','classes'=>'button1'),
);

- Customize the default gallery type used when adding a slideshow in the page editor.
$_LW->REGISTERED_MODULES['galleries']['custom']['default_type']='mini';
- Also customizes the gallery type for “Get Code” links in the gallery manager.
- Custom galleries are kept in the theme under /my_theme/galleries/

- Call a JavaScript function after the page is edited.
$('body').bind('stopEdit.lw', function(){
// do this after LiveWhale page edit/save
});
- Similarly for the calendar:
$('body').bind('calLoad.lwcal', function() {
// do this each time the calendar view is refreshed
});

Owning Your Site
- Create a style guide for editors.
- Write informative widget descriptions.
- Add twice as many comments to your code as you think you need.
- Keep file paths predictable and file names understandable.
- Document everything unique to your site for future developers, for us, for yourself.
- Where’s the best place to keep all this documentation?
GetHelp.livewhale.com

Owning Your Site
Add a navigation widget to the dashboard in livewhale/client/private.config.php:
$_LW->CONFIG['DASHBOARD'] = array(
'left' => array(
array(
'LiveWhale CMS Help',
'<br/><widget id="127_help_navigation"></widget>'
),
),
);
GetHelp.livewhale.com

Example: Careers Microsite www.lakeforest.edu/careers/pathways
- Use a new theme (CSS & JavaScript).
- Add new default widget formats.
- Create new templates.
- New LiveWhale theme structure makes it easy
to keep everything bundled together.

Example: Careers Microsite www.lakeforest.edu/careers/pathways

Example: Digital Publishing www.ursinus.edu/uc-magazine/

THE END
Bonus code snippets →

<head>
<title><xphp var="page_title"/> • <xphp var="group_title"/> • <xphp var="client_name"/></title>
<meta name="description" content="" />
<meta name="keywords" content="" />
<widget type="file"><arg id="path">/templates/includes/head.html</arg></widget>
</head>
LiveWhale Template Head

<xphp content="true">
<if var="x" value=""/>
<content>

</content>
<else content="true">
<content>

</content>
</else>
</xphp>
LiveWhale Conditional Statements
https://livewhale.desk.com/customer/en/portal/articles/2490653-xphp-if-then-else-statement

<xphp content="true" ifmode="or">
<if var="profiles_22"/>
<if var="profiles_23"/>
<content>

</content>
</xphp>
https://livewhale.desk.com/customer/en/portal/articles/1522002-xphp-and-or-statements

<if var="has_tag_red"/>
<content>

</content>
</xphp>
https://livewhale.desk.com/customer/en/portal/articles/2488862-check-if-tag-exists-in-xphp

Tells the functions inside to use LiveWhale’s jQuery and keeps variables locally scoped.
http://adripofjavascript.com/blog/drips/an-introduction-to-iffes-immediately-invoked-function-express
ions.html
;(function($) {
// Assigns LiveWhale's jQuery to $
}(livewhale.jQuery));
LiveWhale jQuery IIFE
(Immediately Invoked Function Expression)

You can put the plugin JS in a custom theme OR call the plugin JavaScript on some pages only.
$.ajax({
url: "/scripts/plugin.js", // Use an IIFE in plugin.js if the plugin requires jQuery
dataType: "script",
cache: false
}).done(function() {
// Do stuff here using the plugin
});
Using Plugins in LiveWhale

Keeping Performance in Mind
function debounce(func, wait, immediate) {
var timeout;
return function() {
var context = this, args = arguments;
var later = function() {
timeout = null;
if (!immediate) func.apply(context, args);
};
var callNow = immediate && !timeout;
clearTimeout(timeout);
timeout = setTimeout(later, wait);
if (callNow) func.apply(context, args);
};
};
Example:
var myFunc = debounce( function() {
// do something here
}, 250, true);
Reduces the number of timed a function is called when resizing the window, scrolling, etc.
JavaScript debounce function from Underscore.js:
https://davidwalsh.name/javascript-debounce-function

Add this to you events detail file to display all events in the calendar instead of in their own
details template:
<?php
if (!empty($_GET['id'])) {
die('<html><head><meta http-equiv="refresh"
content="0;URL=/calendar/#event_id/'.(int)$_GET['id'].'/view/event">
</head><body><script
type="text/javascript">window.location.href="/calendar/#event_id/'.(int)$_GET['id'].'/view/event";
</script></body></html>');
};
require $_SERVER['DOCUMENT_ROOT'].'/livewhale/frontend.php';
?>
Displaying Events Only in the Calendar

Tips and tricks for optimizing LiveWhale development

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Tips and tricks for optimizing LiveWhale development

Similar to Tips and tricks for optimizing LiveWhale development (20)

Recently uploaded

Recently uploaded (20)

Tips and tricks for optimizing LiveWhale development