Sys.Component.create Method

Creates and initializes a component of the specified type. This method is static and can be called without creating an instance of the class.

aComponent.create(type, properties, events, references, element);

Parameters

Parameter

Description

type

The type of the component to create.

properties

(Optional) A JSON object that describes the properties and their values.

events

(Optional) A JSON object that describes the events and their handlers.

references

(Optional) A JSON object that describes the properties that are references to other components.

element

(Optional) The DOM element that the component should be attached to.

Return Value

A new instance of a component that uses the specified parameters.

Remarks

The create method instantiates a component of the specified type. If the component is a control or behavior, the create method attaches the component to the specified element. The method sets any properties or events that are passed as parameters and then calls the initialize method.

The component to create must derive from the Sys.Component class, either directly or by deriving from Sys.UI.Control or Sys.UI.Behavior. You should call the create method during the Sys.Application.init event to make sure that the component being created is available during page load.

The create method can also be invoked by using the $create shortcut method.

Most of the parameters for this method are optional, but a call to the create method must include null as a placeholder for any parameters that you do not pass. The values that are used for the properties, events, and references parameters must be enclosed in braces ({}) and must be in the following standard JSON format:

{argument: value, argument2: value, ...}

The following example shows a create method that passes values for most parameters:

$create(MyControl, {id: 'c1', visible: true}, {click: showValue}, null, $get('button1'));

This method creates an instance of the MyControl class, sets its id property to "c1", and sets its visible property to true. The class has a click event, which is bound to the showValue() function on the page. This instance binds to an HTML DOM element that has an ID of "button1". The class has no properties that refer to other components, therefore the references parameter is set to null.

Note

Do not call the create method or the $create shortcut method from the initialize method of another component. If you do, the new component will not initialize properly. Instead, create the new component and then pass it as a reference to the top component.

See Also

Tasks

Creating Custom Non-Visual Client Components

Reference

Sys.Component Class

Concepts

Creating a Client Component Class Using the Prototype Model

Other Resources

Language Reference