User Guide

Sourcerer

Download Free Buy Pro   € 40

1) Introduction

This guide provides in-depth information about Sourcerer and will tell you:

  • what it does
  • how to install it
  • how to set-up and use it

2) What is Sourcerer?

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.

3) 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.

3.1) 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).

3.2) 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}

3.3) 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 theis 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.

4) 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.

5) 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.

6) 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:

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}

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.

Same settings as the 'Security Settings - Default', plus below settings

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

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

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

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.

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.

Same settings as the 'Security Settings - Default', plus below settings

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.

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

Same settings as the 'Security Settings - Default', plus below settings

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

Editor Button Options

Button Text This text will be shown in the Editor Button.
Show Button Icon J2.5 ONLY If selected, the icon will be displayed 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).

Example Code PRO ONLY

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.

7) Requirements

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

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.

8) Installation

You can either install Sourcerer by using the core extension manager available in the Joomla! Administrator Control Panel, or by using the powerful NoNumber 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.

8.1) NoNumber Extension Manager

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

Please see the User Guide for the NoNumber Extension Manager for more detailed information...

NoNumber Extension Manager

8.2) Joomla! Extension Manager

To install via the Joomla! Extension Manager, just follow these steps (based on Joomla 2.5 setup):

  1. Download the extension zip.
  2. Log into your Joomla administrator
  3. In the menu, choose: Extensions >> Extension Manager
  4. Under 'Upload Package File' select the extension zip.
  5. Click on 'Upload & Install'
Joomla! Installer

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

9) Uninstallation

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

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