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:
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:
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']));?>
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.
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.
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?
<arg id="extract"> is for.
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+).