HowTo's

HowTo - Using Form Validator with the YAML form markup

Since JYAML 4.0 a helper script is included to use the Form Validator with the YAML form markup.

1. Add the following PHP-Code in your template file or in each layout override you need it.

<?php JHtml::_('jyaml.validator'); ?>

2. Then add the CSS-Class jyaml-form-validate to your form like:

<form class="ym-form jyaml-form-validate" action="<?php echo JRoute::_('index.php?option=com_users&task=user.login'); ?>" method="post">
 <fieldset>
 <?php foreach ($this->form->getFieldset('credentials') as $field): ?>
 <?php if (!$field->hidden) : ?>
 <div class="ym-fbox-text">
 <?php echo $field->label; ?>
 <?php echo $field->input; ?>
 </div>
 <?php endif; ?>
 <?php endforeach; ?>
 </fieldset>
 
 <div class="ym-fbox-button">
 <button type="submit" class="ym-button ym-save"><?php echo JText::_('JLOGIN'); ?></button>
 </div>
 
 <?php echo JHtml::_('form.token'); ?>
 <?php $_value = base64_encode($this->params->get('login_redirect_url', $this->form->getValue('return'))); ?>
 <input type="hidden" name="return" value="<?php echo $_value; ?>" />
</form>

HowTo - Using Syncheight (Equal Columns) in JYAML with YAML

Without JavaScript

This method has some restrictions.
Just take a look at the YAML Grids Documentation in the section Equal Heights Grids.

With Javascript

Add the following PHP-Code in your template file or in each layout override you need it.

Syntax:
JHtml::_('jyaml.syncheight', '[column selector]', '[optional row/grid selector]', [update on resize, true or false])

Simple Example:

<?php JHtml::_('jyaml.syncheight', '.columnselector'); ?>

If you want to sync only as special grid you can use:

<?php JHtml::_('jyaml.syncheight', '.columnselector', '.mygrid'); ?>

If you want to re-sync on window resize:

<?php JHtml::_('jyaml.syncheight', '.columnselector', '', true); ?>

Alternatives

I recommend to use the jQuery matchHeight Plugin for more advanced equal height solutions.

HowTo - Usage of Accessible Tabs without modChrome

You can use the Accessible Tabs from the JYAML 4.x+ Framework everywhere you want, within Joomla!.

Script Path: /libraries/jyaml/html/js/accessible_tabs.js

HTML Markup Example

<div class="jyaml-tabs myTabs clearfix">
 <h3><span>Tab 1</span></h3>
 <div class="tabbody">
 <div class="tabbody-content">
 Tab 1: Contents
 </div>
 </div>
 
 <h3><span>Tab 2</span></h3>
 <div class="tabbody">
 <div class="tabbody-content">
 Tab 2: Contents
 </div>
 </div>
 
 <h3><span>Tab 3</span></h3>
 <div class="tabbody">
 <div class="tabbody-content">
 Tab 3: Contents
 </div>
 </div>
</div>

Required Javascript and options

<?php
 // JYAML Instance
 $jyaml = JYAML::getDocument();
 
 // JYAML Tabs Options (see: [JOOMLA_ROOT]/libraries/jyaml/html/js/accessible_tabs.js)
 $options = array();
 $options[] = "tabhead: 'h3'";
 $options[] = "syncheights: true";
 $options[] = "autoAnchor: true";
 $options[] = "currentInfoText: ' ".JText::_('JYAML_TABS_CURRENT_TEXT')." '";
 $options[] = "currentInfoPosition: '".($jyaml->direction=='rtl' ? 'after' : 'before')."'";
 $options[] = "orientation: 'horizontal'";
 $options[] = "effects: null"; // ['slide'], ['fade'], ['slide', 'fade'] or null
 $options[] = "slideDirection: 'horizontal'";
 $options[] = "position: 'top'";
 $options[] = "pagination: true";
 $options[] = "saveState: false";
 
 // Add Javascript
 JHtml::_('jyaml.tabs', '.myTabs', $options);
 // Add Stylesheet
 $jyaml->addStylesheet($jyaml->getUrl('css', 'screen.tabs.css'));

For all options look in the Javascript source-code: /libraries/jyaml/html/js/accessible_tabs.js
The Code JHtml::_('jyaml.tabs', '.myTabs', $options); calls the function in /libraries/jyaml/html/jyaml.php

Basic Stylesheet

See: templates/jyaml/css/screen.tabs.css

HowTo - Usage of Accessible Accordion without modChrome

You can use the Accessible Accordion from the JYAML 4.x+ Framework everywhere you want, within Joomla!.

Script Path: /libraries/jyaml/html/js/accessible_accordion.js

HTML Markup Example

<div class="jyaml-accordion myAccordion">
 <div class="accordion_content clearfix">
 <div class="accordion-container clearfix">
 
 <h3 class="accordionhead"><span>Section 1</span></h3>
 <div class="accordionbody">
 <div class="accordionbody-content clearfix">
 Section 1: Contents
 </div>
 </div>
 
 <h3 class="accordionhead"><span>Section 2</span></h3>
 <div class="accordionbody">
 <div class="accordionbody-content clearfix">
 Section 2: Contents
 </div>
 </div>
 
 <h3 class="accordionhead"><span>Section 3</span></h3>
 <div class="accordionbody">
 <div class="accordionbody-content clearfix">
 Section 3: Contents
 </div>
 </div>
 
 </div>
 </div>
</div>

Required Javascript and options

<?php
 // JYAML Instance
 $jyaml = JYAML::getDocument();
 
 // JYAML Accordion Options (see: [JOOMLA_ROOT]/libraries/jyaml/html/js/accessible_accordion.js)
 $options = array();
 $options[] = "syncheights: false";
 $options[] = "saveState: false";
 $options[] = "autoAnchor: false";
 $options[] = "currentInfoText: ' ".JText::_('JYAML_TABS_CURRENT_TEXT')." '";
 $options[] = "currentInfoPosition: '".($jyaml->direction=='rtl' ? 'after' : 'before')."'";
 
 // MooTools Accordion Options (see: http://mootools.net/docs/more/Fx/Fx.Accordion)
 $acOptions = array();
 $acOptions[] = "duration: 500";
 $acOptions[] = "display: 0";
 $acOptions[] = "height: true";
 $acOptions[] = "width: false";
 $acOptions[] = "opacity: false";
 $acOptions[] = "alwaysHide: true";
 $acOptions[] = "trigger: 'click'";
 $options[] = "accordion: {".implode(', ', $acOptions)."}"; // Apply options
 
 // Add Javascript
 JHtml::_('jyaml.accordion', '.myAccordion', $options);
 // Add Stylesheet
 $jyaml->addStylesheet($jyaml->getUrl('css', 'screen.accordion.css'));

For all options look in the Javascript source-code (/libraries/jyaml/html/js/accessible_accordion.js)
The Code JHtml::_('jyaml.accordion', '.myAccordion', $options); calls the function in /libraries/jyaml/html/jyaml.php

Basic Stylesheet

See: /templates/jyaml/css/screen.accordion.css

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: http://docs.joomla.org/Standard_form_field_and_parameter_types
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: http://bitbucket.hieblmedia.com/jyaml/src/?at=plugins (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"?>
<config>
 <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="" />
   </fieldset>
 </fields>
</config>

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

<?php
/**
 * 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
 * > http://www.jyaml.de/en/license-conditions.html
 */
 
defined('_JEXEC') or die;
 
jimport('joomla.form.formfield');
JFormHelper::loadFieldClass('media');
 
/**
 * 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();
 $document->addStyleDeclaration(" 
 #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; }
 ");
 $document->addScriptDeclaration(" 
 // 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){
 event.stop();
 
 var ok = confirm('".JText::_('JYAML_GALLERYIMAGE_CONFIRM_REMOVE')."');
 if(ok) {
 this.getParent().getParent().destroy();
 galleryInitSortable();
 }
 });
 }); galleryInitButtons();
 
 $('add-gallery-image').addEvent('click', function(event) {
 event.stop();
 
 var container = $('gallery-image-dummy');
 if(container){
 var clone = container.clone(true, true);
 clone.inject(container, 'before');
 
 //initPositions();
 clone.set('id', null);
 clone.addClass('gallery-image');
 
 $$('#gallery-images .gallery-image').each(function(imagegroup, count){
 imagegroup.getElements('input').each(function(el){
 el.set('id', el.get('id')+count);
 el.focus();
 });
 imagegroup.getElements('label').each(function(el){
 el.set('for', el.get('for')+count);
 });
 imagegroup.getElements('a').each(function(el){
 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'});
 galleryInitSortable();
 galleryInitButtons();
 
 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
; > http://www.jyaml.de/en/license-conditions.html
; @link http://www.jyaml.de
; @package JYAML
; @suppackage JYAML.Language
;
; -----------------------------------------------------------------------------
; Note : All ini files need to be saved as UTF-8 - No BOM
 
[Gallery Images - Custom field]
JYAML_GALLERY_IMAGES="Gallery Images"
JYAML_GALLERY_IMAGE="Image"
JYAML_GALLERYIMAGE_CONFIRM_REMOVE="Really remove it? The image itself will be not deleted."
JYAML_GALLERYIMAGE_REMOVE_BTN="Remove"
JYAML_GALLERYIMAGE_ADD_BTN="Add Image"

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: http://docs.joomla.org/Layout_Overrides_in_Joomla_1.6

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

...
<?php
 // 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)) {
 unset($galleryImages[$k]);
 }
 }
 }
?>
<?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">
 <?php
 $img = JYAML::getImage($_image, '', array('resizeUp'=>true), '');
 $img->adaptiveResize(150, 150);
 echo $img->toString();
 ?>
 </a>
 </div>
 <?php endforeach; ?>
 </div>
 </div>
<?php endif; ?>
...

Example Download

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

HowTo - Create and override module chrome/style in JYAML 4x

JYAML has a own concept where the modChorme styles are located. Joomla! uses by default the modules.php. But in JYAML the modules.php does load special modChrome files.

Each chrome style in JYAML contains a xml and a php file. In the xml file you can define options for the dynamic positions selection. And in the php file the modChrome function is included like in modules.php, but only with the specific style.
The xml file of a modChrome style has full support with JForm fields: http://docs.joomla.org/Standard_form_field_and_parameter_types

Override a JYAML included modChrome style.

At first, take a look in following JYAML libraries folder:
JOOMLA_ROOT/libraries/jyaml/html/modChrome/

The target diretory in the template is:
JOOMLA_ROOT/templates/[template]/html/modChrome/

In the libraries folder you can see all core styles.

For example you must make changes in the 'rawlinks' style:

  1. Copy the rawlinks.php and rawlinks.xml in your template folder (JOOMLA_ROOT/templates/[template]/html/modChrome/)
  2. After copy make your modifications in the copied files
  3. The JYAML Framework now automatically load the style from your template instead from the library.

That's it!
Note: You can override the xml and php file of a modChrome style separately, depending on what you want to change.

Create a new modChrome style with custom options

To add a new modChrome style in JYAML you must create a style in the following folder:
JOOMLA_ROOT/templates/[template]/html/modChrome/

The name of the function must called 'modChrome_[style]'. (So just the same as in the 'modules.php' would be)

For example we create a new modChrome style with the name 'mystyle'.

1. Create the file 'mystyle.php' in '/html/modChrome/'

<?php
/**
 * Chrome Style: mystyle example
 * Available and Used attributes:
 * - headerLevel: Headline Level (defaults: 3)
 *
 * @param object $module Module reference object
 * @param object $params Module params reference object {@link JRegistry}
 * @param array $attribs Array of additional jdoc attributes
 */
function modChrome_mystyle($module, &$params, &$attribs)
{
  // get the parameters (defined in the mystyle.xml or submitted from a jdoc attribute)
  $headerLevel = isset($attribs['headerLevel']) ? $attribs['headerLevel'] : '3';
 
  if (!empty ($module->content)) : ?>
    <div class="moduletable<?php echo htmlspecialchars($params->get('moduleclass_sfx')); ?>">
    <?php if ($module->showtitle != 0) : ?>
      <?php echo '<h'.$headerLevel.'>'; ?><?php echo $module->title; ?><?php echo '</h'.$headerLevel.'>'; ?>
    <?php endif; ?>
    <?php echo $module->content; ?>
    </div>
    <?php endif;
}

2. Create the file 'mystyle.xml' in '/html/modChrome/' to define your style attributes. Only necessary, if you will the attributes are selectable in the template settings.

<?xml version="1.0" encoding="utf-8"?>
<jyaml_modchrome>
 <name>mystyle modChrome Example</name>
 <description>This is a modChrome example for mystyle with JYAML</description>
 
 <config>
   <fields name="params" addfieldpath="/libraries/jyaml/form/fields">
    <fieldset name="jyaml-chrome">
       <field name="headerLevel" type="list" default="3" label="headerLevel" description="headerLevel">
         <option value="1">H1</option>
         <option value="2">H2</option>
         <option value="3">H3</option>
         <option value="4">H4</option>
         <option value="5">H5</option>
         <option value="6">H6</option>
       </field>
     </fieldset>
   </fields>
 </config>
</jyaml_modchrome>

After this you can select the modChrome style in the template settings on dynamic positions. For sure you can also use your style directly in jdoc statements.
For example: <jdoc:include type="modules" name="user1" style="mystyle" />

Note 1:
You can find this example in the modChrome folder of the JYAML template.

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