<style type="text/css" scoped>

/* Standard Module Widget CSS */

.yui3-standardmodule-hidden {

display:none;

}

.yui3-standardmodule {

margin:10px;

}

.yui3-standardmodule-content {

padding:3px;

border:1px solid #666;

}

.yui3-standardmodule-content .yui3-widget-hd {

padding:5px;

border:2px solid #aa0000;

background-color:#fff;

overflow:auto;

}

.yui3-standardmodule-content .yui3-widget-bd {

padding:5px;

border:2px solid #0000aa;

background-color:#fff;

overflow:auto;

}

.yui3-standardmodule-content .yui3-widget-ft {

padding:5px;

border:2px solid #00aa00;

background-color:#fff;

overflow:auto;

}

/* Positionable Widget CSS */

.yui3-positionable {

position:absolute;

}

.yui3-positionable-content {

text-align:center;

border:1px solid #000;

background-color:#999966;

color:#fff;

padding:10px;

}

.yui3-positionable-hidden {

visibility:hidden;

}

/* Alignable Widget CSS */

.yui3-alignable {

position:absolute;

}

.yui3-alignable-content {

text-align:center;

border:1px solid #000000;

background-color:#004C6D;

color:#fff;

padding:1px;

}

.yui3-alignable-hidden {

visibility:hidden;

}

/* Example Layout CSS */

.widget-build-example {

border:1px solid #ccc;

padding:5px;

}

.widget-build-example button, .widget-build-example label, .widget-build-example select, .widget-build-example input {

margin-right:5px;

}

.widget-build-example button.fail {

color:#cc0000;

margin-left:10px;

}

.widget-build-example .filler {

color:#999;

}

#x, #y {

width:3em;

}

#widget-build-examples dd {

margin-left:0;

}

#widget-build-examples dt {

margin-bottom:1em;

margin-top:1em;

}

#widget2-example, #widget3-example {

height:15em;

}

#widget2-example select, #widget3-example select {

width:100%;

}

#alignment p {

margin:0;

padding:2px;

color:#dddd00;

}

</style>

<div class="intro">

<p>This example shows how you can mix and match the `WidgetPosition`, `WidgetPositionAlign`, `WidgetStack` and `WidgetStdMod` extensions to build custom versions of the `Widget` class, using `Base.create`.</p>

</div>

<div class="example">

{{>widget-build-source}}

</div>

<h2>Creating Custom Widget Classes</h2>

<p>The `Base` class provides a `create` method which can be used to create custom versions of classes which derive from `Base` by adding extension classes to them.</p>

<p>Widget currently ships with four such extensions: `WidgetPosition`, `WidgetStack`, `WidgetPositionAlign` and `WidgetStdMod`.

These extensions are used to create the basic `Overlay` widget, but can also be used individually, to create custom versions of the base `Widget` class.</p>

<h2>Widget with WidgetStdMod support</h2>

<p>Adding the `WidgetStdMod` extension to Widget, creates a statically positioned Widget, with support for standard module format sections - header, body and footer, which maybe useful in portal type use cases, where the positioning/stacking capabilities which come bundled with Overlay are not required.</p>

<p>To create a custom class, we use <a href="{{apiDocs}}/Base.html#method_Base.create">`Base.create`</a>, which is described in detail on the documention page for <a href="../base/index.html#extensions">Base</a>.</p>

<p>We pass in `Widget` as the main class we want to add extensions to, and `WidgetStdMod` as the extension we'd like added to the main class:</p>

```

var StandardModule = Y.Base.create("standardModule", Y.Widget, [Y.WidgetStdMod]);

// Render from Markup

var stdmod = new StandardModule({

contentBox: "#widget1",

width:"12em",

height:"12em"

});

stdmod.render();

```

<p>`Base.create` will:</p>

<ol>

<li>Create a new class which extends `Widget`</li>

<li>Aggregate known `Base` and `Widget` fields, such as `ATTRS` and `HTML_PARSER` from `WidgetStdMod` on the new class</li>

<li>Augment prototype methods from `WidgetStdMod` onto the new class prototype</li>

</ol>

<p>The first argument to create is the `NAME` of the new class we are creating, just like the `NAME` we define when extending the Widget class directly.</p>

<p>Note that the `Widget` class is unchanged, allowing you to still create `Widget` instances without any standard module support, along with `StandardModule` instances which have standard module support.</p>

<h3>Testing It Out</h3>

<p>The example attempts to set content on an instance of the newly created `StandardModule` class, using the `setStdModContent` method which is added by the extension (which would otherwise not exist on the Widget instance).</p>

```

var contentInput = Y.one("#content");

var sectionInput = Y.one("#section");

// This should work, since the StandardModule widget has settable

// header/body/footer sections

Y.on("submit", function(e) {

e.preventDefault();

var content = Y.Escape.html(contentInput.get("value"));

var section = sectionInput.get("value");

stdmod.setStdModContent(section, content);

}, "#widget1-example");

```

<p>To verify that no unrequested features are added, we also attempt to move the instance using the `move` method, which is not part of the base Widget class, and would be added by the `WidgetPosition` extension. This verifies that the other example classes we'll create, which do create new classes which use `WidgetPosition`, have not modified the base Widget class.</p>

```

// This shoud fail, since the StandardModule widget is not positionable

Y.on("click", function(e) {

try {

stdmod.move([0,0]);

} catch (e) {

alert("move() is " + typeof stdmod.move + ", stdmod.hasImpl(Y.WidgetPosition) : "

+ stdmod.hasImpl(Y.WidgetPosition));

}

}, "#tryMove");

```

<p>Note that `Base.create` adds a `hasImpl` method to the built class, which allows you to query whether or not it has a particular extension applied.</p>

<h3>CSS Considerations</h3>

<p>We need to define the CSS which goes with this new `StandardModule` class we have created. The only rule really required out of the box is the rule which handles visibility (`yui-standardmodule-hidden`). The "standardmodule" used in the class name comes from the `NAME` property we set up for the new class, and is used to prefix all state related classes added to the widgets bounding box.

Since the `StandardModule` class is not positionable, we use `display:none` to define the `hidden` state.</p>

```

/* Visibility - How to handle visibility for this new widget */

.yui3-standardmodule-hidden {

display:none;

}

```

<p>The other "yui-standardmodule" rules are only used to create the required look/feel for this particular example, and do not impact the StandardModule widget's functionality.</p>

<h2>Widget with WidgetPosition and WidgetStack support</h2>

<p>As with `StandardModule`, we use `Base.create` to create the new `Positionable` widget class. This time we add `WidgetPosition` and `WidgetStack` support to the base `Widget` class to create a basic XY positionable widget, with shimming and z-index support.</p>

```

var Positionable = Y.Base.create("positionable", Y.Widget,

[Y.WidgetPosition, Y.WidgetStack]);

// Render from markup

var positionable = new Positionable({

contentBox: "#widget2",

width:"10em",

height:"10em",

zIndex:1

});

positionable.render("#widget2-example");

var xy = Y.one("#widget2-example > p").getXY();

positionable.move(xy[0], xy[1]);

```

<p>We <strong>don't</strong> add `WidgetPositionAlign` or `WidgetStdMod` support, so the widget doesn't have extended positioning support (align, center) or standard module support. Hence we position it manually using the `move` method which the `WidgetPosition` extension provides.</p>

<h3>Testing It Out</h3>

<p>We should now be able to invoke the `move` method on an instance of the newly created `Positionable` class:</p>

```

// This should work, since Positionable has basic XY Positioning support

Y.on("submit", function(e) {

e.preventDefault();

var x = parseInt(xInput.get("value"));

var y = parseInt(yInput.get("value"));

positionable.move(x,y);

}, "#widget2-example");

```

<p>And, as with the `StandardModule` class, we should not be allowed to invoke any methods from an extension which we didn't request:</p>

```

// This should fail, since Positionable does not have Standard Module sections

Y.on("click", function(e) {

try {

positionable.setStdModContent("header", "new content");

} catch (e) {

alert("setStdModContent() is " + typeof positionable.setStdModContent +

", positionable.hasImpl(Y.WidgetStdMod) : " + positionable.hasImpl(Y.WidgetStdMod));

}

}, "#tryContent");

```

<h3>CSS Considerations</h3>

<p>Since now we have a positionable widget, with z-index support, we set the widget to be absolutely positioned by default, and control it's hidden state using `visibility` as opposed to `display`</p>

```

/* Define absolute positioning as the default for positionable widgets */

.yui3-positionable {

position:absolute;

}

/*

In order to be able to position the widget when hidden, we define hidden

to use visibility, as opposed to display

*/

.yui3-positionable-hidden {

visibility:hidden;

}

```

<h2>Widget with WidgetPosition, WidgetStack and WidgetPositionAlign support</h2>

<p>Lastly, we'll attempt to create a new widget class, which, in addition to basic positioning and stacking support, also has extended positioning support, allowing us to align it with other elements on the page.</p>

<p>Again, we use `Base.create` to create our new `Alignable` widget class, by combining `WidgetPosition`, `WidgetStack` and `WidgetPositionAlign` with the base widget class:</p>

```

var Alignable = Y.Base.create("alignable", Y.Widget,

[Y.WidgetPosition, Y.WidgetPositionAlign, Y.WidgetStack]);

var alignable = new Alignable({

width:"14em",

align : {

node: "#widget3-example",

points: ["cc", "cc"]

},

zIndex:1

});

alignable.get("contentBox").set("innerHTML",

'<strong>Alignable Widget</strong><div id="alignment"><p>#widget3-example</p> \

<p>[center, center]</p></div>');

alignable.render("#widget3-example");

```

<h3>Testing It Out</h3>

<p>We'll attempt to align an instance of the `Alignable` class, using some of the additional attributes which `WidgetPositionAlign` adds to the base `Widget` class: `align` and `centered`:</p>

```

// Align left-center egde of widget to

// right-center edge of the node with id "widget3-example"

alignable.set("align", {node:"#widget3-example", points:["lc", "rc"]});

// Align top-right corner of widget to

// bottom-right corner of the node with id "widget3-example"

alignable.set("align", {node:"#widget3-example", points:["tr", "br"]});

// Center the widget in the node with id "widget3-example"

alignable.set("centered", "widget3-example");

// Align the right-center edge of the widget to

// the right center edge of the viewport (since a node is not provided to 'align')

alignable.set("align", {points:["rc", "rc"]});

// Center the widget in the viewport (wince a node is not provided to 'centered')

alignable.set("centered", true);

// Return the node to it's original alignment

// (centered in the node with id "widget3-example")

// NOTE: centered is a shortcut for align : { points:["cc", "cc"] }

alignable.set("align", {node:"#widget3-example", points:["cc", "cc"]});

```

<h3>CSS Considerations</h3>

<p>The `Alignable` widget class, has the same core CSS rules as the `Positionable` class, to define how it is positioned and how it is hidden:</p>

```

/* Define absolute positioning as the default for alignable widgets */

.yui3-alignable {

position:absolute;

}

/*

In order to be able to position the widget when hidden, we define hidden

to use visibility, as opposed to display

*/

.yui3-alignable-hidden {

visibility:hidden;

}

```

<h2>Complete Example Source</h2>

```

{{>widget-build-source}}

```