JSAPI.info

dojo.create

Dojo (1.6.1) - see full source
7358
7359
7360
7361
7362
7363
7364
7365
7366
7367
7368
7369
7370
7371
7372
7373
7374
7375
7376
7377
7378
7379
7380
7381
7382
7383
7384
7385
7386
7387
7388
7389
7390
7391
7392
7393
7394
7395
7396
7397
7398
7399
7400
7401
7402
7403
7404
7405
7406
7407
7408
7409
7410
7411
7412
7413
7414
7415
7416
7417
7418
7419
7420
7421
7422
7423
7424
7425
7426
7427
7428
7429
7430
7431
7432
7433
7434
7435
7436
7437
7438
7439
dojo.create = function(tag, attrs, refNode, pos){
    //    summary:
    //        Create an element, allowing for optional attribute decoration
    //        and placement.
    //
    // description:
    //        A DOM Element creation function. A shorthand method for creating a node or
    //        a fragment, and allowing for a convenient optional attribute setting step,
    //        as well as an optional DOM placement reference.
    //|
    //        Attributes are set by passing the optional object through `dojo.attr`.
    //        See `dojo.attr` for noted caveats and nuances, and API if applicable.
    //|
    //        Placement is done via `dojo.place`, assuming the new node to be the action
    //        node, passing along the optional reference node and position.
    //
    // tag: String|DomNode
    //        A string of the element to create (eg: "div", "a", "p", "li", "script", "br"),
    //        or an existing DOM node to process.
    //
    // attrs: Object
    //        An object-hash of attributes to set on the newly created node.
    //        Can be null, if you don't want to set any attributes/styles.
    //        See: `dojo.attr` for a description of available attributes.
    //
    // refNode: String?|DomNode?
    //        Optional reference node. Used by `dojo.place` to place the newly created
    //        node somewhere in the dom relative to refNode. Can be a DomNode reference
    //        or String ID of a node.
    //
    // pos: String?
    //        Optional positional reference. Defaults to "last" by way of `dojo.place`,
    //        though can be set to "first","after","before","last", "replace" or "only"
    //        to further control the placement of the new node relative to the refNode.
    //        'refNode' is required if a 'pos' is specified.
    //
    // returns: DomNode
    //
    // example:
    //    Create a DIV:
    //    |    var n = dojo.create("div");
    //
    // example:
    //    Create a DIV with content:
    //    |    var n = dojo.create("div", { innerHTML:"<p>hi</p>" });
    //
    // example:
    //    Place a new DIV in the BODY, with no attributes set
    //    |    var n = dojo.create("div", null, dojo.body());
    //
    // example:
    //    Create an UL, and populate it with LI's. Place the list as the first-child of a
    //    node with id="someId":
    //    |    var ul = dojo.create("ul", null, "someId", "first");
    //    |    var items = ["one", "two", "three", "four"];
    //    |    dojo.forEach(items, function(data){
    //    |        dojo.create("li", { innerHTML: data }, ul);
    //    |    });
    //
    // example:
    //    Create an anchor, with an href. Place in BODY:
    //    |    dojo.create("a", { href:"foo.html", title:"Goto FOO!" }, dojo.body());
    //
    // example:
    //    Create a `dojo.NodeList()` from a new element (for syntatic sugar):
    //    |    dojo.query(dojo.create('div'))
    //    |        .addClass("newDiv")
    //    |        .onclick(function(e){ console.log('clicked', e.target) })
    //    |        .place("#someNode"); // redundant, but cleaner.
 
    var doc = d.doc;
    if(refNode){
        refNode = byId(refNode);
        doc = refNode.ownerDocument;
    }
    if(typeof tag == "string"){ // inline'd type check
        tag = doc.createElement(tag);
    }
    if(attrs){ d.attr(tag, attrs); }
    if(refNode){ d.place(tag, refNode, pos); }
    return tag; // DomNode
};