Add New

Deprecation Warning! The content below is only applicable for use within deprecated 1.x versions of Rally's App SDK. Use of the component(s) and/or code on this page is not supported. To develop custom apps within our current environments, please see App SDK 2.0 documentation.

The Add New component provides a way to create new items. It initially displays the + Add New button, and when clicked it expands with more options for creating items. Currently, only HierarchicalRequirement, Defect, DefectSuite, TestCase, Iteration, and Release types can be passed through the configuration. If only one item type is provided in the configuration, it will display without a type drop-down.

add new

To directly add a new item (for types that that only require a name), select the type, enter the name, and click Add.

To add a new item using the editor window, click + Add New, select the type, and then Add with Details.

Create an Add New

First include the App SDK javascript:

<script type=text/javascript" src=/apps/[version]/sdk.js"></script>

Instantiate a new Add New:

var addNew = new rally.sdk.ui.AddNewArtifact(config, rallyDataSource);

The parameters for rally.sdk.ui.AddNewArtifact are as follows:

Parameter Description Example
config* An add new configuration object { types: ["HierarchicalRequirement",
"Defect","DefectSuite"
] }
rallyDataSource* An instance of rally.sdk.data.RallyDataSource

new rally.sdk.data.RallyDataSource
("__WORKSPACE_OID__", "__PROJECT_OID__", "__PROJECT_SCOPING_UP__", "__PROJECT_SCOPING_DOWN__")

* = required parameter

The Add New configuration object supports the following properties:

Parameter Description Example
types* An array of Rally artifact types (defaults to ["HierarchicalRequirement", "Defect"] if not provided). ["HierarchicalRequirement",
"Defect","DefectSuite"]
]

* = required parameter

Display an Add New

Once created, use the display method to show the add new:

addNew.display(domElement, callback);

Parameter Description Example
domElement* The element in which to display the add new; may be either an element or an element ID "addNewDiv",
document. getElementById("addNewDiv")
callback An optional function that will be called after the component displays itself function(addNew, eventArgs){ console.log (eventArgs.selectedItem);

* = required parameter

Methods

The Add New component defines the following methods:

Method Name Parameters Description Example
display domElement*, callback Displays the add new; the callback function is called after the add new component displays itself "addNew.display(domElement, function(){ // after display callback });
destroy - Removes this component addNew.destroy();
getValidEvents - Returns a map of events this component supports addNew.getValidEvents();

* = required parameter

Events

Events are used to notify consumers of a component when actions occur.
The following methods are provided in order to interact with this component's events:

Method Parameters Description Example
addEventListener eventName*, listener*, scope Registers the specified listener with the component's queue for the specified event and returns an object which can be used to remove the event listener later. The listener parameter should be a function with two parameters: 1) the component that fired the event; 2) an eventArgs object with properties specific to the event being fired. This function will be called by the component when the event occurs. If the optional scope parameter was specified the function will be called on that object (such as scope.listener(sender, args);).

function listener(sender, eventArgs) {

//Respond to event

}

var eventObj = component.addEventListener (eventName, listener);

removeEventListener eventObj* Unregisters the specified event from the component.
The eventObj parameter should be the return value of addEventListener() when the listener was originally registered.
var eventObj = component.addEventListener (...); component.removeEventListener (eventObj);
getValidEvents -- Returns an object with a property for each event name supported by the component. This is useful for passing as the first parameter to addEventListener(). var eventName = component.getValidEvents ().onClick;

* = required parameter

The Add New component supports the following events:

Event Name Description Event Arguments Example
onAdd Fired when Add is clicked and results in item creation

The eventArgs object contains a single property:

Item: the item the user created directly.

function onAddNewAdd(addNew, eventArgs) {
var createdItem = eventArgs.item; } addNew.addEventListener("onAdd",onAddNewAdd);
onAddWithDetails Fired when Add with Details is clicked and editor window is opened No args passed to the function.

function onAddNewAddWithDetails(addNew){
//addNew add with details button clicked

}

addNew.addEventListener

("onAddWithDetails", onAddNewAddWithDetails);

onCollapse Fired when Close button is clicked and the display is collapsed No args passed to the function.

function onAddNewCollapse(addNew) { //addNew display collapsed

} addNew.addEventListener("onCollapse", onAddNewCollapse);

onError Fired when the component warns about a known error

The eventArgs object contains a single property:

Message: the message the user receives for known error.

function onAddNewError(addNew, eventArgs) {

var message = eventArgs.message;

}

addNew.addEventListener("onError", onAddNewError);

onExpand Fired when + Add New is clicked and the display is expanded No args passed to the function.

function onAddNewExpand(addNew) { //addNew display expanded

}

addNew.addEventListener("onExpand", onAddNewExpand);

onPreCreate Fired before the item is created when Add button is clicked or the editor window is opened

The eventArgs object passed to any event listeners
contains the following properties:

  • Item: The object fields to be created.
  • withDetails: Boolean stating the Add With Details button was clicked if true, otherwise the Add button was clicked.
  • function onAddNewPreCreate(addNew, eventArgs)

    {

    eventArgs.item["field1"] = "value1";

    } addNew.addEventListener ("onPreCreate", onAddNewPreCreate);

    Example

    Copy and paste the following into a Rally custom app.

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <!-- Copyright (c) 2011 Rally Software Development Corp. All rights reserved -->
    <html>
    <head>
        <title>Component Example: Add New</title>
        <meta name="Name" content="Component Example: Add New" />
        <meta name="Version" content="2011.2" />
        <meta name="Vendor" content="Rally Software" />
        <script type="text/javascript" src="/apps/1.26/sdk.js"></script>
        <script type="text/javascript">

           function reloadPage(){
             window.location.reload();
          }

           function onLoad() {

               var rallyDataSource = new rally.sdk.data.RallyDataSource('__WORKSPACE_OID__',
                         '__PROJECT_OID__',
                         '__PROJECT_SCOPING_UP__',
                        '__PROJECT_SCOPING_DOWN__');

               var addNewConfig = {
                 types : ["HierarchicalRequirement","Defect","DefectSuite"]
               };

               var addNew = new rally.sdk.ui.AddNewArtifact(addNewConfig, rallyDataSource);

               addNew.addEventListener('onAdd', reloadPage);

               addNew.display("addNewDiv");
           }

            rally.addOnLoad(onLoad);

        </script>
    </head>
    <body>
    <div id="addNewDiv"></div>
    </body>
    </html>

    Feedback

    Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.