Sourcerer

Place any code in Joomla!

  • Last updated: 02-Oct-2018
  • Version: 7.3.1
  • Types: System plugin Editor button plugin
  • Joomla rating: 100%

Frequently Asked Questions about Sourcerer

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.

Installation

How can I install/upgrade Sourcerer?

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.

Sourcerer won't install...

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

How can I uninstall Sourcerer?

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

If you no longer use any Regular Labs extensions, you can also uninstall the Regular Labs Library plugin by using the Joomla! core extension manager.

What are the minimum requirements?

Sourcerer will only work correctly if your setup meets these requirements:

  • Up-to-date version of Joomla:
    • Joomla 3.8.0 or higher
  • PHP 5.6 or higher
  • MySQL 5 or higher

Important: I can only provide support for setups that:

  • meet the above requirements;
  • do not have extension files or Joomla! core files which have been altered in any way.

Where can I download earlier versions?

You have access to all previous free versions of all extensions on this website.

If you have a subscription to an extension, you can also download any previous pro version of that extension.

If you do not have a valid subscription, you can download any pro version that is older than 1 year.

You can find old versions in the changelog.

Note: Please note that I am unable to provide support on old versions! (whether you have a subscription or not).

How can I downgrade to an earlier version of Sourcerer?

If for some reason you need to install an older version, it is best to uninstall the extension first.

You will also have to uninstall the Regular Labs Library system plugin.

After that you can simply install the older version zip file using the Joomla! installer.

Note: Please note that I am unable to provide support on old versions!

How can I upgrade from Joomla 2.5 to Joomla 3?

The upgrade of Joomla itself is a one-click process. But that just takes care of Joomla.

Many templates and extensions will not work the same or at all after upgrading to Joomla 3.

I personally advise against using the built-in upgrade process, and advise starting from scratch by installing a fresh copy of Joomla 3.

If you do want to upgrade Joomla 2.5 to Joomla 3, you will need to do this with regards to the Regular Labs extensions you have installed:

  1. Disable or uninstall all Regular Labs extensions.
    (Uninstalling Regular Labs extensions will make you lose any global configuration settings for that extension. You will not lose any saved items)
  2. Upgrade Joomla 2.5 to Joomla 3.
  3. Re-install all Regular Labs extensions you want installed.

For a detailed step-by-step migration process, see: https://docs.joomla.org/Joomla_2.5_to_3.x_Step_by_Step_Migration

Licensing

Under what license are Regular Labs extensions released?

All free and paid Regular Labs extensions are released under the Open Source GNU GPL v2.0 license.

See the Terms & Conditions for additional terms.

Regular Labs Library

What is the Regular Labs Library?

The Regular Labs Library is a Joomla! library and system plugin that is installed along with every Regular Labs extension.

This plugin contains all the common functions and language strings that the Regular Labs extensions use.

If you use any Regular Labs extensions, this plugin must be installed and published. They will not function correctly or they will not function at all without it.

Do I still need the NoNumber Framework plugin?

The NoNumber Framework has been replaced with the Regular Labs Library.

It is however not possible for my installer to check if a user has any custom code (in custom extensions, overrides or templates) that is using and relying on functionality from the NoNumber Framework.
This is the reason the NoNumber Framework does not get uninstalled automatically.

The NoNumber Framework can safely be uninstalled if your do not have any custom code using it.

More Questions

I cannot find an answer to my question

Is there no answer to your question in this list, please try out these options:

  • General FAQs
    For general questions see the Pre-Sale Questions & Answers.
  • Tooltips
    All settings/options for the installed extensions have tooltips that explain what that setting is for. That should give you enough information to know how to use it.
  • Google
    Google is your friend! If you have some problem, get an error, have a question, try out Google. It usually gives you enough feedback to find an answer.
  • Support Forum
    For more specific questions or feedback, please use the Support Forum.
    For extension support you will need a valid subscription.
    For Bug Reports and Pre-Sale questions you do not need a subscription.