XPHP

XPHP is an ever-growing library of scripting statements that you can use for powerful template control, widget behaviors, and more in LiveWhale.

In the below statements, you can use any of the XPHP variables from the XPHP Dictionary, or item-specific variables in widget results and details pages (i.e., "profiles_45" might be one of your custom profile fields).

XPHP Logic Operations

If/Then Example

The following examples demonstrate first, a simple check (is variable “X” empty?) and a more complicated one, using some of the tricks from the conditional functions below.

1
2
3
4
5
6

<xphp content="true">
   <if var="X" value=""/>
     <content>
        <!-- do something here -->
     </content>
</xphp>

1
2
3
4
5
6

<xphp content="true">
   <if var="server_path" value="{group_directory}index.php"/>
     <content>
        <!-- show this if it's the group homepage -->
     </content>
</xphp>

Whatever is in-between <content></content> will be shown if the if statement is true. It could be simple HTML, a widget, or more XPHP code.

If/Then Shorthand (1.7+)

Since LiveWhale 1.7, the above syntax can be shortened to <xphp if. For example:

1
2
3

<xphp if="X">Variable X exists.</xphp>
<xphp if="X" value="Y">Variable X has value Y.</xphp>
<xphp if="X" matches="Y">Variable X contains the text Y.</xphp>

If/Else Example

Below is an example using If/Else in xphp to display a default image in your profile details page when the person does not have a photo:

1
2
3
4
5
6
7
8
9
10
11

<xphp content="true">
  <if var="profiles_image"/>
    <content>
      <xphp var="profiles_image"/>
    </content>
  <else content="true">
    <content>
      <img src="/path/to/default_image.png"/>
    </content>
  </else>
</xphp>

In this example, we see we can use <xphp var="foo"/> to display an XPHP variable directly.

AND & OR Operators

By default, XPHP if statements are treated as ANDs when two or more variables must meet the conditions set, but you can switch to an OR relationship with the addition of only one attribute on the surrounding <xphp> tag.

1
2
3
4
5
6
7
8

<!-- the default AND state -->
<xphp content="true">
  <if var="a"/>
  <if var="b"/>
    <content>
      <p>A and B are both non-empty.</p>
    </content>
</xphp>

1
2
3
4
5
6
7
8

<!-- with the addition of the ifmode="or" attribute, the comparison becomes an OR -->
<xphp content="true" ifmode="or">
  <if var="a"/>
  <if var="b"/>
    <content>
      <p>Either A or B is non-empty.</p>
    </content>
</xphp>

XPHP Conditional Functions

You can alter the <if> statements above, mixing and matching from the following library, to execute all sorts of logical tests:

Using other variables (POST, GET) in your if statements

By default, the above tests will check for your variables in the XPHP Dictionary (also known as $_GLOBALS in PHP). You can use the type attribute to check variables from server, get, or post.

Checking for elements on the page

You can also use XPHP to check for certain elements in the source code of the current page, using the has_element function. Your check can match any valid single CSS selector in the following forms:

1
2
3
4
5
6
7
8

<if has_element="span"/>
<if has_element="#aaa"/>
<if has_element=".bbb"/>
<if has_element="span#aaa"/>
<if has_element="span.bbb"/>
<if has_element="span#aaa.bbb"/>
<if has_element="#aaa.bbb"/>
<if has_element="#aaa.bbb.ccc"/>

This is especially useful if, for example, you want a section of your page to display only if <div id="sidebar"> exists (<if has_element="div#sidebar"/>).

Note: The element must exist in the page before the <if> statement in question is reached. This may mean, if you have other page changes being output from another XPHP statement, it could not be caught by this logical test.

XPHP Tools

In addition to the above conditional statements and logical tests, XPHP has several tools that you can use to make your website more responsive, intelligent, or fun.

Advanced: Extracting specific HTML elements from an XPHP variable

Sometimes you may want to extract only a specific HTML object from an existing XPHP variable. In LiveWhale 2.0.0 and later, you can use selector="" in your <xphp> variables (and, in widget formats, with <field> variables) to do just that.

This advanced tool supports the XPath syntax (cheatsheet). selector="//foo will grab the element <foo> wherever it appears. See below for some examples.

Timely Content

You can use XPHP to show content before/after a certain date, or daily before/after a certain time.

LiveWhale 1.7.1+

Starting with LiveWhale 1.7.1 you can define timely content with the simple attributes start and end. You can also preview timely content from other dates/times by adding ?lw_preview_date= to your URL. e.g., /my-page/?lw_preview_date=April 7

You can use any PHP-readable date/time strings in your schedules and preview links (dates, dates with times, or just times for daily repeating schedules).

1
2
3
4
5
6

<xphp content="true" end="2020-11-28">
<content>Countdown to our Day of Giving...</content>
</xphp>
<xphp content="true" start="2020-11-28">
<content>Today is Day of Giving!</content>
</xphp>

1
2
3
4
5
6
7
8
9

<xphp content="true" end="12pm">
<content>Good morning!</content>
</xphp>
<xphp content="true" start="12pm" end="5pm">
<content>Good afternoon!</content>
</xphp>
<xphp content="true" start="5pm">
<content>Good night!</content>
</xphp>

LiveWhale 1.7 and before

In previous versions of LiveWhale, you can define your schedule with before_date and after_date, and you can preview timely content by adding ?xphp_request_time=XXX to your URL, replacing XXX with a timestamp. These methods are still supported for backwards-compatibility.

1
2
3
4
5
6

<xphp content="true" before_date="2020-11-28">
<content>Countdown to our Day of Giving...</content>
</xphp>
<xphp content="true" after_date="2020-11-28">
<content>Today is Day of Giving!</content>
</xphp>

Using XPHP Variables Inside Quotes

In LiveWhale 1.6.2+, you can use the following XHTML-friendly syntax to place XPHP variables inside other XPHP or HTML tags and attributes. You do so by replacing <xphp var="my_variable" /> with %%xphp_my_variable%%. For example, if you have <xphp var="start_date" /> set, you can use:

1
2
3

<xphp content="true" after_date="%%xphp_start_date%%">
<content>Today is Day of Giving!</content>
</xphp>

Or even in simpler cases, you can use the %% format where you want to nest XPHP code inside other tags:

1
2

This is the URL: <xphp var="href" />
<a href="%%xphp_href%%">Read more</a>

Note, this syntax only works for individual XPHP variables and not for larger chunks of XPHP logic.

Specifying Type and Cast

In LiveWhale 1.7+, you can also use the %%xphp_ format for variables of alternate types (GET, POST, COOKIE, SERVER) and casts (encoded, decoded, text, urlencoded, obfuscated, uppercase, lowercase, uppercase-first, uppercase-words, int, bool, float, string).

The format is %%xphp_variable|TYPE|CAST:value%% with |TYPE and |CAST:value both being optional. You can also use multiple casts by separating them with spaces. A few examples are below:

XPHP Variables Dictionary

Site-wide Variables

Server Variables

Examples are from the URL https://www.myschool.edu/folder/my-page/?foo=bar

Note: The special variable <xphp var="server_path_flat" /> returns the contents of server_dirname but with / replaced with -. This has been used in some legacy Jumpchart integrations and may not be too useful nowadays.

Page Variables

Group Variables

Note: Groups that use the main navigation of another group also inherit all group_* variables from that group.

Using Page and Group Variables in an include:

When using a file widget, LiveWhale will include the full source code into your page, meaning you can use context-specific variables like <xphp var="group_title"/>. However, when you append any GET variables (?foo=bar) to a file widget path, LiveWhale will instead make an HTTP request for that URL and then use the response, meaning context-specific variables like <xphp var="group_title"/> won’t work in that include, since LiveWhale doesn’t see /_ingredients/includes/my-include.php as belonging to any particular group.

Time

Tags

Details Template Variables

Please note, XPHP variables for details pages are prefixed with details_. If your site was built using LiveWhale 1.6 or before, you may see in your details templates some variable prefixed with events_, forms_, news_, etc. However, since LiveWhale 1.6.1, details_ is the correct prefix for those variables (others are supported for backwards compatibility).

Events

Forms

Galleries

News

Profiles

Blurbs