Yii Extensions

Home made extensions for the Yii Framework.


 back to homepage
jformValidate logo

EGuiders is a Yii extension that wraps an excellent JQuery plugin called Guiders

The Basic

Creating a Guider for your Yii webapp is easy : simply create a set of 'ext.guiders.EGuider' widgets chained together. Below is a basic example on how to create a guide. As you can see, the next button on this guide will drive the user to another Guide with id set to 'second'.

$this->widget('ext.guiders.EGuider', array(
        'id'          => 'first',
        'next'        => 'second',
        'title'       => 'Guider title',
        'buttons'     => array(array('name'=>'Next')),
        'description' => '<b>here you should put some intresting text</b>',
        'overlay'     => true,
        'xButton'     => true,
        // look here !! 'show' is true, so that means this guider will be
        // automatically displayed when the page loads
        'show'        => true,
        'autoFocus'      => true
    )
);

Upgrade from 1.0 the autoFocus option is required to garantee that the guider will scroll to the element. Previously this option was not needed as the scroll was performed by default.

The Guider plugin provides a lot of options that allows you to customize almost every aspect of the guider tour you want to offer to your users.

From javascript, you can call some API to interact with your guides.

				guiders.hideAll(); // hides all guiders
				guiders.next(); // hides the last shown guider, if shown, and advances to the next guider
				guiders.show(id); // shows the guider, given the id used at creation
			

Customize Buttons

You can define your own handler for buttons included in the Guide. This can bring some interaction with the user : you don't have to Guide a passive user ! let's make him work a little !. The following widget redefine buttons displayed by the guider.

$this->widget('ext.eguiders.EGuider', array(
        'id'           => 'second',
        'title'        => 'Simple API',
        'next'         => 'third',
        'buttons'      => array(
            array(
                'name'   => 'Previous',
                'onclick'=> "js:function(){guiders.hideAll(); $('.highlight pre').hide(); guiders.show('sample');}"
            ),
            array(
                'name'   => 'Show me more',
                'onclick'=> "js:function(){guiders.next();}"
            ),
            array(
                'name'   => 'Exit',
                'onclick'=> "js:function(){guiders.hideAll();}"
            )
        ),
        // why not call renderPartial to get the content of the Guide ? .. yeah, why not ?
        'description'   => $this->renderPartial('_guide_api',null,true),
        'overlay'       => false,
        // you can attach your guide to any element in the page thanks to JQuery selectors
        'attachTo'      => '#elementId',
        'position'      => 11,
        'xButton'       => true,
        'onShow'        => 'js:function(){ $(".highlight pre").show();}',
        'closeOnEscape' => true,
    )
);

New feature since version 1.1, thanks to the closeOnEscape option it is now possible to configure a guider to it closes when user hits the Escape key.

Guide between pages

It is possible to guide your user among one or more pages by using hash url format. To achieve this, you must add the '#guide=guide_name' parameter to the url of the target page. Replace 'guide_name' by the id of the guide that will be displayed on the target page and that's it !

Jump in The Guided tour

$nextLink = Yii::app()->createUrl('extension/eguiders2',array('#' => 'guider=page2_step2'));
$this->widget('ext.eguiders.EGuider', array(
        'id'            => 'page1_step1',
        'title'         => "Ready to leave the page ?",
        'buttons'       => array(
            array('name'=>'Let\'go', 'onclick'=> "js:function(){  document.location = '$nextLink';}"),
            array('name'=>'Exit',    'onclick'=> "js:function(){guiders.hideAll();}")
        ),
        'description'   => 'we are not going to travel very far from here, just jumpt to aother page and we are back.',
        'overlay'       => true,
        'autoFocus'     => true,
    )
);

Use your own style

By setting both the 'classString' and 'cssFile' options, you can customize the style of your guider.
It is important to understand that in all Guiders included into a page, share the same CSS files, so if you delcare a stylesheet on the first guide of your page, no need to declare it for other guides in the same page.
Another point is that even if you declare a custom stylesheet, the default CSS file provided with the Guiders JQuery plugin is always included : your custom stylesheet must overloads it and redefine styles you want to change.

$this->widget('ext.eguiders.EGuider', array(
        'id'          => 'style',
        'title'       => "Custom style is also available !",
        'next'        => 'end',
        'description' => "<b>Yes you can !</b> ... Simply register your own CSS style and choose a CSS class name "
        ." that will be added to the parent enclosing DIV.",
        'classString' => 'custom',
        'buttons'     => array(array('name'=>'Next')),
        
        // remember that this CSS is going to overloads the default one,
        // not replace it !!
        
        'cssFile'     => Yii::app()->baseUrl. '/css/custom_guiders.css',
        'classString' => 'custom',
    )
);

There's a lot more on using the Guiders plugin, so have a look at the official Project page


bootstrap - Copyright © 2014 by Raoul.
All Rights Reserved.
Powered by Yii Framework.