Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Label.html
index da2ba3d..242235d 100644 (file)
-<html>\r
-<head>\r
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.form.Label"></div>/**
- * @class Ext.form.Label
- * @extends Ext.BoxComponent
- * Basic Label field.
- * @constructor
- * Creates a new Label
- * @param {Ext.Element/String/Object} config The configuration options.  If an element is passed, it is set as the internal
- * element and its id used as the component id.  If a string is passed, it is assumed to be the id of an existing element
- * and is used as the component id.  Otherwise, it is assumed to be a standard config object and is applied to the component.
- * @xtype label
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-form-Label'>/**
+</span> * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
+ *
+ * Produces a standalone `&lt;label /&gt;` element which can be inserted into a form and be associated with a field
+ * in that form using the {@link #forId} property.
+ * 
+ * **NOTE:** in most cases it will be more appropriate to use the {@link Ext.form.Labelable#fieldLabel fieldLabel}
+ * and associated config properties ({@link Ext.form.Labelable#labelAlign}, {@link Ext.form.Labelable#labelWidth},
+ * etc.) in field components themselves, as that allows labels to be uniformly sized throughout the form.
+ * Ext.form.Label should only be used when your layout can not be achieved with the standard
+ * {@link Ext.form.Labelable field layout}.
+ * 
+ * You will likely be associating the label with a field component that extends {@link Ext.form.field.Base}, so
+ * you should make sure the {@link #forId} is set to the same value as the {@link Ext.form.field.Base#inputId inputId}
+ * of that field.
+ * 
+ * The label's text can be set using either the {@link #text} or {@link #html} configuration properties; the
+ * difference between the two is that the former will automatically escape HTML characters when rendering, while
+ * the latter will not.
+ *
+ * # Example
+ * 
+ * This example creates a Label after its associated Text field, an arrangement that cannot currently
+ * be achieved using the standard Field layout's labelAlign.
+ * 
+ *     @example
+ *     Ext.create('Ext.form.Panel', {
+ *         title: 'Field with Label',
+ *         width: 400,
+ *         bodyPadding: 10,
+ *         renderTo: Ext.getBody(),
+ *         layout: {
+ *             type: 'hbox',
+ *             align: 'middle'
+ *         },
+ *         items: [{
+ *             xtype: 'textfield',
+ *             hideLabel: true,
+ *             flex: 1
+ *         }, {
+ *             xtype: 'label',
+ *             forId: 'myFieldId',
+ *             text: 'My Awesome Field',
+ *             margins: '0 0 0 10'
+ *         }]
+ *     });
  */
-Ext.form.Label = Ext.extend(Ext.BoxComponent, {
-    <div id="cfg-Ext.form.Label-text"></div>/**
-     * @cfg {String} text The plain text to display within the label (defaults to ''). If you need to include HTML
+Ext.define('Ext.form.Label', {
+    extend:'Ext.Component',
+    alias: 'widget.label',
+    requires: ['Ext.util.Format'],
+
+<span id='Ext-form-Label-cfg-text'>    /**
+</span>     * @cfg {String} [text='']
+     * The plain text to display within the label. If you need to include HTML
      * tags within the label's innerHTML, use the {@link #html} config instead.
      */
-    <div id="cfg-Ext.form.Label-forId"></div>/**
-     * @cfg {String} forId The id of the input element to which this label will be bound via the standard HTML 'for'
-     * attribute. If not specified, the attribute will not be added to the label.
+<span id='Ext-form-Label-cfg-forId'>    /**
+</span>     * @cfg {String} forId
+     * The id of the input element to which this label will be bound via the standard HTML 'for'
+     * attribute. If not specified, the attribute will not be added to the label. In most cases you will be
+     * associating the label with a {@link Ext.form.field.Base} component, so you should make sure this matches
+     * the {@link Ext.form.field.Base#inputId inputId} of that field.
      */
-    <div id="cfg-Ext.form.Label-html"></div>/**
-     * @cfg {String} html An HTML fragment that will be used as the label's innerHTML (defaults to '').
+<span id='Ext-form-Label-cfg-html'>    /**
+</span>     * @cfg {String} [html='']
+     * An HTML fragment that will be used as the label's innerHTML.
      * Note that if {@link #text} is specified it will take precedence and this value will be ignored.
      */
-
-    // private
-    onRender : function(ct, position){
-        if(!this.el){
-            this.el = document.createElement('label');
-            this.el.id = this.getId();
-            this.el.innerHTML = this.text ? Ext.util.Format.htmlEncode(this.text) : (this.html || '');
-            if(this.forId){
-                this.el.setAttribute('for', this.forId);
-            }
-        }
-        Ext.form.Label.superclass.onRender.call(this, ct, position);
+    
+    maskOnDisable: false,
+    getElConfig: function(){
+        var me = this;
+        return {
+            tag: 'label', 
+            id: me.id, 
+            htmlFor: me.forId || '',
+            html: me.text ? Ext.util.Format.htmlEncode(me.text) : (me.html || '') 
+        };
     },
 
-    <div id="method-Ext.form.Label-setText"></div>/**
-     * Updates the label's innerHTML with the specified string.
+<span id='Ext-form-Label-method-setText'>    /**
+</span>     * Updates the label's innerHTML with the specified string.
      * @param {String} text The new label text
-     * @param {Boolean} encode (optional) False to skip HTML-encoding the text when rendering it
-     * to the label (defaults to true which encodes the value). This might be useful if you want to include
-     * tags in the label's innerHTML rather than rendering them as string literals per the default logic.
-     * @return {Label} this
+     * @param {Boolean} [encode=true] False to skip HTML-encoding the text when rendering it
+     * to the label. This might be useful if you want to include tags in the label's innerHTML rather
+     * than rendering them as string literals per the default logic.
+     * @return {Ext.form.Label} this
      */
-    setText : function(t, encode){
-        var e = encode === false;
-        this[!e ? 'text' : 'html'] = t;
-        delete this[e ? 'text' : 'html'];
-        if(this.rendered){
-            this.el.dom.innerHTML = encode !== false ? Ext.util.Format.htmlEncode(t) : t;
+    setText : function(text, encode){
+        var me = this;
+        
+        encode = encode !== false;
+        if(encode) {
+            me.text = text;
+            delete me.html;
+        } else {
+            me.html = text;
+            delete me.text;
+        }
+        
+        if(me.rendered){
+            me.el.dom.innerHTML = encode !== false ? Ext.util.Format.htmlEncode(text) : text;
         }
         return this;
     }
 });
 
-Ext.reg('label', Ext.form.Label);</pre>    \r
-</body>\r
-</html>
\ No newline at end of file
+</pre>
+</body>
+</html>