update: string, specifies the selector whose HTML content should be replaced
* by the AJAX request result.
*
replace: string, specifies the selector whose target should be replaced
* by the AJAX request result.
*
* @return string the generated JavaScript
* @see http://docs.jquery.com/Ajax/jQuery.ajax#options
*/
public static function ajax($options)
{
self::getClientScript()->registerCoreScript('jquery');
if(!isset($options['url']))
$options['url']='js:location.href';
else
$options['url']=self::normalizeUrl($options['url']);
if(!isset($options['cache']))
$options['cache']=false;
if(!isset($options['data']) && isset($options['type']))
$options['data']='js:jQuery(this).parents("form").serialize()';
foreach(array('beforeSend','complete','error','success') as $name)
{
if(isset($options[$name]) && strpos($options[$name],'js:')!==0)
$options[$name]='js:'.$options[$name];
}
if(isset($options['update']))
{
if(!isset($options['success']))
$options['success']='js:function(html){jQuery("'.$options['update'].'").html(html)}';
unset($options['update']);
}
if(isset($options['replace']))
{
if(!isset($options['success']))
$options['success']='js:function(html){jQuery("'.$options['replace'].'").replaceWith(html)}';
unset($options['replace']);
}
return 'jQuery.ajax('.CJavaScript::encode($options).');';
}
/**
* Generates the URL for the published assets.
* @param string the path of the asset to be published
* @return string the asset URL
*/
public static function asset($path)
{
return Yii::app()->getAssetManager()->publish($path);
}
/**
* Generates the HTML code for including the specified core script.
* @param string core script name. The valid names are listed in framework/web/js/packages.php
* @return string the HTML code
*/
public static function coreScript($name)
{
return self::getClientScript()->renderCoreScript($name);
}
/**
* Generates a URL if the input specifies the route to a controller action.
* @param mixed the URL to be normalized. If a string, the URL is returned back;
* if an array, it is considered as a route to a controller action and will
* be used to generate a URL using {@link CController::createUrl}; if the URL is empty,
* the currently requested URL is returned.
* @param string the URL
*/
public static function normalizeUrl($url)
{
if(is_array($url))
$url=isset($url[0]) ? Yii::app()->getController()->createUrl($url[0],array_splice($url,1)) : '';
return $url==='' ? Yii::app()->getRequest()->getUrl() : $url;
}
/**
* Generates an input HTML tag.
* This method generates an input HTML tag based on the given input name and value.
* @param string the input type (e.g. 'text', 'radio')
* @param string the input name
* @param string the input value
* @param array additional HTML attributes for the HTML tag
* @return string the generated input tag
*/
protected static function inputField($type,$name,$value,$htmlOptions)
{
$htmlOptions['type']=$type;
$htmlOptions['value']=$value;
$htmlOptions['name']=$name;
return self::tag('input',$htmlOptions);
}
/**
* Generates a label tag for a model attribute.
* The label text is the attribute label and the label is associated with
* the input for the attribute. If the attribute has input error,
* the label's CSS class will be appended with {@link errorCss}.
* @param CModel the data model
* @param string the attribute
* @param array additional HTML attributes.
* @return string the generated label tag
*/
public static function activeLabel($model,$attribute,$htmlOptions=array())
{
$label=$model->getAttributeLabel($attribute);
$for=get_class($model).'_'.$attribute;
if($model->hasErrors($attribute))
self::addErrorCss($htmlOptions);
return self::label($label,$for,$htmlOptions);
}
/**
* Generates a text field input for a model attribute.
* If the attribute has input error, the input field's CSS class will
* be appended with {@link errorCss}.
* @param CModel the data model
* @param string the attribute
* @param array additional HTML attributes. Besides normal HTML attributes, a few special
* attributes are also recognized (see {@link clientChange} for more details.)
* @return string the generated input field
* @see clientChange
* @see activeInputField
*/
public static function activeTextField($model,$attribute,$htmlOptions=array())
{
self::resolveNameID($model,$attribute,$htmlOptions);
self::clientChange('change',$htmlOptions);
return self::activeInputField('text',$model,$attribute,$htmlOptions);
}
/**
* Generates a hidden input for a model attribute.
* @param CModel the data model
* @param string the attribute
* @param array additional HTML attributes.
* @return string the generated input field
* @see activeInputField
*/
public static function activeHiddenField($model,$attribute,$htmlOptions=array())
{
self::resolveNameID($model,$attribute,$htmlOptions);
return self::activeInputField('hidden',$model,$attribute,$htmlOptions);
}
/**
* Generates a password field input for a model attribute.
* If the attribute has input error, the input field's CSS class will
* be appended with {@link errorCss}.
* @param CModel the data model
* @param string the attribute
* @param array additional HTML attributes. Besides normal HTML attributes, a few special
* attributes are also recognized (see {@link clientChange} for more details.)
* @return string the generated input field
* @see clientChange
* @see activeInputField
*/
public static function activePasswordField($model,$attribute,$htmlOptions=array())
{
self::resolveNameID($model,$attribute,$htmlOptions);
self::clientChange('change',$htmlOptions);
return self::activeInputField('password',$model,$attribute,$htmlOptions);
}
/**
* Generates a text area input for a model attribute.
* If the attribute has input error, the input field's CSS class will
* be appended with {@link errorCss}.
* @param CModel the data model
* @param string the attribute
* @param array additional HTML attributes. Besides normal HTML attributes, a few special
* attributes are also recognized (see {@link clientChange} for more details.)
* @return string the generated text area
* @see clientChange
*/
public static function activeTextArea($model,$attribute,$htmlOptions=array())
{
self::resolveNameID($model,$attribute,$htmlOptions);
self::clientChange('change',$htmlOptions);
if($model->hasErrors($attribute))
self::addErrorCss($htmlOptions);
return self::tag('textarea',$htmlOptions,self::encode($model->$attribute));
}
/**
* Generates a radio button for a model attribute.
* If the attribute has input error, the input field's CSS class will
* be appended with {@link errorCss}.
* @param CModel the data model
* @param string the attribute
* @param array additional HTML attributes. Besides normal HTML attributes, a few special
* attributes are also recognized (see {@link clientChange} for more details.)
* @return string the generated radio button
* @see clientChange
* @see activeInputField
*/
public static function activeRadioButton($model,$attribute,$htmlOptions=array())
{
if(!isset($htmlOptions['value']))
$htmlOptions['value']=1;
if($model->$attribute)
$htmlOptions['checked']='checked';
self::resolveNameID($model,$attribute,$htmlOptions);
self::clientChange('click',$htmlOptions);
return self::activeInputField('radio',$model,$attribute,$htmlOptions);
}
/**
* Generates a check box for a model attribute.
* If the attribute has input error, the input field's CSS class will
* be appended with {@link errorCss}.
* @param CModel the data model
* @param string the attribute
* @param array additional HTML attributes. Besides normal HTML attributes, a few special
* attributes are also recognized (see {@link clientChange} for more details.)
* @return string the generated check box
* @see clientChange
* @see activeInputField
*/
public static function activeCheckBox($model,$attribute,$htmlOptions=array())
{
if(!isset($htmlOptions['value']))
$htmlOptions['value']=1;
if($model->$attribute)
$htmlOptions['checked']='checked';
self::resolveNameID($model,$attribute,$htmlOptions);
self::clientChange('click',$htmlOptions);
return self::activeInputField('checkbox',$model,$attribute,$htmlOptions);
}
/**
* Generates a drop down list for a model attribute.
* If the attribute has input error, the input field's CSS class will
* be appended with {@link errorCss}.
* @param CModel the data model
* @param string the attribute
* @param array data for generating the list options (value=>display)
* @param array additional HTML attributes. Besides normal HTML attributes, a few special
* attributes are also recognized (see {@link clientChange} for more details.)
* @return string the generated drop down list
* @see clientChange
* @see listData
*/
public static function activeDropDownList($model,$attribute,$listData,$htmlOptions=array())
{
$selection=$model->$attribute;
$options="\n".self::listOptions($selection,$listData,$htmlOptions);
self::resolveNameID($model,$attribute,$htmlOptions);
self::clientChange('change',$htmlOptions);
if($model->hasErrors($attribute))
self::addErrorCss($htmlOptions);
return self::tag('select',$htmlOptions,$options);
}
/**
* Generates a list box for a model attribute.
* If the attribute has input error, the input field's CSS class will
* be appended with {@link errorCss}.
* @param CModel the data model
* @param string the attribute
* @param array data for generating the list options (value=>display)
* @param array additional HTML attributes. Besides normal HTML attributes, a few special
* attributes are also recognized (see {@link clientChange} for more details.)
* @return string the generated list box
* @see clientChange
* @see listData
*/
public static function activeListBox($model,$attribute,$listData,$htmlOptions=array())
{
if(!isset($htmlOptions['size']))
$htmlOptions['size']=4;
return self::dropDownList($model,$attribute,$listData,$htmlOptions);
}
/**
* Displays a summary of validation errors for a model.
* @param CModel the data model
* @param string a piece of HTML code that appears in front of the errors
* @param string a piece of HTML code that appears at the end of the errors
* @return string the error summary. Empty if no errors are found.
* @see CModel::getErrors
* @see errorSummaryCss
*/
public static function errorSummary($model,$header='',$footer='')
{
if($header==='')
$header='
'.Yii::t('yii#Please fix the following input errors:').'
';
$content='';
foreach($model->getErrors() as $errors)
{
foreach($errors as $error)
$content.="
".$footer);
else
return '';
}
/**
* Displays the first validation error for a model attribute.
* @param CModel the data model
* @param string the attribute name
* @return string the error display. Empty if no errors are found.
* @see CModel::getErrors
* @see errorMessageCss
*/
public static function error($model,$attribute)
{
$errors=$model->getErrors($attribute);
if(!empty($errors))
return self::tag('div',array('class'=>self::$errorMessageCss),reset($errors));
else
return '';
}
/**
* Generates the data suitable for {@link dropDownList} and {@link listBox}.
* @param array a list of model objects.
* @param string the attribute name for list option values
* @param string the attribute name for list option texts
* @param string the attribute name for list option group names. If empty, no group will be generated.
* @return array the list data that can be used in {@link dropDownList} and {@link listBox}
*/
public static function listData($models,$valueField,$textField,$groupField='')
{
$listData=array();
if($groupField==='')
{
foreach($models as $model)
$listData[$model->$valueField]=$model->$textField;
}
else
{
foreach($models as $model)
$listData[$model->$groupField][$model->$valueField]=$model->$textField;
}
return $listData;
}
/**
* Generates an input HTML tag for a model attribute.
* This method generates an input HTML tag based on the given data model and attribute.
* If the attribute has input error, the input field's CSS class will
* be appended with {@link errorCss}.
* This enables highlighting the incorrect input.
* @param string the input type (e.g. 'text', 'radio')
* @param CModel the data model
* @param string the attribute
* @param array additional HTML attributes for the HTML tag
* @return string the generated input tag
*/
protected static function activeInputField($type,$model,$attribute,$htmlOptions)
{
$htmlOptions['type']=$type;
if(!isset($htmlOptions['value']))
$htmlOptions['value']=$model->$attribute;
if($model->hasErrors($attribute))
self::addErrorCss($htmlOptions);
return self::tag('input',$htmlOptions);
}
/**
* Returns the client script manager.
* This is a shortcut method for getting the client script manager.
* @return CClientScript the client script manager
*/
protected static function getClientScript()
{
return Yii::app()->getController()->getClientScript();
}
/**
* Generates the list options.
* @param mixed the selected value(s). This can be either a string for single selection or an array for multiple selections.
* @param array the option data (see {@link listData})
* @param array additional HTML attributes. The following two special attributes are recognized:
*
*
prompt: string, specifies the prompt text shown as the first list option. Its value is empty.
*
empty: string, specifies the text corresponding to empty selection. Its value is empty.
*
* @return string the generated list options
*/
protected static function listOptions($selection,$listData,&$htmlOptions)
{
$content='';
if(isset($htmlOptions['prompt']))
{
$content.='\n";
unset($htmlOptions['prompt']);
}
if(isset($htmlOptions['empty']))
{
$content.='\n";
unset($htmlOptions['empty']);
}
foreach($listData as $key=>$value)
{
if(is_array($value))
{
$content.=''."\n";
}
else if($key==$selection || is_array($selection) && in_array($key,$selection))
$content.='\n";
else
$content.='\n";
}
return $content;
}
/**
* Generates the JavaScript with the specified client changes.
* @param string event name (without 'on')
* @param array HTML attributes which may contain the following special attributes
* specifying the client change behaviors:
*
*
submit: string, specifies the URL that the button should submit to. If empty, the current requested URL will be used.
*
confirm: string, specifies the message that should show in a pop-up confirmation dialog.
*
ajax: array, specifies the AJAX options (see {@link ajax}).
*
*/
protected static function clientChange($event,&$htmlOptions)
{
if(isset($htmlOptions['submit']) || isset($htmlOptions['confirm']) || isset($htmlOptions['ajax']))
{
if(isset($htmlOptions['on'.$event]))
{
$handler=trim($htmlOptions['on'.$event],';').';';
unset($htmlOptions['on'.$event]);
}
else
$handler='';
if(isset($htmlOptions['id']))
$id=$htmlOptions['id'];
else
$id=$htmlOptions['id']=self::ID_PREFIX.self::$_count++;
$cs=self::getClientScript();
$cs->registerCoreScript('jquery');
if(isset($htmlOptions['submit']))
{
$cs->registerCoreScript('yii');
if($htmlOptions['submit']!=='')
$url=CJavaScript::quote(self::normalizeUrl($htmlOptions['submit']));
else
$url='';
$handler.="jQuery.yii.submitForm(this,'$url');return false;";
unset($htmlOptions['submit']);
}
if(isset($htmlOptions['ajax']))
{
$handler.=self::ajax($htmlOptions['ajax']).'return false;';
unset($htmlOptions['ajax']);
}
if(isset($htmlOptions['confirm']))
{
$confirm='confirm(\''.CJavaScript::quote($htmlOptions['confirm']).'\')';
if($handler!=='')
$handler="if($confirm) {".$handler."} else return false;";
else
$handler="return $confirm;";
unset($htmlOptions['confirm']);
}
$cs->registerBodyScript('Yii.CHtml.#'.$id,"jQuery('#$id').$event(function(){{$handler}});");
}
}
/**
* Generates input name and ID for a model attribute.
* This method will update the HTML options by setting appropriate 'name' and 'id' attributes.
* @param CModel the data model
* @param string the attribute
* @param array the HTML options
*/
protected static function resolveNameID($model,$attribute,&$htmlOptions)
{
if(!isset($htmlOptions['name']))
$htmlOptions['name']=get_class($model).'['.$attribute.']';
if(!isset($htmlOptions['id']))
$htmlOptions['id']=str_replace(array('[]', '][', '[', ']'), array('', '_', '_', ''), $htmlOptions['name']);
}
/**
* Appends {@link errorCss} to the 'class' attribute.
* @param array HTML options to be modified
*/
protected static function addErrorCss(&$htmlOptions)
{
if(isset($htmlOptions['class']))
$htmlOptions['class'].=' '.self::$errorCss;
else
$htmlOptions['class']=self::$errorCss;
}
}