Freestyle Includes: Fragments - User Guide

This user guide gives an in depth description of Freestyle Includes: Fragments and how to use it including:

• What the product does
• How to install and uninstall
• How to setup and use

Freestyle Includes: Fragments is part of our growing Freestyle Includes range of products.

It allows you to pre-define chunks of HTML and content to be included anywhere on your site by using a simple tag such as:

{frag my-fragment}

If you edit an article you will see the tag displayed, but when viewed on the frontent of your site the tag will be replaced with the content of your fragment!

On your web sites Joomla! administration section (usually http://www.yoursite.com/administrator/), goto the menu "Components" -> "Freestyle Joomla" -> "Includes: Fragments Pro". This is the main control panel for Freestyle Includes: Fragments.

Click the "Fragments" button to display a list of your current fragments on the site.

To create a new fragment, click the "New" button. You will be presented with with a form where you can enter your fragment.

Title

This is a descriptive title that will only be displayed on the admin part of your site.

Alias

This is the identifier that is used to reference the fragment when including it in your content. If you do not specify an alias, one will automatically be created from your title.

Shortcut

You can enter a name here as a shortcut tag for outputting the fragment.

Make sure that you have entered a title for your new fragment. In the "Template" tab, you will be presented with a WYSIWYG editor that is used to define the fragment that will be output. Enter the HTML you wish to display here and then "Save" the fragment.

Once you have created your fragment, return to the fragments list on your Joomla admin section. You should see your new fragment listed.

Against the fragment under the "Tag" column will be listed the tag that is needed to output your new fragment on your site.

{frag my-fragment}

If you include the code in either an article or module on your site, it will be replaced with the template that you defined for the fragment.

If you specified a "Shortcut" for your fragment, then this can also be used to output the fragment. E.g. if the shortcut you specified was "myfrag1" then using the tag

{myfrag1}

will also output your fragment. The shortcut will be also displayed in the "Tag" column.

You can dynamically change the content of a fragment by passing parameters to it within the tag. The parameter will be replaced in the template you created with what has been passed in the tag.

An example of this would be the following fragment:

©{year} - {company} - All rights reserved

Example uses and outputs:

{frag copyright year="2013" company="My Company"}

{frag copyright year="2001" company="Bills Software Company"}

Freestyle Includes: Fragments Pro allows the template to be passed through the Smarty template system. This allows for much greater flexibility of the content your are displaying. The syntax of the Smarty template system is simple but also very powerfull, and there are too many possibilites to be documented here. View the Smarty documentation for a full rundown on its features.

Any parameters that are passed in the tag will be set as variables within the template. The parameters can be displayed by {parameter} or used in code as $parameter.

An example fragment using smarty (alias of 'showname'):

{name} - {if $new}NEW!{else}Not new{/if}

With the following preset parameters:

name="Dont forget to enter a name"
new=0

Example uses and outputs:

Another Pro only option is the use of the Code Mirror editor. This replaces the Joomla! WYSIWYG editor with a simple HTML code editor. This will allow you to fully customize the HTML output based with Smarty. An example of this would be (alias of 'proex2'):

<div style='border: 2px solid {color}; {if $bold}font-weight: bold;{/if}'>{title}</div>

Example uses and outputs:

The settings for Freestyle Includes: Fragments can be found in the "Settings" icon on the main component page ("Components" -> "Freestyle Joomla" -> "Includes: Fragments")

Template Editor *

Change which editor is used for editing your template. You can specify to use the built in Joomla! editor, or to use the more advanced Code Mirror editor.

Enable Smarty *

Enable this to run the output through the Smarty template system instead of the simple output mode

Hide Errors

This will hide any error messages that are displayed when outputting your fragments. For testing and development this is reccomended to be enabled, and for live and production sites disabled.

Each of these settings cab also be changed for each fragment individually by editing the fragment cand changing the value in the "Fragments Settings" pane.

* Setting only available in Pro version.

Freestyle Includes: Fragments has the following technical requirements:

• Joomla 2.5, 3.3 or 3.4
• PHP 5.3 or later
• MySQL 5.x

All Freestyle Includes components work through a single Joomla! content plugin. For Freestyle Includes: Fragments to function, you must ensure that the "Content - Freestyle Includes" plugin is enabled. To check this, on your Joomla! admin pages, goto "Extensions" -> "Plug-in Manager". Search for "Content - Freestyle Includes" and make sure that the status is checked. If it is not, then clicking the red circle will enable the plugin.

Please ensure that you have the most current version of your copy of Joomla installed. Our components and extensions are developed and tested only with the most recent versions of Joomla.

To install Freestyle Includes: Fragments on your Joomla! site you will need to do the following steps:

1. Download the component from our websites downloads section.
2. Go to your Joomla! web sites Administration page ( http://www.yoursite.com/administrator/ )
3. Log into your Admin account
4. From the menu at the top of the page select "Extensions" -> "Extension Manager"
5. Under "Upload Package File" click the "Choose File" button.
6. Select the zip file you downloaded from our site and click the "Upload & Install" button
7. Your component is now installed and can be found under "Components" -> "Freestyle Joomla" -> "Freestyle Includes: Fragments"

To update an existing installation of Freestyle Includes: Fragments you do not need to uninstall the component first. You just need to follow the instructions for installing.

If you have any issues with this process please open a support ticket or post a message in our forums.

To uninstall Freestyle Includes: Fragments you need to log into your Joomla admin backend as described in the installation process.

Goto "Extensions" -> "Extension Manager", then to the "Manage" section.

In the "Filter" enter "Freestyle" and click "Search". This will display a list of all the Freestyle Joomla components that you have installed. Check the box on the left of the list and click the "Uninstall" button on the top right of the page to uninstall a component.

The following components are required by all Freestyle Joomla components and should not be uninstalled unless you are removing all Freestyle products.

• Freestyle Joomla Core
• Freestyle Joomla Overview
• Freestyle Joomla System Plugin

Also, if you have any Freestyle Includes products installed, the following compononets and plugins are required and should not be removed unless you are removing all includes products.

• Freestyle Includes
• Content - Freestyle Includes

You can remove and "Freestyle Joomla Installer" installer items at any time as these are not required by the products, and are just used for installation.