User Guide

Index

1. Introduction
2. What is Sourcerer?
3. Syntax
   1. Using the double bracket syntax
   2. Using HTML entities
   3. Not using a WYSIWYG editor?
4. Examples
5. Editor Button
6. Settings
7. Requirements
8. Installation
   1. NoNumber Extension Manager
   2. Joomla! Extension Manager
9. Uninstallation

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

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

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

7) Requirements

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

• Up-to-date version of Joomla! 1.5 or 2.5 or 3.x
• PHP 5.3+ No PHP 5.2 support
• PHP mbstring (Multibyte String) functions enabled
• MySQL 5+

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

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'

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 PRO version of 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.