Sourcerer

Place any code in Joomla!

  • Last updated: 13 Sep 2019
  • Version: 8.2.0
  • Types: System plugin Editor button plugin
  • Joomla rating: 100%

Tutorial for Sourcerer

There is a Free and a Pro version of Sourcerer.
The parts in this tutorial that only concern the Pro version will be marked with: Pro only

Introduction

Sourcerer is a Joomla system plugin (that also comes with an editor button plugin).

Sourcerer enables you to place PHP and any kind of HTML, CSS and JavaScript code right into your content! Not only in your articles, but also in categories, modules, components, the head of the HTML page, etc.

You can simply place your custom codes right into your WYSIWYG Editor. The only thing you have to do is surround the code with the Sourcerer plugin tags. Easy peasy!

So with Sourcerer, now you can also use PHP scripts in your content. That opens up a great deal of possibilities.

Normally, most Joomla! Text Editors will strip parts of your HTML code, like JavaScripts (e.g. statistics scripts) and video embed tags. With Sourcerer you won't have these limitations.

How to use it (syntax)

The syntax is very simple.
Just place a starting {source} tag and an ending {/source} tags in the text area where you want the code to appear (like an article or Custom HTML module).

Then, simply place your code between these tags. For example:

{source}
<script type="text/javascript">
    document.write('This text is placed through JavaScript!');
</script>
{/source}

You can place the tags inside your content to output the result of simple or complex PHP code:

Hi {source}<?php echo $user->name; ?>{/source}! Welcome back.

And you can of course also combine multiple codes of various types in one single block:

{source}
<h2>Some HTML code here</h2>

<script>
    RunSomeJavaScriptFunction();
</script>

<h4>Welcome <?php echo $user->name; ?></h4>

<p>&gt;&gt; And some more funky HTML code!</p>
{/source}

It's important to note that you should place the code in the WYSIWYG view of the editor, NOT in the HTML/Code view of the editor.

You can find some simple examples of how to place code with Sourcerer in the Examples Page.

You can also use the Sourcerer editor button to make the process even easier.

Loading CSS Styles and JavaScript

You can add CSS styles or JavaScript code to the head of the HTML output, by using Joomla's built-in document functions.

Sourcerer already creates the $document (or $doc) object for you when it is needed. So you do not have to initialize this yourself.

CSS Styles or Files

To place a piece of CSS code, use:

{source}<?php 
$mycss = "
body {
background-color: red;
}
";
$doc->addStyleDeclaration( $mycss );
?>
{/source}

To add a CSS File to the head, you can use:

{source}<?php
$doc->addStyleSheet( JURI::root( true ).'/path/to/your/file.css' );
?>
{/source}

Quick syntax Pro only

With the Pro version of Sourcerer, you can add CSS files to the head of the document with an easier, shorter syntax. Simply use the css attribute (or style can also be used), and enter the path of the file:

{source css="path/to/your/file.css"}{/source}

You can even enter multiple files at once, separating them with a comma:

{source css="path/to/your/file1.css,path/to/your/file2.css,path/to/your/file3.css"}{/source}

JavaScript Scripts or Files

To place a piece of JavaScript code, use:

{source}<?php 
$myscript = "
alert('This is JavaScript');
";
$doc->addScriptDeclaration( $myscript );
?>
{/source}

To add a JS File to the head, you can use:

{source}<?php
$doc->addScript( JURI::root( true ).'/path/to/your/file.js' );
?>
{/source}

Quick syntax Pro only

With the Pro version of Sourcerer, you can add JS files to the head of the document with an easier, shorter syntax. Simply use the js attribute (or script can also be used), and enter the path of the file:

{source js="path/to/your/file.js"}{/source}

You can even enter multiple files at once, separating them with a comma:

{source js="path/to/your/file1.js,path/to/your/file2.js,path/to/your/file3.js"}{/source}

With the Pro version, you can also use the Sourcerer editor button to help you enter your files and code.

Note: When you use the $document or $doc inside modules (Custom HTML modules), remember to switch on the "Prepare Content" option.

Including Files

PHP Files

When using large pieces of PHP code, or you want to reuse the same piece of code in multiple places, it is wise to put this code in a separate PHP file.

For example, to include the PHP file located at yourdomain.com/myfiles/file.php, you can do:

{source}<?php
include JPATH_SITE.'/myfiles/file.php';
?>
{/source}

Setting variables for a PHP File

If you want to set variables that are used in the PHP file, you can simply set them before the include/require, like:

{source}<?php
$name = 'Peter';
$surname = 'van Westen';
$interests = array( 'small fluffy things', 'green cantaloupe', 'toothpaste', '9V batteries' );
include JPATH_SITE.'/myfiles/file.php';
?>
{/source}

Quick syntax Pro only

With the Pro version of Sourcerer, you can include PHP files with an easier, shorter syntax. Simply use the php attribute (or file can also be used), and enter the path of the file:

{source php="myfiles/file.php"}{/source}

You can even enter multiple files at once, separating them with a comma:

{source php="myfiles/file1.php,myfiles/file2.php,myfiles/file3.php"}{/source}

And then you can, of course, also place additional PHP inside the tags.

For instance, if you set variables inside the PHP file, you can then use/manipulate them further in the PHP block:

{source php="myfiles/file.php"}<?php
   echo '<div class="mydiv">' . $var_from_file . '</div>';
?>{/source}

Include Method Pro only

The method above will simply include the file.

But if you have a PHP file with classes and functions in it, you will get issues when including the file more than once on your page. In that case it is better to only make it include/require the file once.

When using the short syntax, you can also specify the Include Method you want to use for the PHP file.

To do this, instead of the generic php attribute (which equals to include), you can use one of the following four attributes to specify the Include Method:

{source include="myfiles/file.php"}{/source}
{source include_once="myfiles/file.php"}{/source}
{source require="myfiles/file.php"}{/source}
{source require_once="myfiles/file.php"}{/source}

With the Pro version, you can also use the Sourcerer editor button to help you enter a PHP file and easily select your desired Include Method.

Text or HTML Files

For text files, like .txt or .html you could use this syntax:

{source}<?php
echo file_get_contents( JPATH_SITE.'/myfiles/file.txt' );
?>
{/source}

Dealing with Document structures

Please keep in mind that files you include SHOULD NOT generate their own html structure (<html>, <head>, <body> tags) inside your content.

When you include a file, it will be placed inside your Joomla content, which is already inside a full HTML structure. If you place structure tags in your content, you will get invalid HTML, which can cause all sorts of issues.

So if you want to load in html files, or when copying code from some ready-made html/script, make sure you only place the text part (what is inside the <body> tags) into your content.

If you include a PHP file, it should also not output any of these main html structure parts. Otherwise you will either have to use iframes or use some more advanced PHP code to strip the html structure away.

If you need to add CSS or JavaScript to the head of your page, you can do so via PHP. See above: How to add code to the head of the HTML page.

Using PHP code

When placing PHP code, you have access to anything available in PHP itself. But also to anything Joomla makes available.

This means you can access and output any session data, user data, connect to the database, and a whole lot more.

If you know your PHP, you know that the sky is the limit!

Ready-to-use PHP Variables & Objects

Sourcerer checks your PHP code to see if you are referencing any commonly used Joomla objects / variables, and then creates them for you.

This means you don't have to create these variables yourself every time.

Currently Sourcerer creates these variables ready for use:

  • $app The Joomla application framework
  • $document or $doc The html document
  • $database or $db The database
  • $user The user object containing the details of the guest or current logged in user
  • $Itemid The menu id of the page
  • $article The article object (only available when using the code inside articles)

Connecting to the Database

Internal Database

If you want to do database calls to get data from it (or write data to it), you can use Joomla's built-in database object and functions.

Sourcerer already creates the $database (or $db) object for you when it is needed. So you do not have to initialize this yourself.

So for example, you can directly do:

{source}<?php
$query = "SELECT something from #__mydatabasetable WHERE this = 'that'";

$database->setQuery($query);
$result = $database->loadResult();

// Do something with $result
?>
{/source}

Or better (more stable):

{source}<?php
$query = $db->getQuery(true)
->select($db->quoteName('something'))
->from('#__mydatabasetable')
->where($db->quoteName('this').' = '.$db->quote('that'));

$db->setQuery($query);
$result = $database->loadResult();

// Do something with $result
?>
{/source}

For more information on how to use the Joomla Database object: docs.joomla.org/How_to_use_the_database_classes_in_your_script

External database

To connect to an external database, use:

{source}<?php
  $option = array(
    'driver'   => 'mysql', // Database driver name
    'host'     => 'db.myhost.com', // Database host name
    'user'     => 'my_username', // User for database authentication
    'password' => 'my_password', // Password for database authentication
    'database' => 'my_database', // Database name
    'prefix'   => 'abc_', // Database prefix (may be empty)
  );
  $db = JDatabaseDriver::getInstance( $option );

// Do something with the $db object ?>
{/source}

Editor Button

You can enter the tags directly into your content. However, to save time typing and remembering what the exact syntax is, Sourcerer comes with a handy editor button.

When clicking on this "Code" button (located below the text input area) you will get a modal popup with the Sourcerer code editor.

This can help you enter your code in a dedicated field. And with the Pro version you can use extra tabs to more easily insert specific CSS, JavaScript and PHP files and code.

After clicking on the "Insert" button, that code will be generated into your article/content editor.

We recommend you always use this editor button to enter code, as it prevents your content editor from messing up the code.

To edit code that is already in your article/content item, simply select the code - including the {source} tags, and click on the Sourcerer editor button. The selected code and attributes will appear in the Sourcerer editor. And after clicking on the "Insert" button, the new code will replace the selected code.

Advanced Security Pro only

The Pro version of Sourcerer gives you Advanced Security control. This means you can control who can use what features of Sourcerer on your website.

Prevent registered users from placing Sourcerer code on your forum or message board? Sourcerer Pro has you covered.

Don't want your authors to be able to place PHP code, but let them place JavaScript through Sourcerer? No problem.

See the different Security tabs in the Sourcerer system plugin settings for all the different options and settings.

Troubleshooting

Alternative double bracket syntax

Some editors (i.e. TinyMCE) will strip HTML style tags when you enter them in the WYSIWYG view. For that reason you can also use double square brackets for the HTML style tags. So if your tags get stripped, use the double bracket syntax.

For instance, instead of doing this:

{source}<strong>Text</strong>{/source}

You can also do this:

{source}[[strong]]Text[[/strong]]{/source}

Using HTML entities

When you want to use html entities in your code, you will notice that most editors will convert them to actual characters when saving.

You can prevent that from happening by adding an underscore (_) after & to escape it, like:

{source}Sch&_ouml;n{/source}

Not using a WYSIWYG editor?

Sourcerer is designed to be used with a WYSIWYG editor. It will strip all tags entered in the HTML/Code view of the content, to prevent styling from messing with the code.

When you do not use a WYSIWYG editor (or the field where you want to enter the code has no editor), practically all code would be stripped, which you don't want of course.

To prevent Sourcerer from stripping the HTML code, you can add a 0 parameter in the {source} tag, like:

{source 0}Code in an HTML editor{/source}

Or you can add a raw="true" attribute, both syntaxes will work the same:

{source raw="true"}Code in an HTML editor{/source}

Strip surrounding HTML tags

By default Sourcerer will output your code right inside your content where you placed your {source} tags.

However, most editors treat new lines as paragraphs, meaning that the {source} tags will get surrounded by <p> tags.

If you - for instance - include a file through Sourcerer that outputs a table, and your {source} tags are surrounded by <p> tags, then you would get a table inside a paragraph, which you don't want of course.

To make Sourcerer remove the surrounding paragraph tags (or span tags), you can switch on the Strip surrounding tags option in the Sourcerer system plugin settings.

Or you can individually override this setting in the {source} tag by adding a trim="..." attribute with either a true (on) or false (off) value:

<p>{source trim="true"}Surrounding paragraph will be stripped from the output{/source}</p>

For more troubleshooting tips in case something doesn't work as expected, check out the Frequently Asked Questions page.

Settings

Sourcerer is packed with options, giving you control over how it works and behaves. Here is the full list of the options you can find in the Sourcerer system plugin settings:

Security - Default

Here you can set what kind of code can be used within the Sourcerer tags. All code that is not permitted will be stripped away.

CSS

Allow CSS tags If enabled, CSS (style & link) tags are permitted within the Sourcerer tags. Otherwise the CSS tags (and the CSS code within) will be stripped.

JavaScript

Allow JavaScript tags If enabled, JavaScript (script) tags are permitted within the Sourcerer tags. Otherwise the JavaScript tags (and the JavaScript code within) will be stripped.

PHP

Allow PHP tags If enabled, PHP tags are permitted within the Sourcerer tags. Otherwise the PHP tags (and the PHP code within) will be stripped.
Forbidden PHP functions A comma separated list of PHP functions that are forbidden. The whole PHP block of code will not be executed if it contains any of these functions.
Forbidden (HTML) Tags A comma separated list of tags that are forbidden. These tags will be stripped, and also any code in between double tags.

Security - Articles Pro only

These settings have effect on Articles and Categories. The security settings only have effect on articles.

Enable in articles Select whether to enable the use of the syntax in articles.
Security Level Set the level of security. Sourcerer tags will be stripped from articles where the an owner (creator) is not a member of these groups.

CSS

Allow CSS tags If enabled, CSS (style & link) tags are permitted within the Sourcerer tags. Otherwise the CSS tags (and the CSS code within) will be stripped.
CSS Security Level Set the level of security. CSS tags (and the CSS code within) will be stripped from articles with an owner (creator) below this group level. If the overall security level is set higher, it will overrule this.

JavaScript

Allow JavaScript tags If enabled, JavaScript (script) tags are permitted within the Sourcerer tags. Otherwise the JavaScript tags (and the JavaScript code within) will be stripped.
JavaScript Security Level Set the level of security. JavaScript tags (and the JavaScript code within) will be stripped from articles with an owner (creator) below this group level. If the overall security level is set higher, it will overrule this.

PHP

Allow PHP tags If enabled, PHP tags are permitted within the Sourcerer tags. Otherwise the PHP tags (and the PHP code within) will be stripped.
PHP Security Level Set the level of security. PHP tags (and the PHP code within) will be stripped from articles with an owner (creator) below this group level. If the overall security level is set higher, it will overrule this.
Extra Forbidden PHP functions A comma separated list of PHP functions to add to the forbidden list (see Default settings)
Extra Forbidden (HTML) Tags A comma separated list of tags to add to the forbidden list (see Default settings)

Security - Components Pro only

These settings have effect on the component area.
You can select in which components Sourcerer should not be enabled. Advise is to not allow Sourcerer in components that non-backend users can post content in.

Enable in components Select whether to enable the use of the syntax in components.
Disable on components Select which components NOT to enable Sourcerer in. This is a list of your installed frontend components.

CSS

Allow CSS tags If enabled, CSS (style & link) tags are permitted within the Sourcerer tags. Otherwise the CSS tags (and the CSS code within) will be stripped.

JavaScript

Allow JavaScript tags If enabled, JavaScript (script) tags are permitted within the Sourcerer tags. Otherwise the JavaScript tags (and the JavaScript code within) will be stripped.

PHP

Allow PHP tags If enabled, PHP tags are permitted within the Sourcerer tags. Otherwise the PHP tags (and the PHP code within) will be stripped.
Extra Forbidden PHP functions A comma separated list of PHP functions to add to the forbidden list (see Default settings)
Extra Forbidden (HTML) Tags A comma separated list of tags to add to the forbidden list (see Default settings)

Security - Other Areas Pro only

These settings have effect on the areas outside the component area (so in Modules and the rest of the website).

Enable other areas Select whether to enable the use of the syntax in all remaining areas, like the modules and the document head.

CSS

Allow CSS tags If enabled, CSS (style & link) tags are permitted within the Sourcerer tags. Otherwise the CSS tags (and the CSS code within) will be stripped.

JavaScript

Allow JavaScript tags If enabled, JavaScript (script) tags are permitted within the Sourcerer tags. Otherwise the JavaScript tags (and the JavaScript code within) will be stripped.

PHP

Allow PHP tags If enabled, PHP tags are permitted within the Sourcerer tags. Otherwise the PHP tags (and the PHP code within) will be stripped.
Extra Forbidden PHP functions A comma separated list of PHP functions to add to the forbidden list (see Default settings)
Extra Forbidden (HTML) Tags A comma separated list of tags to add to the forbidden list (see Default settings)

Editor Button Options

Button Text This text will be shown in the Editor Button.
Enable in frontend If enabled, it will also be available in the frontend.

Tag Syntax

Sourcerer tag word This defines the word to use as the Sourcerer syntax tag.

Default is 'source'. Which means the tags to use are: {source}...{/source}
Tag Characters The surrounding characters of the tag syntax.

Note: If you change this, all existing tags will not work anymore.

Options: {...}, [...], {{...}}, [[...]], [:...:], [%...%]

Advanced

Strip Surrounding Tags Select to always remove html tags (div, p, span) surrounding the plugin tag. If switched off, the plugin will try to remove tags that break the html structure (like p inside p tags).
Enable in Head Select to also handle the Sourcerer tags inside the document head section of the page. If unselected, any Sourcerer tags found in the head will get removed (together with any code inside them).
Remove from search Select to remove the Sourcerer tags and content from the search results.
Include Path The path (relative to the root folder) to use when including PHP files with the php attribute in the tag.
Path to Temp Folder Please specify a writable folder to store temporary files. Leave empty to use the Joomla global Temp Folder
Place HTML comments By default HTML comments are placed around the output of this extension.
These comments can help you troubleshoot when you don't get the output you expect.
If you prefer to not have these comments in your HTML output, turn this option off.

Installation

You can either install Sourcerer by using the core extension manager available in the Joomla! Administrator Control Panel, or by using the powerful Regular Labs Extension Manager.

Note: When updating Sourcerer, you do not need to uninstall it first. The package will update all the files automatically.

Keep in mind that when you update to a major new version (or uninstall first), you might lose some configuration settings.

Regular Labs Extension Manager

It is very easy to install/update any Regular Labs Extension using the Regular Labs Extension Manager.

Please see the Tutorial for the Regular Labs Extension Manager for more detailed information...

Joomla! Extension Manager

To install via the Joomla! Extension Manager, just follow these steps:

  1. Log into your Joomla administrator;
  2. In the menu, choose: Extensions >> Extensions;
  3. Choose the tab: Install from Web (or enable it if you haven't done so yet);
  4. Select the search field and enter Sourcerer and hit enter;
  5. Click on the Sourcerer listing;
  6. Click on Install;
  7. Click on Install to confirm.
Installer Web

Or if you need to install the Pro version or cannot install via the 'Install via Web' method for some reason:

  1. Download the extension install file (.zip);
  2. Log into your Joomla administrator;
  3. In the menu, choose: Extensions >> Extensions;
  4. Choose the tab: Upload Package File;
  5. Click on the Choose File button and select the extension zip;
  6. Click on Upload & Install.
Installer Upload

If you have problems installing Sourcerer, please try the manual installation process as described here: docs.joomla.org/Installing_an_extension