Using a Customizable File Widget

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.

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:

1
2
3
4
5
6
7
8
9
10
11
<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:

1
2
3
<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']));?>

1
2
3
4
5
6
7
8
9
10
11
<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.

1
2
3
<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.

1
2
3
4
<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 (LiveWhale 1.7.1+).

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