Issues are a special content type in LiveWhale CMS and LiveWhale Storyteller for managing collections of stories (and sometimes blurbs) called “issues.” This feature was designed and intended for use with university magazines, but can be used for any communications effort that requires linking together a number of stories—like newsletters, for instance.

Please reach out if you’re planning a project using Issues and you’d like design or build assistance from our team.

Enabling issues

Issues functionality starts off disabled by default, and can be enabled on a per-group basis.

1. After creating the group where you want to enable Issues, note the group ID
   (e.g., for /livewhale/?groups_edit&id=330 the group ID is 330)

2. To livewhale/client/global.config.php, add the following:

   $_LW->CONFIG['ENABLE_ISSUES']=[
     // gid=>[
     //    'title'=>'',
     //    'url'=>'',
     //    'content_type'=>['news', 'blurbs'] // or just news, if you don't plan on using blurbs for Issue-specific static content
     // ],
     330=>[
       'title'=>'Magazine Title',
       'url'=>'/magazine-homepage/',
       'content_type'=>['news', 'blurbs']
     ],
   ];

   This is an array and can support multiple collections of issues (“magazines”) in different groups, if need be.

3. With this configuration in place, logout/login and switch to the relevant group. Now when you enter the Stories navigation, a new item “Issues” is there.

Using issues

• Go to Issues > Add a new issue. Each issue can have

  • A title (required), e.g. “Fall 2023”
  • An image (optional), e.g. magazine cover image
  • A publication date (required). This is used instead of Live/Hidden. Issues published today or before are Live, and the most recently-published Issue is used as the current one. Issues with future publication dates are essentially Hidden. Note, the status of an issue is unique from the statuses of its stories/blurbs (more on this below).
  • Tags (optional). Some approaches use this to indicate different homepage designs (e.g. tags for “Layout 1,” “Layout 2”)
  • Table of contents (optional). This is a WYSIWYG text area that you can use for prefacing text or a hard-coded list to your stories, if you prefer to do so in place of setting up individual widgets for each.

• Once you’ve created an Issue, you can start adding stories and/or blurbs from the current group to it from the Story and Blurb editor pages. (If you need to use stories from other groups, first share them into this group.)

• On the Issues manager, you’ll see two preview links: one with only Live content, another called “Include hidden content” that will also show stories/blurbs that are currently hidden. This allows you, if you want, to schedule certain stories to go-live the same day as the Issue publication date, but still preview them ahead of time.

Theming your issues homepage

• Essentially, the /index.php of the Issues URL you configured in global.config.php acts as a special sort of LiveWhale details template. We’ll call that the “magazine” template.

• When someone goes to the magazine template URL on its own, they’ll see content from the currently active (i.e., most recent published) issue. But you can also suffix the URL to view a particular past or upcoming issue:

  In LiveWhale 2.9.3 and before, add a GET variable to the magazine homepage to specify an issue ID, e.g. /magazine-homepage/?id=2

  In LiveWhale 2.10.0 and later, add the custom URL for the issue to the end of the magazine homepage URL, e.g. /magazine-homepage/2-fall-2023

• The magazine template must include <widget type="issues_details" priority="high"></widget> and has the following XPHP variables available:

• In addition to the above variables, news and blurb widgets included on the magazine template will automatically filter to only show results from the currently-viewed issue. Most designs use this alongside news tags to organize their magazines. e.g., a news widget for stories tagged “Top Feature”, a blurb widget for one item tagged “President’s Welcome”, etc.

Theming your issues news stories

• You may choose to use your normal site-wide news details template for magazine stories. You can also set a custom news details template for your Issues group (under “Custom Landing Page URLs” in the group settings).

• In either case, you can access certain XPHP variables about the containing issue when on a news details template.

  <xphp if="details_issue_title">
      <h2>Source: <a href=""><xphp var="details_issue_title"/> Issue</a></h2>
  </xphp>

Setting up issues widgets

• When Issues are enabled, there is a new hidden widget type “issues” that you can include in your templates and includes for displaying a list of issues, e.g. for a dropdown or navigation to other issues.

  <widget type="issues">
    <arg id="clean_markup">true</arg>
    <arg id="format">
      <a href="{url}" data-issue="{id}">{title_clean}</a>
    </arg>
  </widget>

• Tip: if you like, you can use the issues widgets and date sorting to generate previous and next links:

  <widget type="issues">
      <arg id="group">me</arg>
      <arg id="max">1</arg>
      <arg id="clean_markup">true</arg>
      <arg id="end_date"><xphp var="details_date" /></arg>
      <arg id="sort_order">reverse-date</arg>
      <arg id="format"><a href="{href}">Previous Issue</a></arg>
  </widget>
  
  <widget type="issues">
    <arg id="group">me</arg>
    <arg id="max">1</arg>
    <arg id="clean_markup">true</arg>
    <arg id="start_date"><xphp var="details_date" /></arg>
    <arg id="sort_order">date</arg>
    <arg id="format">
        <a href="{href}" class="green magazine-button">Next Issue ></a>
    </arg>
  </widget>

• Tip: You can also use an issue widget to display a gallery of issues with their cover photos:

  <widget type="issues">
    <arg id="start_date">01/01/2015</arg>
    <arg id="group">me</arg>
    <arg id="clean_markup">true</arg>
    <arg id="paginate">false</arg>
    <arg id="thumb_width">400</arg>
    <arg id="thumb_height">300</arg>
    <arg id="ignore_cropper">true</arg>
    <arg id="format">
      <a href="{href}">{image}<br/>{title_clean}</a>
    </arg>
    <arg id="format_widget">
      {widget}
    </arg>
  </widget>

• Note: It is also possible to add custom fields to the issues content type, if you have other text fields (like, say, a PDF link) you want to attach to each Issue. Then, in your details template or issues widgets, you can use {custom_pdf_link} like you would for any other custom field.