Tutorial:

Introduction

Sourcerer is a Joomla! system plugin (and editor button plugin).

Sourcerer enables you to place PHP and any kind of HTML style code (including CSS and JavaScript) right into your content! Not only in your articles, but also in sections, categories, modules, components, META tags, etc.

You can now just place your original codes right into your WYSIWYG editor. The only thing you have to do is surround the code with the Sourcerer tags. Easy peasy!

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

Most Joomla! Text Editors will strip parts of your HTML code, like JavaScripts (think of statistics scripts) and movie embed tags. With Sourcerer you won't have these limitations.

Syntax

The syntax is pretty simple. Just place {source} and {/source} tags in text area you want the code to appear (like an article or Custom HTML module), and place your code between the tags.

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

You should place the code in your WYSIWYG editor, and NOT in the HTML view of the editor.

Using the 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}

Use this syntax:

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

PS: The Sourcerer editor button will help you convert code to double bracket syntax (or back to normal tags).

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 using an underscore to escape it, like:

{source}Dani&_euml;lle{/source}

Not using a WYSIWYG editor?

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

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

To disable Sourcerer from stripping the html code, you can use the '0' parameter in the {source} tag, like:

{source 0}code in an html editor{/source}

PS: You don't have to add this 0 to the tag when using {source} tags in the replace fields of ReReplacer. ReReplacer is smart enough to pass the code onto Sourcerer in the {source 0} way.

Remove surrounding html tags

By default Sourcerer will place whatever the output is right inside your content where you place your {source} 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 will get a table inside a paragraph.

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

Or add a trim=1 attribute to the {source} tag: {source trim=1}

Examples

Here are some simple examples of how to place code.

HTML tags

Code

{source}<span style="color:red">This text should be red!</span>{/source}

Result

This text should be red!

HTML tags (with double square brackets)

If your editor has problems saving tags entered in the WYSIWYG view, and strips these upon saving, then you can use the double bracket syntax for tags.
So [[tag]] instead of <tag>.

Code

{source}[[span style="color:red"]]This text should be red![[/span]]{/source}

Result

This text should be red!

JavaScript

Code

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

Result

PHP

Code

{source}
<?php
    echo 'This text is placed through <strong>PHP</strong>!';
?>
{/source}

Result

This text is placed through PHP

Combined (HTML, JavaScript and PHP)

Code

{source}
<span style="color:red">This text should be red!</span>
<br />
<script type="text/javascript">
    document.write('This text is placed through <strong>JavaScript</strong>!');
</script>
<?php
    echo '<p>';
    echo 'This text is placed through <strong>PHP</strong>!';
    echo '</p>';
?>
{/source}

Result

This text should be red!

This text is placed through PHP

More examples

Find more examples and ways to implement certain code in the FAQs.

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 'Insert Code' editor button (located below the text input area) you will get a modal popup with the Sourcerer code editor.
This code editor will display the example code, which you can change to meet your needs. After clicking on the 'Insert' button, that code will be placed back into your article/content editor.

I recommend you always use this editor button to insert 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 will appear in the Sourcerer editor. And after clicking on the 'Insert' button, the new code will replace the selected code.

You can customise the default tag and editor button settings in the Sourcerer system plugin settings.

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:

Advanced Settings

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: {...}, [...], {{...}}, [[...]], [:...:], [%...%]
Remove surrounding tags Select to remove surrounding paragraph and span tags.
Include Path The path (relative to the root folder) to use when using the file attribute in the tag.

Security Settings - 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. For more precise settings, see the Advanced Security settings.

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 Settings - 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 Settings - 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 Settings - 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.

Defaults

These setting have effect on the initial settings when you open the Sourcerer Code Helper window.

Add {source} tags If selected, the code will be surrounded by {source} tags (if the tags are not already in the code).
Use Example Code If enabled, the example code below will be placed inside the Sourcerer tags.
Example Code Here you can place the example code you want to be placed inside the Sourcerer tags. If you leave this field empty and save it, this field will be reset to the default example code.
FAQs:

I'm getting fatal PHP errors about redeclaring functions in Joomla 3.8.0

Due to a change (bug!) in Joomla 3.8.0, plugins are triggered twice over the same article content. This will cause Sourcerer to execute the code you place in the content twice as well.

This is fixed with Joomla 3.8.1, so make sure you update your Joomla version.

You can also solve this by placing any classes and/or functions you have in your custom php code you place via Sourcerer in a separate file.
Then you can use require_once in your Sourcerer code to load these classes and/or functions.

This has the added benefit that you can reuse these custom classes/functions in other places by simply loading them in where you need them.

Also it is usually easier to edit/maintain/test code in a separate php file than having it inside {source} tags in an article.

Also see the more indepth infromation on how to include files via Sourcerer.

The {source} tags are not being converted

The Sourcerer plugin is not published

Check if the Sourcerer plugin is published. Go to Extensions >> Plugin manager and search for the system plugin "System - Regular Labs Sourcerer". Then publish it.

There is markup code in the Sourcerer syntax tags

Sourcerer has no problem with markup codes between the {source} tags. However, the {source} tags themselves will have to be free from markup. So this will make the {source} block from working:

<span>{</span>source}

Remove the extra styling or other html tags around and in the {source} tags that might cause problems.

Code is stripped when I save the article

Make sure you are using the WYSIWYG view of your editor.

Some editors remove tags you enter in the editor (even if not in html view).

To prevent tags from being stripped, use the double bracket syntax. So instead of <tag>, do [[tag]].

Some editors (like JCE) do allow you to enter tags in the WYSIWYG view, but you may have to change some settings in the editor.

Code is stripped on the frontend
(In the editor the code is all there)

The security level prevents the use of Sourcerer

You can set certain security settings in the Sourcerer plugin. This way you can prevent certain user group levels and certain content types to not allow the use of Sourcerer. Please look in the html output source of you site to see if you have a Sourcerer comment that tells you this is the case.

Using JavaScript or PHP in the tags?

Some editors remove tags you enter in the editor (even if not in html view).

To prevent tags from being stripped, use the double bracket syntax. So instead of <tag>, do [[tag]].

Some editors (like JCE) do allow you to enter tags in the WYSIWYG view, but you may have to change some settings in the editor.

JavaScript is not working

You have forgotten the script open- and close-tags

JavaScript should be placed inside the script tags:

<script type="text/javascript">...</script>

Or for double bracket syntax:

[[script type="text/javascript"]]...[[/script]]

The security level prevents the use of JavaScript

You can set certain security settings in the Sourcerer plugin. This way you can prevent certain user group levels and certain content types to not allow the use of JavaScript. Please look in the html output source of you site to see if you have a Sourcerer comment that tells you this is the case.

PHP is not working

You have forgotten the PHP open- and closetags

PHP should be placed inside the PHP tags

<?php ... ?>

Or for double bracket syntax:

[[?php ... ?]]

The security level prevents the use of PHP

You can set certain security settings in the Sourcerer plugin. This way you can prevent certain user group levels and certain content types to not allow the use of PHP. Please look in the html output source of you site to see if you have a Sourcerer comment that tells you this is the case.

There are errors in your PHP code

Sourcerer will not execute your PHP code if it has errors. You can check if you have errors by looking in the html output source of you site to see if you have a Sourcerer comment that tells you this is the case.

How to add CSS to the head of the html page

You can add css styles to the head of the html output 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.

To place a piece of 'inline' css code, use:

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

To add a css file to the head, use:

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

To add multiple stylesheets and javascripts, you can place 1 php block like:

{source}<?php
   $css = "
      body {
         color: red;
      }
   ";
   $doc->addStyleDeclaration( $css );
   $doc->addStyleSheet( JURI::root( true ).'/path/to/your/file.css' ); 
   $doc->addStyleSheet( JURI::root( true ).'/path/to/your/file2.css' );
   $script = "
      alert('this is javasript');
   ";
   $doc->addScriptDeclaration( $script );
   $doc->addScript( JURI::root( true ).'/path/to/your/file.js' ); 
   $doc->addScript( JURI::root( true ).'/path/to/your/file2.js' ); 
?>{/source}

PS: When you use the $document or $doc in (custom HTML) modules, remember to switch on the Prepare content option.

How to add Javascript to the head of the html page

You can add Javascript code or files to the head of the html output 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.

To place a piece of 'inline' Javascript code, use:

{source}<?php 
$script = "
alert('this is javasript');
";
$doc->addScriptDeclaration( $script );
?>{/source}

To add a js file to the head, use:

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

To add multiple stylesheets and javascripts, you can place 1 php block like:

{source}<?php
   $css = "
      body {
         color: red;
      }
   ";
   $doc->addStyleDeclaration( $css );
   $doc->addStyleSheet( JURI::root( true ).'/path/to/your/file.css' ); 
   $doc->addStyleSheet( JURI::root( true ).'/path/to/your/file2.css' );
   $script = "
      alert('this is javasript');
   ";
   $doc->addScriptDeclaration( $script );
   $doc->addScript( JURI::root( true ).'/path/to/your/file.js' ); 
   $doc->addScript( JURI::root( true ).'/path/to/your/file2.js' ); 
?>{/source}

PS: When you use the $document or $doc in (custom HTML) modules, remember to switch on the Prepare content option.

How to include a file

Including a php file

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.
Then you can simply include the file with a single line through Sourcerer.

Example PHP file:
www.yourdomain.com/myfiles/file.php

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

You can also place php inside the tags. For instance, if you set variables inside the php file, you can use/manipulate them further in the php block:

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

This will simply include the file. If you have a php file with classes and functions in it, you will get issues when including the file more than once. In that case it is better to use php to only make in include/require the file once:

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

include/require vs require_once

You can also use 'include' (or 'require') instead of 'require_once', but only use that if you need the file included more than once on your page.
If your php file creates classes / functions, having it included more than once will cause errors like "Cannot redeclare class".

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 require/include, like:

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

Including a text or html file

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

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

NO html structures

Please keep in mind that files you include SHOULD NOT generate their own html structure (<html>, <head>, <body> tags).
If you include a file, it will be placed inside your Joomla content, which is already inside a full html structure.

So if you want to load in html files, make sure they only contain the text part (what is inside the <body>).
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.

Also see: What to do with <head> or <body> tags?

What to do with <head> or <body> tags?

You SHOULD NOT add any main html structure tags (<html>, <head>, <body> tags) inside your content.
Joomla already creates the full html structure. So if you place structure tags in your content, you will get invalid html, which can cause all sorts of issues.

When copying code from some ready-made html/script, make sure you only place the part that is inside the <body> tags into your content.

If you need to add css or javascript to the head of your page, you can do so via PHP. See:

How to connect to the 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();
?>{/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();
?>{/source}

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

How to connect to an external database

{source}<?php
  $option = array(
    'driver'   => 'mysql', // Database driver name
    'host'     => 'db.myhost.com', // Database host name
    'user'     => 'fredbloggs', // User for database authentication
    'password' => 's9(39s£h[%dkFd', // Password for database authentication
    'database' => 'bigdatabase', // Database name
    'prefix'   => 'abc_', // Database prefix (may be empty)
  );
  $db = JDatabase::getInstance( $option );
  ?>{/source}

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

What variables & objects does Sourcerer have ready for use

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:

  • $mainframe or $app
  • $document or $doc (Cannot be used in Sourcerer code in modules)
  • $database or $db
  • $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)

Quotes are escaped (\") in the editor

This is caused by an incorrect server setting. The Magic Quotes GPC php settings should be switched off. If you don't know how to change that setting, ask your host.

I get a 'Parse' error / 'runtime-created function' error

This means something is wrong with the php code you have placed through Sourcerer.
Double check your own code for problems.

I want to prevent others from using the {source} tag

The easiest way to prevent this is to change the tag syntax name to something other than 'source'. You can change this in the Sourcerer system plugin settings.

For instance, if you change this to 'mycode', then the {source} tags no longer work and you have to use {mycode}...{/mycode}

In the Pro version you have extensive security settings to (dis)allow certain things for different user groups. So you can fine-tune the ability to use the Sourcerer tags and types of code.

Free vs Pro:

Place HTML
Place CSS
Place Javascript
Place PHP
Easy to use Sourcerer Code Editor (via Editor Button)
Basic security settings::Ability to set whether Sourcerer should be able to place CSS, JavaScript and PHP code

Use custom example code::Ability to change the default example code the Sourcerer Code Editor uses
Advanced security settings::Ability to set security levels on article, component and other area levels

Sourcerer enables you to place PHP and any kind of HTML style code (including CSS and JavaScript) right into your content! Not only in your articles, but also in sections, categories, modules, components, META tags, etc.

You can now just place your original codes right into your WYSIWYG editor. The only thing you have to do is surround the code with the Sourcerer tags. Easy peasy!

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

Most Joomla! Text Editors will strip parts of your HTML code, like JavaScripts (think of statistics scripts) and movie embed tags. With Sourcerer you won't have these limitations.