Default Formats

When you use a LiveWhale widget, you are often using the default format when each item is output in a list. For example, the default format for a news widget is:

{image}
<div class="lw_news_headline">
  {headline}
</div>
<div class="lw_news_summary">
  {summary}
</div>

In the example above, each curly-braced {format_variable} will be replaced with the value from each item in the matching widget stories. The values may be simply text or HTML. For instance, if at least one image is attached to the story, the above {image} would be replaced by an <img/> set to the size of the thumbnail, wrapped in a link <a> to the full story, wrapped in a <span> when output in a page or inside other dynamic content.

When the item value being requested is empty or not set, then the {format_variable} disappears entirely from the output of that item in the widget. In such cases, you would not see {image} above at all, but when markup is surrounding the variable, as for {summary} an empty summary results in <div class="lw_news_summary"></div> still present in the output. (See conditional formatting below if this is an issue for your widget.)

Creating/Editing Formats

In many widgets, you have the opportunity when editing a widget to set your own widget format, and additionally one for starred items when the content can be starred.

You can modify the widget output by clicking any of the available buttons directly beneath the widget format to add the format variable and any default wrapper markup. In many cases, this default markup, particularly the classes, will tie your widget into the default LiveWhale design, or into the custom design that your site uses.

You can also simply click into the format and add/change/delete anything in there, so long as the markup validates as HTML. Want that <span> to be a <div> instead? Just change it. Do note that such changes should accompany a review of design (CSS) and function (javascript) for your site.

If you’re working on a custom project, where you’ll be also be updating or adding CSS/javascript, then you can use any markup in the format. Use your own ids, classes, etc. as needed to achieve your end. (And read about the special format variables below, as you may need more options than those provided via the buttons.)

Other Variables

When doing custom formats, you are also not limited to the values for the buttons available. If you wish, you can include the values for fields based on their name in the matching editor. For example, you can include {body} in a news widget to get the entire body of the story. Or, try {description} for an event.

Widget markup style: Standard vs Simple

The widget editor gives you the option to choose between “Standard LiveWhale markup” and “Simple (clean) markup.”

By default, LiveWhale adds semantic list markup ( div > ul > li ) to the output of widgets. Setting the style to “simple” markup will output the widget items without any HTML markup. You may then set your own code around the widget items. Do not use list elements <ul> and <li> around the widget items when using “simple” markup (it breaks randomized widgets).

Special Format Variables

When creating a very specific form of output, you may need the item values output in a raw state, so that you can fully customize the markup. For example, with the above {image} you would have no way to not wrap the image in a link or span.

While not available as buttons, you can manually type in any number of special variables that are populated whenever the base item value is non-empty. The attached image has probably the largest number of options:

{image}: <span class="lw_item_thumb"><a href="{href}"><img src="{image_src}" alt="Image preview" class="lw_image" height="{thumb_height}" width="{thumb_width}"/></a></span>

{image_src}: an absolute path to the image, scaled to thumbnail size
{image_href}: alias to {image_src}
{image_caption}: the image caption

{link}: <a href="{href}">{link_text}</a>
{href}: the absolute URL to the full content of the item, e.g. its details page

Tags

When setting up special styling or JavaScript sorting by tag, you may need to display your widget result’s tags in a certain format. There are many options available:

{tags}: <a href="...">Tag</a> <a href="...">Tag 2</a> <a href="...">Tag 3</a>
{tags_starred}: <a href="...">Starred Tag</a> <a href="...">Starred Tag 2</a>
{tags_global}: <a href="...">Global Tag</a> <a href="...">Global Tag 2</a>
{tags_separated}: tag1|tag2|tag3
{tags_starred_separated}: starredtag1|starredtag2
{tags_global_separated}: globaltag1|globaltag2
{tags_dashed}: my-tag another-tag dashes-for-spaces
{tags_starred_dashed}: my-starred-tag another-starred-tag
{tags_global_dashed}: my-global-tag another-global-tag

_clean

When {format_variables} come pre-formatted as markup or otherwise might include HTML (summary, body, description, etc.) you can append _clean to any variable name to get its value as raw text. For example:

{headline}: <a href="{href}">{headline_text}</a>
{headline_clean}: the headline as text only

{title}: <a href="{href}">{title_clean}</a>
{title_clean}: the title as text only

{tags}: <p><strong>Tags:</strong><span class="lw_item_tags"><a href="...">tag</a>, ...</span></p>
{tags_clean}: tag, tag2, tag3,…

There are additional options for outputting tags.
The examples below assume use of the tags My Tag and My Other Tag .

{tags_separated} results in my-tag | my-other-tag . This can be used inside widget arguments:

<arg id="tag">cat|dog|mouse</arg> is parsed by LiveWhale as equal to

<arg id="tag">cat</arg>
<arg id="tag">dog</arg>
<arg id="tag">mouse</arg>

So you can add a widget argument like this:

<arg id="tag"><xphp var="tags_separated"/></arg>

… to look for each tag on an item separately.

Parent Format Variables

When a widget appears inside another widget, the nested widget will also have access to the item variables of the containing widget, so long as the nested one doesn’t use the same variable name. This obviously gets very Inception-like, but you could nest a blurb widget inside a news story, and know that you can put the {headline_clean} in the blurb widget format.

There is one caveat to this, while {headline} is always available for widget output, other less-used values like {group_title} are only available to the nested widget when they are also in the containing widget. If you have an instance where a value isn’t needed in the containing widget, you will still need to include it, but in a hidden form, as: <div style="display:none;">{format_variable_just_for_nested_use}</div> .

Simple Conditional Formatting

Beginning in LiveWhale 1.4.3, conditional format variables became available in order to fine-tune the markup output when a value was empty. Using the news summary example above, you could make the <div> surrounding the {summary} conditional on the summary being available by changing the widget format to:

{image}
<div class="lw_news_headline">
  {headline}
</div>
{<div class="lw_news_summary">
  |summary|
</div>}

In the above format, the <div> wrapping summary is now inside the curly braces, with the actual variable name offset with vertical pipes (|). With this simple templating style , you could have any HTML markup conditional on the non-emptiness of the item value.

You can also display a variable based on the absence or emptiness of another:

{photo_caption}{!photo_caption:photo_credit}

The above format displays {photo_caption} , if it exists, and if not, it displays {photo_credit} . You can also display text if a variable is empty: {!image:"There is no image here."}

Nested Conditional Formatting

Beginning in LiveWhale 1.4.5 and 1.5.0, conditional variables gained the ability to be nested inside each other. For example, perhaps you want the ability to show one item value only if another is also non-empty. Let’s presume that we only want to show a news story headline and summary conditional on the non-emptiness of the summary. That would look like this:

{image}
{<div class="lw_news_headline">
  {headline}
</div>
<div class="lw_news_summary">
  |summary|
</div>}

In the above example, the summary curly braces now surround everything but the {image} and like the simple conditional, the summary is bound by vertical pipes. But within the summary braces, we now see the headline, conditional upon the summary. You can include as many other {format_variables} as you please within a conditional set of braces, all dependent on the primary value.

And if you wish, you can go even deeper:

{image}
{<div class="lw_news_headline">
  {<span class="lw_news_group_title">
    |group_title|:
  </span>}
  {headline}
</div>
<div class="lw_news_summary">
  |summary|
</div>}

In this final example, the <span> surrounding the group title is conditional on the group title, while it, the headline and the summary are all conditional on the summary. At present, nested conditionals are allowed to at least two levels, as shown above.

Advanced Conditional Formatting

Since LiveWhale 1.6.2, if you want to get more advanced with your widget output and are familiar with XPHP, you can include XPHP in widget formats by using <field> . Basically, you replace xphp with field in a widget’s format argument and it will be run on every result.

Example: If

<field content="true">
  <if var="description"/>
    <content>
      <span>This result has a description: {description}</span>
    </content>
</field>

The above has the same result as {<span>This result has a description: |description|</span>} . The real power in the <field> syntax is if you want to use multiple criteria or more complex XPHP logic.

Example: If/Else

<field content="true">
  <if var="image_src"/> <!– use image if exists –>
    <content>
      <img class="spotlight-img" src="{image_src}" alt="{title_clean}">
    </content>
  <else content="true"> <!– otherwise, just show date –>
    <content>
      <div class="spotlight-date date-box green large">{date}</div>
    </content>
  </else>
</field>

Example: has_tag_* 

You can check for has_tag_* in widget formatting in the same way you would on pages:

<field content="true">
  <if var="has_tag_foo"/>
    <content>
      <span>This content has the tag "foo"</span>
    </content>
</field>

Example: %​​​%field_ (LiveWhale 2.2.0+)

In LiveWhale 2.2.0, the %​​​ %xphp_ syntax was extended to %​​​%field_, so you can do more advanced operations on widget format variables that you want to use inside of HTML attributes.

In this example, a urlencoded %​​​ %field_ variable is used to create tag links that, on page load, apply to the news widget below.

<widget type="tags">
  <arg id="group">me</arg>
  <arg id="clean_markup">true</arg>
  <arg id="format">
    <a href="./?topic=%​​​%field_title_clean|CAST:urlencoded%​​​%">{title_clean}</a> 
  </arg>
</widget>

<widget id="1234_news_all_news">
  <xphp if="topic" type="GET">
    <arg id="tag"><xphp var="topic" type="GET"/></arg>
  </xphp>
</widget>

Find more examples of XPHP Logic Operations.