Details pages are the templates that serve the “details” of individual dynamic content items such as news stories, events, galleries, forms, blog posts, and profiles.
Details pages are set per content type. In other words, all news stories on a LiveWhale-powered site appear in the same template by default. But, you can create custom details pages for groups (so that groups with unique site designs can have stories that appear in their own template) or even for widgets (so that special kinds of news items can always appear in a consistent template).
Organizing your details pages
The default locations for your details pages are:
- /_ingredients/templates/details/blogs.php
- /_ingredients/templates/details/blurbs.php
- /_ingredients/templates/details/events.php
- /_ingredients/templates/details/forms.php
- /_ingredients/templates/details/galleries.php
- /_ingredients/templates/details/news.php
- /_ingredients/templates/details/profiles.php
- /_ingredients/templates/details/tags.php
If your files are at that location, no further configuration is needed.
If you don’t want to use the default _ingredients location, you can set the location of your details pages in livewhale/client/public.config.php:
$_LW->REGISTERED_WIDGETS['blurbs']['widget']['item_url']='/templates/details/blurbs.php';
$_LW->REGISTERED_WIDGETS['events']['widget']['item_url']='/templates/details/events.php';
$_LW->REGISTERED_WIDGETS['forms']['widget']['item_url']='/templates/details/forms.php';
$_LW->REGISTERED_WIDGETS['galleries']['widget']['item_url']='/templates/details/galleries.php';
$_LW->REGISTERED_WIDGETS['news']['widget']['item_url']='/templates/details/news.php';
$_LW->REGISTERED_WIDGETS['profiles']['widget']['item_url']='/templates/details/profiles.php';
$_LW->REGISTERED_WIDGETS['tags']['widget']['item_url']='/templates/details/tags.php';
Developing new details pages
If you are developing a new or significantly different details page, one of the easiest methods is to duplicate an existing details page closest to your need (of the matching content type of course) and then build and test your new page off-the-grid by requesting it directly:
/path/to/your/new/details-page.php?id=####
In the above example, we request the details page directly and must also include a valid id for matching content to be displayed in the details page. Not providing the id will result in a 404 error page.
The main thing that tells LiveWhale it may use a particular file as a details page is putting <widget type="news_details" priority="high"/>
somewhere on the page, changing “news” to another content type (profiles, forms, if necessary.
Details Page Variables
Since LiveWhale 1.6, details pages can be created with generic variables (details_name, details_thumbnail, details\body, etc.) that allow you to re-use content between details pages.
Name | Code | Type(s) |
---|---|---|
Name / Title |
<xphp var="details_name"/> or<xphp var="details_title"/>
|
all |
Image |
<xphp var="details_image"/>
|
news, events, profiles, galleries |
Gallery Images |
<xphp var="details_thumbnails"/>
|
galleries |
Body (includes profiles fields assigned to “body”) |
<xphp var="details_name"/>
|
all |
Sidebar (includes profiles fields assigned to “sidebar”) |
<xphp var="details_sidebar"/>
|
profiles |
Post |
<xphp var="details_post"/>
|
blogs |
Summary |
<xphp var="details_summary"/>
|
news, events, galleries |
URL |
<xphp var="details_url"/>
|
news, events, profiles |
Location |
<xphp var="details_location_title"/>
|
all |
Related Content |
<xphp var="details_related_content"/>
|
all |
Save and Share Links |
<xphp var="details_share"/>
|
all |
Last Modified |
<xphp var="details_last_modified"/>
|
all |
Last Editor |
<xphp var="galleries_last_editor"/>
|
all |
If your site predates LiveWhale 1.6, you might notice variables that are named for the content type (news_body, profiles_thumbnail, etc.). You can replace those with the generic details_
version, but LiveWhale 1.6+ remains backwards-compatible with the old style of variables.
You may want to use XPHP logic to only show certain fields if they exist:
<xphp content="true">
<if var="details_image"/>
<content>
<div class="news-page-images"><xphp var="details_image"/></div>
</content>
</xphp>
This is especially useful when displaying custom fields in profile details pages:
<xphp content="true">
<if var="profiles_12"/><!– Class Year –>
<content>
<span>Class of <xphp var="profiles_12"/></span>
</content>
</xphp>
The default gallery
LiveWhale 2.0+ includes a new core gallery type called “default,” which is used when images or a gallery are attached to an event, news story, profile, or blurb.
When you place it on your event details component using {{ image }} or on a news/profile/blurb details page using <xphp var="details_image" />
, it will return:
- A single image (if only one is attached)
- An image that clicks to open a fullscreen slideshow (when multiple images are attached), including an icon overlay indicating that a gallery is present
To customize the appearance of the fullscreen overlay, copy the folder from
/livewhale/theme/core/galleries/default/
to
/_ingredients/themes/global/galleries/default/
and start editing!
Note: Aftering copying the default gallery to your theme, delete the pre-rendered .css and .js files. Instead, keep and edit the .scss and .es6 versions and LiveWhale will automatically render them.
default.xml widget template
In default.xml, you can edit the following configuration settings:
Setting | Description | Default | Can be overridden per content type? |
---|---|---|---|
thumb_width | The width of the main image | 300 | Yes |
thumb_height | The height of the main image (if empty/absent, will default to auto) | auto | Yes |
image_width | The width of the fullscreen gallery images that opens on click | 1000 | Yes |
image_height | The height of the fullscreen gallery images that opens on click (if empty/absent, will default to auto) | auto | Yes |
format_single_image | LiveWhale 2.8 and above: When only one image is attached to your event/story/profile/blurb, the default gallery will skip all markup from format_widget and format, instead returning this simplified HTML format only. Supported formatting variables: `{image}, {caption}, {credit} |
{image} {<div class=”lw_image_caption”>|caption|</div>} |
Yes |
format_widget | The widget wrapper HTML that goes around the outside of the gallery. Supported formatting variables: {title}, {gallery_thumbnail}, {widget} | See core default.xml for full HTML | No |
format | The HTML formatting for each image in the fullscreen gallery. Supported formatting variables: {gallery_image}, {caption}, {credit} | See core default.xml for full HTML | No |
Editing the above settings in /_i/themes/global/galleries/default/default.xml will apply your changes to all content types that use the default gallery.
If you’d like to customize certain settings per content type, you can do that by editing the default template directly and those settings will override default.xml. You can override thumb_width/height, image_width/height, and format_single_image in this way.
Customizing News, Profiles, and Blurbs images
In your details .php template, edit the <widget type="{type}_details" priority="high"/>
declaration to change how images are included on your details page. Here’s an example from a news.php details template:
<widget type="news_details" priority="high">
<!– These override settings from default.xml –>
<arg id="thumb_width">800</arg>
<arg id="thumb_height">auto</arg>
</widget>
<!– This will now be an 800-pixel wide version of the news image –>
<xphp var="details_image"/>
Customizing Event images
In your calendar widget (often in a file called calendar_settings.html), edit the <widget type="events_calendar">...</widget>
declaration to change how images are included on your event details page. Here’s an example:
<widget type="events_calendar">
<!– These override settings from default.xml –>
<arg id="image_width">250</arg>
<arg id="image_height">auto</arg>
<arg id="format_single_image">{image}</arg>
</widget>
Note: Since thumb_width and thumb_height already have a special meaning for calendar settings (as the size of the event thumbnail in the day/week/list views), these events_calendar overrides use image_width/height for the main event details image and gallery_width/height for the fullscreen gallery size. See the list of Calendar Widget Arguments for more details.
default.scss stylesheet (automatically compiled to default.css)
In default.scss, you can edit the variables to change the colors/sizing of the gallery overlay, or change the .lw_gallery–multiple &::after
styles if you’d like to use your own icon or indication of when the image is linking to a gallery.
default.es6 script (automatically compiled to default.js)
We do not recommend editing the .es6/.js files for the default gallery, though if you like, you can replace the core default gallery altogether with your own original version. Do this by creating a new gallery called “default” in /_ingredients/themes/global/galleries/ containing its own .scss, .es6, and .xml configuration files modeled after the above core versions.