e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<style type="text/css" scoped>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai .example-out .myclass-attrs {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai font-family:courier;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai margin-top:2px;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai .example-out .myclass-title {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai font-weight:bold;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai font-family:arial;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai color:#8dd5e7;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai margin-top:5px;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai margin-bottom:3px;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai .example-out {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai overflow:auto;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai border:1px solid #000;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai color:#ffffff;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai background-color:#004C6D;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai margin-top:5px;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai margin-bottom:20px;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai padding:2px 2px 2px 5px;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai #writeInitial label, #writeAgain label, #writeInternally label {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai font-weight:900;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai #writeInitial .fooVal, #writeAgain .fooVal, #writeInternally .fooVal {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai #writeInitial .barVal, #writeAgain .barVal, #writeInternally .barVal {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai #writeInitial p, #writeAgain p, #writeInternally p {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai margin-top:0.2em;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai margin-bottom:0.2em;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai color:#004C6D;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai font-size:108%;
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<div class="intro">
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai <p>Attributes can be configured to be `readOnly`, stopping them from being modified by the end user, or `writeOnce` allowing them to be set by the end user, but only once. This example demonstrates how to setup attributes for your class as `readOnly` or `writeOnce` attributes, and shows how their behavior differs when the end user attempts to set their values.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<div class="example">
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai {{>attribute-rw-source}}
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h2>ReadOnly And WriteOnce</h2>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>Attribute supports the ability to configure attributes to be `readOnly` or `writeOnce`. `readOnly` attributes cannot be set by the end user, either through initial values passed to the constructor, or by invoking the `set` method. `writeOnce` attributes on the other hand, can be set by the user, but only once, either during initialization or through a call to `set`. Once a value is established for a `writeOnce` attribute, it cannot be reset to another value by the user.</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h2>Configuring ReadOnly And WriteOnce Attributes</h2>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>This example sets up a custom class, `MyClass`, with two attributes, `foo` and `bar`. `foo` is configured to be a `readOnly` attribute, and `bar` is configured to be a `writeOnce` attribute:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai// Setup a custom class with attribute support
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaifunction MyClass(cfg) {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // Attribute configuration
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai var attrs = {
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai value: "Default Foo",
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai readOnly: true
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai value: "Default Bar",
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai writeOnce: true
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h2>Attempting To Set Values</h2>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>We first attempt to set values for both attributes in the constructor (used to intialize the attributes) and see that only `bar`, the `writeOnce` attribute, gets set to the user provided value:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaivar fooVal = Y.one("#writeInitial .fooVal").get("value");
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaivar barVal = Y.one("#writeInitial .barVal").get("value");
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaio1 = new MyClass({
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai foo: fooVal,
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen DesaidisplayValues(o1, "Attempt to set initial values in constructor",
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai "#writeInitial .example-out");
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>We then attempt to set values for both attributes again, using `set`, and see that niether of the values are modified:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaivar fooVal = Y.one("#writeAgain .fooVal").get("value");
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaivar barVal = Y.one("#writeAgain .barVal").get("value");
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai// Attempt to reset values:
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaio1.set("foo", fooVal);
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaio1.set("bar", barVal);
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen DesaidisplayValues(o1, "Attempt to set values again, using set",
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai "#writeAgain .example-out");
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h2>Setting The State Of ReadOnly Values Internally</h2>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<p>Although the user cannot update the value of `readOnly` attributes, it maybe neccessary for the host object to update it's value internally. The example shows how this can be done, using the private `_set` property on the host:</p>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // ... Do something which requires
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // MyClass to change the value
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // of foo ...
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // Host code can reset value of
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // readOnly attributes interally,
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai // by working with the private _set
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai this._set("foo", val);
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desaivar val = Y.one("#writeInternally .fooVal").get("value");
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai// Call method, which sets foo internally...
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen DesaidisplayValues(o1, "Set value of foo (readOnly) interally",
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai "#writeInternally .example-out");
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai<h2>Complete Example Source</h2>
e808b8824ca1091c8efb5669db9129e68e5e1c14Satyen Desai{{>attribute-rw-source}}