JIncludes ReadMe file

JIncludes is a Joomla! plugin allowing administrators to define code snippets and include/execute them inside a content item.

This ReadMe should address the most common issues. In case you didn't find the answer you need here, please post it in the JIncludes support forum and I will help you as soon as possible.

This file contains:

Known issues

Functionalities and syntax

JIncludes does not recognize anything right out-of-the-box. You first need to define code snippets, by entering their keys and their types in the backend plugin settings page. Every snippet is defined independently of the others, and currently up to 30 of them can be defined. Remember that the plugin, right after installation, is disabled: you need to enable it from the plugin manager to make it work.

Every snippet has a keyName you define, and you will be able to launch the associated snippet action by entering {{ keyName }} at the desired point of your articles. Snippet types which do not output text can be put anywhere in your articles and they will not be visible to frontend viewers.

Keys can only contain ASCII alphanumeric characters, underscores ("_") and an optional leading slash ("/"), to mimic HTML closing tags. Technically, the Perl RegExp you need to match is #^/?[a-z\d_]+$#i.

Parameters

Some snippet types (i.e. all HTML and PHP snippets) support parameters. This allows you to make snippet definitions which aren't static and repeated, but can be adapted and customized every time they are called.

Parameters are declared with this syntax: {{ keyName parameters }}.

The parameters string is actually passed on as a single string, with no whitespace at its beginning and end. In PHP snippets, It can be easily adapted to contain more than one parameter, since it may contain any sequence and length of characters (except for the closing braces }}). Therefore, you can choose a parameter separator (typically the space character) it and split it up to an array of parameters. Simply calling split($params,' ') will do the job.

Remember: whitespace at the beginning and at the end of the parameters string will not be read.

The block syntax

PHP snippet types which are named with "+ block" will be matched with a special pattern. They are meant to enclose a chunk of the article, like HTML tags do, and give the custom PHP code a more powerful environment to work with that chunk.

When you define a snippet of type PHP + block with a key named key1, the plugin will search for a something like:

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. {{key1 params}}Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.{{/key1}} Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

and will pass the match to your code in a very powerful way.

Whitespace and case insensitivity

The snippet keys are case insensitive, which means that you may call them with any capitalization, but also that you can't define two keys which differ only by their capitalization.

It also has a very flexible behavior towards whitespace. Look at a JIncludes tag {{*key*params*}}. Where you see *, you can put any kind and amount of whitespace you want, i.e. any combination and number of spaces, tabs, newlines.

  • Of course, you can also omit whitespace next to the curly braces: {{key params}} is a valid tag.
  • At least one whitespace character is required as a separator between they key and the parameters string.
  • The parameters string is always matched and returned without any leading or trailing whitespace, so don't rely on them. Within the string, instead, you may put any kind and number of whitespace characters, they will be matched and reported faithfully in the params string.
    Be careful: this may be very good or very bad for you, but don't ignore the problem. My advice is that you don't rely on whitespace: the tags are inside HTML code, and for an HTML parser every kind and amount of whitespace is equivalent to a single space character. So, for instance, WYSIWYG editors may convert complicated whitespace sequences into one single space character.

Snippet types

HTML (input code)

For snippets of this type, the plugin will take the snippet code and output it literally, except for parameter insertion, at the tag's position.

The parameter string is inserted into the HTML code, wherever the $ (dollar symbol) character appears (not only once). To output an actual dollar sign, write \$. You don't need to escape any other symbol.

Example: Your article is

Nobody knows what happened {{red yesterday morning}} in Denver.

And you define a snippet with key = red, type = HTML (input code), code = <span style="color: red;">$</span> .
Your article will be rendered as

Nobody knows what happened <span style="color: red;">yesterday morning</span> in Denver.

PHP (input code),
External PHP (input filename)

Warning: if you input PHP code containing pipes (|) into the plugin's configuration, it will get broken by Joomla!. This is a known bug and will be fixed very soon. In the meantime, if your code contains pipes, the PHP (input code) mode will be unreliable, so please avoid using it: use an external file instead.

In this case, you can either enter PHP code directly into the snippet's code or specify a server path for a PHP file to include. Remember: a server local filesystem path, not an URL! In both cases, your code will be executed wherever the snippet's tag is found.

Some rules apply:

  1. To output text (which will replace the snippet's tag into the article) you simply need to echo() it.
  2. The parameters string will be available to your code as the $param local variable.
  3. Your code will be executed in an output buffer context. You should not ob_start() or ob_end_*(). That is, don't mess with the output buffer.
  4. The snippet's whole tag (parameters included) will be available as $env[0]. You will likely never need it. In this context, the $env array will have no other items.

If you use an external file, remember that the server path must exist and you must have permission to include() files located there.

PHP + block (input code),
External PHP + block (input filename)

These snippet types apply the block matching described above. The execution context is the same as in the plain PHP snippet types, so the first three rules still apply:

  1. To output text (which will replace the snippet's tag into the article) you simply need to echo() it.
  2. The parameters string will be available to your code as the $param local variable.
  3. Your code will be executed in an output buffer context. You should not ob_start() or ob_end_*(). Again, don't mess with the output buffer.

Now for the differences. First, the $env array will be populated in a more complex way:

$env[0]
The whole article code, possibly including snippet tags. You will likely never need it, except as a fallback.
$env[1]
All the article code before the opening tag of the current snippet.
$env[2]
All the article code enclosed between the opening and closing tag of the current snippet.
$env[3]
All the article code after the closing tag of the current snippet.

Second, and very important: the snippet matches the whole article, so your article must output the whole (modified) article code in this case.

Again, if you choose to include an external file, make sure that the path exists and that you have permission to include() that file from that path.

Link CSS stylesheet (input URL)

Snippets of this type are made to attach an external CSS stylesheet to a single article or just a few articles, instead of putting all the site's styles into your template's CSS. This also allows you to define different styles for plain HTML elements in different articles, without the need to use article-specific classes.

Usage is fairly simple: just enter a snippet key, select this snippet type and input a stylesheet's URL into the code box. Then add {{ keyName }} anywhere in every article you want to link the stylesheet file. This snippet type does not support (and ignores) parameters and the tag's text will not be output.

The URL is passed on exactly as you input it, so remember to make it relative to the site's root (starting with "/") if you use SEF, where your pages will appear at different depths in the site's tree to the client browser.

Stylesheets are linked with no media attribute, and type = text/css.

Link JavaScript file (input URL)

This snippet type behaves exactly like the one above, except it produces an external script tag instead of an external stylesheet link. Your script will be included in the document's <head>, so tags of this type can be put indifferently anywhere in the article's text, just like CSS ones.

Again, create the snippet and enter the script file's URL as its code. The URL will be output literally as written, this snippet type does not support (and ignores) parameters, and disappears on article rendering. Take care of making your URL relative to the site's root if you use SEF (see CSS snippets above).

Updating

The usual way to update a plugin in Joomla! is uninstalling it and installing the new version. However, this deletes the plugin's settings, and while for some plugins this might be acceptable, JIncludes's settings contain all of your snippets, which you would need to save separately and re-enter manually from scratch. This is why you will find an update package in the plugin's file release system to manually update your JIncludes copy without losing your snippets.

All you have to do is unzip the update package in your Joomla! root directory and overwrite the files. If you don't have shell access to your server, you will need to upload and overwrite the files one by one, which is not so bad because they are 3 (at most). If you need it, please feel free to ask for help in the JIncludes support forum.

 

Last updated: 2008-04-10