/**
* Main API to create a tip.
*
* EXAMPLES:
*---------------------------------------------------
* 1.This will display as a flash-style tip with the specified text
* Tours::tip (array(
* 'content' => "<h1>Welcome to the profile page</h1>"
* ));
*
*---------------------------------------------------
* 2. This example will create a Q-tip dialog,
* and highlight the element '#create-new-user-button'.
* Tours::tip ( array(
* 'content' => 'The button here will create a new user",
* 'target' => '#create-new-user-button'
* ));
*
*
* @param string $content HTML, text, or partial alias OR array of tips
* @param array $params Config array (Described below)
* @return string HTML for a tip
*/
public static function tip($params = array(), $return = false)
{
// $params can be a string for an simple tip
if (is_string($params)) {
return self::tip(array('content' => $params), $return);
}
// If content is not set, no tip can be created
if (!isset($params['content'])) {
throw new Exception("Tips must include a 'content' key");
}
// Dont show tips if user has tips off
if (!Yii::app()->params->profile->showTours) {
return;
}
// Register JS if it is the first tip rendered
if (Tours::$registerJS) {
Yii::app()->clientScript->registerPackage('tours');
Tours::$registerJS = false;
}
// Merge Paramters with default
$params = array_merge(self::$defaultParams, $params);
$content = $params['content'];
// By default the key is an md5 of the content
if ($params['key']) {
$key = $params['key'];
} else {
$key = md5($content);
}
// Get a tip if it hasn't been seen
$tour = self::getTip($key);
if (!$tour) {
return;
}
if ($params['revision']) {
$content = $params['revision'];
}
// Merge Html Options, Default class string
$htmlOptions = array_merge(array('class' => ''), $params['htmlOptions']);
// Translate if specified
if ($params['translate']) {
$content = Yii::t($params['translate'], $content);
}
// set content to partial if specified
if ($params['partial']) {
$content = Yii::app()->controller->renderPartial($content, $params['viewParams'], true);
}
// Replace all replacements
foreach ($params['replace'] as $key => $value) {
$content = preg_replace("/{$key}/", $value, $content);
}
// --- Popup specifics --
// If target is set, create a popup classed tour
if ($params['target']) {
$params['type'] = 'popup';
$htmlOptions['data-target'] = $params['target'];
}
// set content to partial if specified
if ($params['highlight']) {
$htmlOptions['data-highlight'] = true;
}
// Set the type of tip as a class
$htmlOptions['class'] .= " {$params['type']}";
// Return rendered partial
$html = self::render($tour, $content, $params, $htmlOptions);
if ($return) {
return $html;
} else {
echo $html;
}
}
