HowTo - Extend Joomla! Settings (JForm) easily with JYAML 4x

From Joomla! 1.6+ with JForm you can extend option/parameter settings with your own fields with the plugin trigger onContentPrepareForm. In JYAML 4.x you can add fields easily if you create appropriate xml files.

Add field options in your JYAML template

You can find in the Joomla! template folder of JYAML a file 'custom.xml.example' as an example.
Make a copy of the 'custom.xml.example' an rename it to 'custom.xml'.
After rename you can see the additional example fields in the template settings.

The xml syntax is the same of JForm. JForm fields are fully supported:
Overwriting of existing fieldset's or fields is also possible.

When you need fields with multiple languages you can use the custom language file included in the template /language/ folder. See: xx-XX.tpl_[template].custom.ini.example
You can get the additional parameters as the same way as of all existing values. For example in the template files or template override files with:

// within template files (/html/*)
$fieldValue = $this->params->get(fieldname [, optional default value]);
// or outside of the template fiels you need to get the reference object of JYAML with:
$jyaml = JYAML::getDocument();
$fieldValue = $jyaml->params->get(fieldname [, optional default value]);

Add additional field options for Extensions

Adding fields for extensions is not possible from the template folder. You need to look in the JYAML Library folder "/libraries/jyaml/config/custom". In the folder you can find examples.

You also can do this with a special JYAML Plugin. An example code of such plugin can you find here: (look at the config folder)

The principle is the same here as adding fields in the template settings, but you must give the correct name of the file. To find out what filename is affected you can enable "Show Admin Log" in the "JYAML Framework System Plugin" in the Joomla! Extension Manager.

Example: Create a simple gallery with image selection in article detail options.

Add a multiple image selection field in article detail options

Add the option.
Create the file "com_content.article.xml" in "/libraries/jyaml/config/custom/" with following content:

<?xml version="1.0" encoding="utf-8"?>
 <fields name="attribs" addfieldpath="/libraries/jyaml/config/custom/fields">
   <fieldset name="gallery_images" label="JYAML_GALLERY_IMAGES">
     <field name="gallery_images" type="galleryimages" label="JYAML_GALLERY_IMAGE" default="" />

Create a multiple image selection field type.
Create a file "galleryimages.php" in "/libraries/jyaml/config/custom/fields" with following content:

 * JYAML - Template Framework includes YAML for Joomla!
 * @author Reinhard Hiebl
 * @copyright Copyright (C) 2006-2011, Reinhard Hiebl, HieblMedia
 * @license Creative Commons Attribution 3.0 Unported License
 * >
defined('_JEXEC') or die;
 * JYAML Scripts Form Field
class JFormFieldGalleryimages extends JFormFieldMedia
 * The form field type.
 protected $type = 'JFormFieldGalleryimages';
 protected function getLabel() {
 return '';
 * Get the field input markup.
 protected function getInput()
 static $loaded;
 if(!$loaded) {
 JHTML::_('behavior.framework', true);
 $document = JFactory::getDocument();
 #gallery-images .gallery-image { border:1px solid #ccc; padding:5px; background:#f6f6f6; margin-bottom:3px; }
 #gallery-images .gallery-image-content { overflow:hidden; width:100%; position:relative; }
 #gallery-images label { cursor: move; }
 #gallery-images .remove-gallery-image { float:right; }
 // JFormFieldGalleryimages
 window.addEvent('domready',function() {
 var galleryInitSortable = (function() {
 new Sortables('gallery-images', {
 constrain: true,
 clone: true,
 revert: true,
 handle: 'label',
 onStart: function(element, clone){
 element.setStyle('opacity', '0.25');
 clone.setStyles({'opacity': '0.75', 'background': 'yellow', 'z-index': '10'});
 }); galleryInitSortable();
 var galleryInitButtons = (function() {
 $$('.remove-gallery-image').addEvent('click', function(event){
 var ok = confirm('".JText::_('JYAML_GALLERYIMAGE_CONFIRM_REMOVE')."');
 if(ok) {
 }); galleryInitButtons();
 $('add-gallery-image').addEvent('click', function(event) {
 var container = $('gallery-image-dummy');
 var clone = container.clone(true, true);
 clone.inject(container, 'before');
 clone.set('id', null);
 $$('#gallery-images .gallery-image').each(function(imagegroup, count){
 el.set('id', el.get('id')+count);
 el.set('for', el.get('for')+count);
 var href = el.get('href');
 var onclick = el.get('onclick');
 if(href) {
 href = href.replace(/jform_attribs_gallery_images/, 'jform_attribs_gallery_images'+count);
 el.set('href', href);
 if(onclick) {
 onclick = onclick.replace(/jform_attribs_gallery_images/, 'jform_attribs_gallery_images'+count);
 el.set('onclick', onclick);
 clone.setStyle('display', 'block');
 SqueezeBox.assign($$('a.modal'), {parse: 'rel'});
 return false;
 $loaded = true;
 $this->name = $this->name . '[]';
 $origID = $this->id;
 $html = '';
 $html .= '<div class="gallery-images" id="gallery-images">';
 if($this->value && is_array($this->value)) {
 foreach($this->value as $count=>$_value) {
 if(empty($_value)) { continue; }
 $html .= '<div class="gallery-image">';
 $html .= '<div class="gallery-image-content">';
 $html .= '<a href="#" onclick="return false;" class="remove-gallery-image"><span>'.JText::_('JYAML_GALLERYIMAGE_REMOVE_BTN').'</span></a>';
 $this->id = $this->id.$count;
 $this->value = $_value;
 $html .= parent::getLabel();
 $html .= parent::getInput();
 $html .= '</div>';
 $html .= '</div>';
 $html .= '<div id="gallery-image-dummy" style="display:none;">';
 $html .= '<div class="gallery-image-content">';
 $html .= '<a href="#" onclick="return false;" class="remove-gallery-image"><span>'.JText::_('JYAML_GALLERYIMAGE_REMOVE_BTN').'</span></a>';;
 $this->value = '';
 $this->id = $origID;
 $html .= parent::getLabel();
 $html .= parent::getInput();
 $html .= '</div>';
 $html .= '</div>';
 $html .= '</div>';
 $html .= '<a href="#" id="add-gallery-image"><span>'.JText::_('JYAML_GALLERYIMAGE_ADD_BTN').'</span></a>';
 return $html;

Add language strings.
Create a file "en-GB.custom.ini" in "libraries\jyaml\language\en-GB\". with following content:
Repeat this for each language you want (de-DE, etc.).

; JYAML - Template Framework includes YAML for Joomla!
; -----------------------------------------------------------------------------
; @version $Id: en-GB.lib_jyaml.ini 884 2011-02-05 19:11:52Z hieblmedia $
; @author Reinhard Hiebl
; @copyright Copyright (C) 2006-2011, Reinhard Hiebl, HieblMedia
; @license Creative Commons Attribution 3.0 Unported License
; >
; @link
; @package JYAML
; @suppackage JYAML.Language
; -----------------------------------------------------------------------------
; Note : All ini files need to be saved as UTF-8 - No BOM
[Gallery Images - Custom field]
JYAML_GALLERYIMAGE_CONFIRM_REMOVE="Really remove it? The image itself will be not deleted."

Create a new com_content article detail template output override to display the selected images

We only create a output override as example.

You can also create a new view (e.g. article_gallery or something).
Joomla! HowTo:

1. Copy the "default.php" from "\components\com_content\views\article\tmpl\" into "\templates\jyaml\html\com_content\article\"

2. Add the following part of code to get and display the images in the copied default.php (insert the code where you want to display the images):

 // get images
 $galleryImages = (array)$this->item->params->get('gallery_images', array());
 // validate images (remove empty entries)
 if(!empty($galleryImages)) {
 foreach($galleryImages as $k=>$v) {
 if(empty($v)) {
<?php if(!empty($galleryImages)) : ?>
 <?php JHtml::_('behavior.modal'); // squeezbox modal box ?>
 <div class="gallery-images clearfix">
 <div class="gallery-image-thumbs clearfix">
 <?php foreach($galleryImages as $_image) : ?>
 <div class="gallery-image-thumb float_left">
 <a href="/<?php echo $_image; ?>" class="modal">
 $img = JYAML::getImage($_image, '', array('resizeUp'=>true), '');
 $img->adaptiveResize(150, 150);
 echo $img->toString();
 <?php endforeach; ?>
<?php endif; ?>

Example Download

You can download the files of the above image gallery example here: