File widgets are handy for including headers, footers, or other consistent blocks of code you don’t want to be messing with in the WYSIWYG editor.

Basic File Includes

<widget type="file">
        <arg id="path">/_ingredients/includes/header.html</arg>
</widget>

<xphp include="/_ingredients/includes/header.html" />

Customizable File Includes

Sometimes, you might have a code block that you re-use almost identically a number of places. For example, Blackbaud/Raiser’s Edge generates embedded forms that are all the same except for a single ID string.

If you’ve received code like this:

<div id="bbox-root"></div>
<script type="text/javascript">
  window.bboxInit = function () {
    bbox.showForm(’0000000-0000-0000-0000-000000000000');
  };
  (function () {
    var e = document.createElement('script'); e.async = true;
    e.src = 'https://bbox.blackbaudhosting.com/webforms/bbox-min.js';
    document.getElementsByTagName('head')[0].appendChild(e);
  } ());
</script>

You can save that code in your includes folder (/_ingredients/templates/includes/bbox.php) and use a file widget to insert it on any page:

<widget type="file">
  <arg id="path">/_ingredients/templates/includes/bbox.php</arg>
</widget>

However, then you’d be having to create a new include for each form.

Instead, let’s set that ID value on-the-fly.

Save the following in /_ingredients/templates/includes/bbox.php, replacing the ID with the PHP snippet <?php echo htmlentities(strip_tags($_GET['id']));?>

<div id="bbox-root"></div>
<script type="text/javascript">
  window.bboxInit = function () {
    bbox.showForm('<?php echo htmlentities(strip_tags($_GET['id']));?>');
  };
  (function () {
    var e = document.createElement('script'); e.async = true;
    e.src = 'https://bbox.blackbaudhosting.com/webforms/bbox-min.js';
    document.getElementsByTagName('head')[0].appendChild(e);
  } ());
</script>

Then you can insert any form by typing the following into the View Source window of a WYSIWYG editor, substituting in the id of your given form.

<widget type="file">
        <arg id="path">/_ingredients/templates/includes/bbox.php?id=0000000-0000-0000-0000-000000000000</arg>
</widget>

You can extend this technique to any number of uses.

Note: 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.

Selecting content with “extract”

Most of the time, when using <widget type="file"> you’re grabbing and including the entire contents of that file on your page. But, what if you wanted to grab only a portion of it? What if it’s a web page?

That’s what <arg id="extract"> is for.

<widget type="file">
  <arg id="path">/about/mission/index.php</arg>
  <arg id="extract">mission-statement</arg>
</widget>

The above example grabs the entire /about/mission/ page, but only includes the <div id="mission-statement"> and its contents.

If you want only the contents and not also the container, you can set extract_contents=true .

<widget type="file">
  <arg id="path">/about/mission/index.php</arg>
  <arg id="extract">mission-statement</arg>
  <arg id="extract_contents">true</arg>
</widget>