HTML Client API Reference

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

The article provides an overview of the generated portions of the JavaScript API for LightSwitch HTML clients.

Each entity and screen, and the app itself, exposes the following entry points where you can write custom JavaScript code for your app.

Entity Created

myapp.[EntityName].created = function (entity) {};

This method is called when an entity is created. The entity object creates a generated property for each property listed in the entity designer.

It is typically used to set global property values for an entity. The following example sets the initial value for a BooleanInsured property of a Patient entity:

myapp.Patient.created = function (entity) {  
    entity.Insured = new Boolean();  
    entity.Insured = 'true';  
};  

To access this entry point, open the designer for the entity, and choose the HTMLClient perspective. In the Write Code list, choose created.

Screen Created

myapp.[ScreenName].created = function (screen) {}

This method is called each time a screen is created.

It is typically used to set initial values for fields on a screen. The following example sets the value for the State field on a AddEditPatient screen:

myapp.AddEditPatient.created = function (screen) {  
   screen.Patient.State = 'CA'  
};  

To access this entry point, open the designer for the screen. In the Write Code list, choose created.

Screen Before Apply Changes

myapp.[ScreenName].beforeApplyChanges = function (screen) {};

This method is called each time a save operation is initiated for a screen. If the method returns true, the save operation proceeds. If it returns false, the save operation is canceled. If the method returns a WinJs.Promise object, the save operation waits for the promise to complete (or fail) before continuing.

It is typically used for screen validation logic. The following example validates the PatientName field:

myapp.AddEditPatient.beforeApplyChanges = function (screen) {  
    if (screen.Patient.PatientName.indexOf('!') != -1) {  
        screen.findContentItem("PatientName").validationResults = [  
        new msls.ValidationResult(  
        screen.Patient.details.properties.PatientName,  
        "Patient Name cannot contain the character '!'.")  
        ];  
        return false;  
    }  
};  

To access this entry point, open the designer for the screen. In the Write Code list, choose beforeApplyChanges.

Application Save

myapp.onsavechanges = function () {}

This method is called when a save operation takes place, after the beforeApplyChanges method returns true.

It is typically used to add logic to the save operation, for example, when saving to multiple data sources. The following example uses the WinJs.Promise object to customize the built-in Save command.

myapp.onsavechanges = function (e) {  
    var promises = [];  
    promises.push(myapp.activeDataWorkspace.NorthwindData.saveChanges());  
    promises.push(myapp.activeDataWorkspace.ApplicationData.saveChanges());  
    e.detail.promise = WinJS.Promise.join(promises);  
};  

To access this entry point, open the designer for the screen, and then choose Write Code.

Screen Methods

Each screen method that is listed in the screen members list of the screen designer has two methods available: execute and canExecute. The execute method is typically used to perform a function when a user clicks a button. The canExecute method is typically used to enable or disable a button based on a condition.

  • Method signature: myapp.MyScreen.MyMethod_execute = function (screen) { };

    Executed when the MyMethod button is clicked or when the MyScreen.MyMethod() method is called from code.

    The following example deletes the selected Customer on a BrowseCustomers screen:

    myapp.BrowseCustomers.DeleteSelected_execute = function (screen) {  
        screen.getCustomers().then(function (customers) {  
            customers.deleteSelected();  
        });  
    };  
    
    
  • Method signature: myapp.MyScreen.MyMethod_canExecute = function (screen) { };

    Called before a method runs. If this function returns false, the MyMethod button will be disabled. If it returns true, the button will be enabled.

    The following example disables a Delete button for a record that hasn’t been saved yet.

    myapp.MyScreen.Delete_canExecute = function (screen) {  
        return (screen.MyEntity.Id != null);  
    };  
    
    

To access screen methods, open the shortcut menu for the method in the left pane of the screen designer, and then choose the method.

Screen Content Render

myapp.[ScreenName].[ContentItemName]_render = function (element, contentItem)

This method is called when a screen is created and applies only to custom controls. It is typically used to render the contents of the control on the screen.

element is the HTML element for the control. Use $(element) to create a jQuery object.

contentItem is an msls.ContentItem object that allows access to the item’s value, databinding, and validation results.

The following example displays an OrderDate for each row in a RowTemplate control:

myapp.BrowseOrders.RowTemplate_render = function (element, contentItem) {   
 var orderDate = $("<p>" + contentItem.value.OrderDate + "</p>");   
 orderDate.appendTo($(element));   
};  

To access the render method, choose a custom control in the screen designer. In the Write Code list, choose ControlName_render.

Screen Content Post Render

myapp.BrowseTable1Items.ContentItem2_postRender = function (element, contentItem) {};

This method is called after a screen is created or refreshed. It is typically used to modify the contents or appearance of a control on the screen.

element is the HTML element for the control. Use $(element) to create a Jquery object.

contentItem is an msls.ContentItem object that allows access to the item’s value, databinding, and validation results.

The following example formats a Double to display two decimal places in a control named Unit:

myapp.ViewItems.Unit_postRender = function (element, contentItem) {  
    contentItem.dataBind("value", function (value) {  
        if (value) {  
            $(element).text(value.toFixed(2));  
        }  
    });  
}  

To access the postRender method, choose a control in the screen designer. In the Write Code list, choose ControlName_postRender.

LightSwitch generates a custom API set based on project assets that you can use when writing custom code in the HTML client. Each data source, table, query and screen generates various items in the API set.

(global variable) msls

Members

_run

_run([homeScreenId : String])

Asynchronously launches the LightSwitch application. This method is called in the default.html file for the application.

Return type: WinJS.Promise

promiseOperation

promiseOperation(init(operations), [independent: Boolean])

Initiates a new operation and returns a promise object when that operation is complete.

Return type: WinJS.Promise

Example:

//Method that imports data from Northwind.svc  
myapp.BrowseOrders.ImportOrders_execute = function (screen) {   
    var northwind = "http://services.odata.org/Northwind/Northwind.svc";   
    return msls.promiseOperation(function (operation) {   
        OData.read({ requestUri: northwind + "/Orders?$top=10",   
            recognizeDates: true,   
            enableJsonpCallback: true },   
                     function success(result) {   
                         var results = result.results;   
                         for (var i = 0, len = results.length; i < len; i++) {   
                             var importedOrder = screen.Orders.addNew();   
                             importedOrder.OrderDate = results[i].OrderDate;   
                         }    
                         operation.complete();   
                     },   
                     function error(e) { operation.error(e); });   
    });   
};  

relativeDates

relativeDates

Contains the implementation of globally defined relative dates.

Return type: Date

Methods that start with "end" return a time of 23:59:59. Methods that start with "start" return a time of 00:00:00.

MethodReturns
endOfDay()The date and time for the end of the current day.
endOfMonth()The date and time for the end of the current month.
endOfQuarter()The date and time for the end of the current quarter.
endOfWeek()The date and time for the end of the current week.
endOfYear()The date and time for the end of the current year.
now()The current date and time.
startOfMonth()The date and time for the start of the current month.
startOfQuarter()The date and time for the start of the current quarter.
startOfWeek()The date and time for the start of the current week.
startOfYear()The date and time for the start of the current year.
today()The current date with a time of 00:00:00.

The following code example returns the related startOfWeek and endOfWeek values for a given date:

myapp.AddEditAppointment.created = function (screen) {  
    // Write code here.   
    var currDT = new Date();  
    ws = msls.relativeDates.startOfWeek(currDT);  
    we = msls.relativeDates.endOfWeek(currDT);  
    screen.Appointment.StartDate = ws;  
    screen.Appointment.EndDate = we;  
}  

relativeDateTimeOffsets

relativeDateTimeOffsets

Contains the implementation of globally defined relative dates using the offset from Coordinated Universal Time (UTC).

Return type: Date

Methods that start with "end" return a time of 23:59:59. Methods that start with "start" return a time of 00:00:00.

MethodReturns
endOfDay()The date and time for the end of the current day.
endOfMonth()The date and time for the end of the current month.
endOfQuarter()The date and time for the end of the current quarter.
endOfWeek()The date and time for the end of the current week.
endOfYear()The date and time for the end of the current year.
now()The current date and time.
startOfMonth()The date and time for the start of the current month.
startOfQuarter()The date and time for the start of the current quarter.
startOfWeek()The date and time for the start of the current week.
startOfYear()The date and time for the start of the current year.
today()The current date with a time of 00:00:00.

render

render(element: HTMLElement, contentItem: msls.ContentItem)

Renders the visualization of a content item inside a root HTML element.

Example:

myapp.BrowseOrders.RowTemplate_render = function (element, contentItem) {  
    var orderDate = $("<p>").text(contentItem.value.Customer.CompanyName);  
    orderDate.appendTo($(element));  
};  

showMessageBox

showMessageBox(message:String, [options])

Displays a message box to the user.

Return type: WinJS.Promise

A promise is returned when the user closes the message box. You can access the result of the message box (of type msls.MessageBoxResult) through the returned promise.

Options:

ParameterDescriptionDefault
titleA title for the message box.none
buttonsA msls.MessageBoxButtons value that specifies the buttons to show.ok

Example:

myapp.AddEditCustomer.Delete_execute = function (screen) {  
    msls.showMessageBox("Are You Sure?", {  
        title: "Delete Customer",  
    buttons: msls.MessageBoxButtons.yesNo  
}).then(function (val) {  
    if (val == msls.MessageBoxResult.yes) {  
        screen.Customer.deleteEntity();  
        myapp.commitChanges().then(null, function fail(e) {  
            var errmsg = screen.Customer.Name + e.message;  
            myapp.cancelChanges().then(function () {  
  
                var resp = msls.showMessageBox(errmsg, {  
                    title: "ERROR",  
                    buttons: msls.MessageBoxButtons.ok  
                });  
  
                throw e;  
            });  
  
        });  
    }  
});  
};  

showProgress

showProgress(promise: WinJS.Promise)

Shows a progress indicator that prevents the usage of the application until a promise is resolved or rejected.

Example:

msls.showProgress(msls.promiseOperation(function (operation) {  
        $.getJSON(url, function (data) {  
            operation.complete(data); //Operation completed successfully  
        }).error(function (args) {  
            operation.error(args); //Operation completed with error.  
        });  
    }) .then(function (result) {  
        msls.showMessageBox(result);  
    })  
);  

Represents the active LightSwitch application.

System_CAPS_ICON_note.jpg Note

The myapp object is a shortcut for msls.application.

Members

activeDataWorkspace

msls.application.activeDataWorkspace

Gets the current workspace for the application.

Example:

msls.application.activeDataWorkspace.ApplicationData.Query1("parameter value")  
.execute().then(  
        function (results) {  
            if (results.results.length >= 0) {  
                msls.showMessageBox("Found some records!");  
            }  
        },  
        function (error) {  
            alert(error);  
        }  
    );  

applyChanges

msls.application.applyChanges()

Asynchronously applies any pending changes by merging nested changes into the parent change set or saving top-level changes, and stays on the current screen. Calling applyChanges saves all the changes of the current change set. If only one change set exists, it saves the changes to the data source. If the current change set is a nested scope, it commits the changes to the parent change set.

Return type: WinJS.Promise

Example:

// Save changes  
msls.application.applyChanges().then(null, function fail(e) {  
  
    // If an error occurs, show the error.  
    msls.showMessageBox(e.message, { title: e.title }).then(function () {  
        // Discard changes  
        screen.details.dataWorkspace.ApplicationData.details.discardChanges();  
    });  
});  

cancelChanges

msls.application.cancelChanges()

Undoes all changes in the current change set and navigates back to the previous screen.

Return type: WinJS.Promise

Example:

msls.application.commitChanges().then(null, function fail(e) {  
    alert(e.message);  
    msls.application.cancelChanges();  
    throw e;  
});  

commitChanges

msls.application.commitChanges()

Asynchronously commits any pending changes by merging nested changes into the parent change set or saving top-level changes, and then navigates back to the previous screen. Calling commitChanges saves all the changes of the current change set, just like applyChanges. First validation is run on the screen, and if there are no errors, saveChanges is called.

Return type: WinJS.Promise

Example:

msls.application.commitChanges().then(null, function fail(e) {  
    alert(e.message);  
    msls.application.cancelChanges();  
    throw e;  
});  

navigateBack

msls.application.navigateBack()

Prompts the user to commit or cancel any pending changes and to either navigate back to the previous screen, or to stay on the current screen.

Return type: WinJS.Promise

navigateHome

msls.application.navigateHome()

Asynchronously navigates forward to the home screen.

Return type: WinJS.Promise

options

msls.application.options

Gets the values of options that affect the LightSwitch application. Options must be set in the default.htm file, before calling msls._run.

OptionTypeDescription
defaultMergeOptionStringSpecifies how to merge the results of queries with locally cached data. This can be set to a value of msls.MergeOption.
disableUrlScreenParametersBooleanSpecifies whether a primary key is used to form the URL for a screen instance. The bookmarking feature for HTML client screens enables a user to copy the URL for a specific screen instance and return to that instance later. The URL is partially based on the primary key for the screen’s entity, so if the primary key contains sensitive information you may want to prevent users from seeing it by disabling the bookmarking feature.
enableModalScrollRegionsBooleanIndicates whether to use an independent scroll region inside modal views such as dialog boxes and pickers. If this option isn't enabled, modal views will expand to their full size, allowing the user to scroll in the main browser window to see all the content. This option works better with some devices.
showContentBehindDialogBooleanIndicates whether the background screen behind a dialog box should be visible. This has no effect on small devices, because a dialog box always uses the entire display. Hiding the background screen on large devices may improve performance.
transitionAnimationLevelStringSpecifies the level of animation that occurs during transitions. A simple animation can improve performance on some devices. This option can be set to a value of msls.TransitionAnimationLevel.

showScreen

msls.application.showScreen(screenId, [Array parameters],[options])

Asynchronously navigates forward to a specific screen.

Parameter screenId: The modeled name of a screen or the model item that defines a screen.

Optional parameter parameters: An array of screen parameters, if applicable.

Optional parameter options: An object that provides one or more of the following options:

  • beforeShown: A function that is called after boundary behavior has been applied but before the screen is shown.

  • afterClosed: A function that is called after boundary behavior has been applied and the screen has been closed.

Return type: WinJS.Promise

Example:

msls.application.showScreen(AddEditPatient, null, {  
    afterClose: function (addEditScreen, navigationAction) {  
        if (navigationAction == msls.NavigateBackAction.commit) {  
            var newPatient = addEditScreen.Patient;  
            msls.application.showViewPatient(newPatient)  
        }  
    }  
});  

msls.BusinessObject()

Represents a business object.

Members

MemberDescriptionType
detailsRepresents the details for a business object.msls.BusinessObject.Details
ownerGets the business object that owns this details object.msls.BusinessObject
propertiesGets the set of property objects for the owner's properties.msls.BusinessObject.Details.PropertySet

msls.CollectionChange(action, [items], [oldStartingIndex], [newStartingIndex])

Provides data for the collection change event.

Parameter action: The action of type msls.CollectionChangeAction that caused the event.

Optional parameter items: The array of items (collection) affected by the action.

Optional parameter oldStartingIndex: The index at which the items were removed, if applicable.

Optional parameter newStartingIndex: The index at which the items were added, if applicable.

Members

MemberDescriptionType
actionGets the description of the action that caused the event.String
itemsGets the array of items affected by the action.Object
newStartingIndexGets the index at which the items were added, if applicable.Integer
oldStartingIndexGets the index at which the items were removed, if applicable.Integer

msls.CollectionChangeAction

Specifies how a collection has changed.

ValueDescription
addSpecifies that items were added to the collection.
refreshSpecifies that the entire collection has changed.
removeSpecifies that items were removed from the collection.

msls.ContentItem(screenObject, model)

Represents the view model for an item of content that is visualized by a screen. ContentItem is available as the contentItem argument in the postRender and render methods.

Parameter screenObject: The screen (of type msls.Screen) that owns this content item.

Parameter model: The modeled definition of this content item.

Properties

application: Gets the application object to which the item belongs. Type: msls.application.

bindingPath: Gets the binding path between the "data" property (the source) and the "value" property (the target). Type: String.

Example:

// Adds a div element each time the value of ValueControl1 content item changes.  
myapp.EditTable1Item.ChangeNotesControl_render = function (element, contentItem) {  
    var valueControlContentItem = contentItem.screen.findContentItem("ValueControl1");  
    contentItem.dataBind(valueControlContentItem.bindingPath, function (newValue) {  
        $(element).append($("<div> Value of control changed at " + msls.relativeDates.now().toString() + "</div>"));  
    });  
};  

children: Gets the child content items owned by this content item. For example, the children of a Tab would be all the controls shown while the tab is active. Type: Array of Object.

choiceList: Gets the list of static choices for the value of this content item, if applicable. Type: Array.

Example:

myapp.Screen1.created = function (screen) {  
    var myDropDown = screen.findContentItem("Status");  
    var myCustomChoices = new Array({ value: "Active", stringValue: "Active" }, { value: "Resolved", stringValue: "Resolved" });  
  
    myDropDown.choiceList = myCustomChoices;  
    myDropDown.dispatchChange("choiceList");  
    myDropDown.dispatchChange("value");  
};  

choicesSource: Gets or sets a visual collection that provides a dynamic set of choices for the value of this content item. Type: msls.VisualCollection.

System_CAPS_ICON_note.jpg Note

Only applies to the Details Modal Picker control.

The default value is Auto. At run time, the control dynamically creates a visual collection that contains every item on the server. choicesSource can be updated to a more specific visual collection, like the results of a query. Note that the control only initializes the visual collection once for performance reasons.

commandItems: Gets the command content items owned by this content item. Type: Array of msls.ContentItem.

controlModel: Gets the model item describing the control that is visualizing this content item. Type: Object.

data: Gets the source data object from which the details and value properties are bound. Type: Object.

description: Gets or sets the description for this content item. Type: String.

details: Gets the Details property object for the value that this content item represents, using a binding path that is derived from the bindingPath property. Type: msls.BusinessObject.Details.Property.

displayError: Gets the display error that occurred for the control, if any. Type: String.

displayName: Gets or sets the display name for this content item. Type: String.

heightSizingMode: Gets the height sizing mode for this content item. Type: msls.HeightSizingMode (String).

horizontalAlignment: Gets the horizontal alignment of this content item. Type: msls.HorizontalAlignment (String).

isEnabled: Gets a value indicating if the control for this content item should be enabled. Type: Boolean.

isLoading: Gets a value indicating if the control for this content item should be shown in the loading state. Type: Boolean.

isReadOnly: Gets a value indicating if the control for this content item should be read only. Type: Boolean.

isVisible: Gets or sets a value indicating if the control for this content item should be visible. Type: Boolean.

kind: Gets the kind of this content item. Type: msls.ContentItemKind (String).

Example:

// Adds description help to each content item  
myapp.AddEditCustomer.columns_postRender = function (element, contentItem) {  
    // Look for content items with type either 'details' (a navigation property)   
    // or 'value' (non-relationship properties)   
    var contentItemTypes = [];  
    contentItemTypes.push(msls.ContentItemKind.details);  
    contentItemTypes.push(msls.ContentItemKind.value);  
    // Find these content items starting from the children of the 'columns' content item   
    var matchingContentItems = findMatchingContentItems(contentItemTypes, contentItem);  
    // Find all LABEL elements that are descendants of the parent element rendering the   
    // 'columns' content item   
    var $matchingElements = $(element).find("label");  
    $.each($matchingElements, function (index) {  
        // Set the LABEL element to float left   
        $(this).css("float", "left");  
        // Create a new A element that will display the '?' link   
        var $help = $("<a href='#'>?</a>");  
        $help.css({ "cursor": "pointer", "display": "block", "float": "right" });  
        var correspondingContentItem = matchingContentItems[index];  
        // Add a click event handler to display the content item description   
        $help.on('click', function (e) {  
            e.preventDefault();  
            contentItem.screen.HelpText = correspondingContentItem.description;  
            contentItem.screen.showPopup('Help');  
        });  
        // Insert the help element as a sibling after the LABEL element   
        $(this).after($help);  
    });  
};   
function findMatchingContentItems(arrayOfTypes, parentContentItem) {  
    var matches = [];  
    // Return an empty array if no children to look at   
    if (parentContentItem.children.length == 0) {  
        return matches;  
    }  
    $.each(parentContentItem.children, function (i, contentItem) {  
        $.each(arrayOfTypes, function (j, type) {  
            if (contentItem.kind == type) {  
                matches.push(contentItem);  
            }  
        });  
        // Check the child's children for matches   
        matches = matches.concat(findMatchingContentItems(arrayOfTypes, contentItem));  
    });  
    return matches;  
};  

model: Gets the model item that describes this content item. Type: Object.

name: Gets the name of this content item. Type: String.

onchange: Gets or sets a handler for the change event, which is called any time the value of an observable property on this object changes. Type: Function.

pageKind: Gets the type of page (None, Popup, Tab) of this content item. Type: msls.PageKind (String).

parent: Gets the parent content item that owns this content item. Type: msls.ContentItem.

properties: Gets the set of control-specific properties used to configure the visualization of this content item. Type: Object.

screen: Gets the screen that produced this content item. Type: msls.Screen.

stringValue: Gets or sets the string representation of the value property. It’s preferable to use this property instead of the value property when getting a value to be displayed on the screen. Type: String.

validationResults: Gets or sets the current set of validation results for this content item. Type: Array of msls.ValidationResult.

Includes any results that were explicitly set into this property, plus any results that were added by automatic validation or by calling the validate() method. Note that the validation results will not be displayed until the user modifies the property in the UI or tries to save.

Example:

screen.findContentItem("OrderDate").validationResults = [new msls.ValidationResult(screen.Order.details.properties.OrderDate, "Invalid date")];  

value: Gets or sets the value that this content item represents. Type: Object.

valueModel: Gets the model item that describes the value of this content item. Type: Object.

widthSizingMode: Gets the width-sizing mode for this content item. Type: msls.WidthSizingMode (String).

Methods

addChangeListener: Adds a change event listener.

addChangeListener(propertyName, listener)

Parameter propertyName: A property name, or null for the global change event. Type: String.

Parameter listener: The function to call when the change event is raised. Type: Function.

Example:

myapp.AddEditCustomer.created = function (screen) {  
function onPropertyChanged() {  
    // Do something.  
}  
screen.Customer.addChangeListener(  
    "Property", onPropertyChanged);  
  
function onEvent() {  
    // Do something.  
}  
screen.Customer.addEventListener(  
    "Event", onEvent);  
  
// Clean up when screen is closed.  
screen.details.rootContentItem  
.handleViewDispose(function () {  
    screen.Customer.removeChangeListener(  
        "Property", onPropertyChanged);  
    screen.Customer.removeEventListener(  
        "Event", onEvent);  
});  
};  

dataBind: Binds to a source that is identified by a binding path (for example, value.unitPrice).

dataBind(bindingPath, callback)

Parameter bindingPath: A dot-delimited binding path that describes the path to the source. Type: String.

Parameter callback: A function that is called when the source changes. Type: Function.

Example:

myapp.ViewCustomer.Details_postRender = function (element, contentItem) {   
    contentItem.dataBind("screen.Customer.Name", function (value) {   
        contentItem.screen.details.displayName = value;   
    });   
};  

dispatchChange: Raises a change event for a property.

dispatchChange(propertyName)

Parameter propertyName: A property name. Type: String.

Example:

myapp.ViewIncidents.created = function (screen) {  
   myapp.activeDataWorkspace.Main  
  .Statuses  
  .load()  
  .then(function onComplete(data) {  
      var choice = screen.findContentItem("Status"),  
          values = [];  
      data.results.forEach(function (status){  
          values.push({  
              value: status.Id,  
              stringValue: status.Title  
          });  
      });  
      choice.choiceList = values;  
      choice.dispatchChange("choiceList");  
  }, function onError(error) {  
      msls.showMessageBox(error, {  
          title: "Error loading Statuses from the backend"  
      });  
  });  
}  

findItem: Recursively searches for a content item starting from this content item.

findItem(contentItemName)

Parameter contentItemName: The unique name of a content item. Type: String.

Returns msls.ContentItem: The content item with the specified name, if found; otherwise, a false value.

handleViewDispose: Sets a handler for the view dispose event.

handleViewDispose(handler)

Parameter: handler: A function that is called when the view for this content item is disposed. Type: Function.

Example:

myapp.AddEditCustomer.created = function (screen) {  
function onPropertyChanged() {  
    // Do something.  
}  
screen.Customer.addChangeListener(  
    "Property", onPropertyChanged);  
  
function onEvent() {  
    // Do something.  
}  
screen.Customer.addEventListener(  
    "Event", onEvent);  
  
// Clean up when screen is closed.  
screen.details.rootContentItem  
.handleViewDispose(function () {  
    screen.Customer.removeChangeListener(  
        "Property", onPropertyChanged);  
    screen.Customer.removeEventListener(  
        "Event", onEvent);  
});  
};  

hasValidationErrors: Indicates if this content item currently has validation errors.

hasValidationErrors(recursive)

Parameter recursive: Indicates if child content items should also be checked. Type: Boolean.

Returns Boolean: true if there are validation errors; otherwise, false.

Example:

if (screen.findContentItem("name").hasValidationErrors()) {  
        screen.findContentItem("name").validationResults = [];  
    }  

removeChangeListener: Removes a change event listener.

removeChangeListener(propertyName, listener)

Parameter propertyName: A property name, or null for the global change event. Type: String.

Parameter listener: The event listener that should be removed. Type: Function.

Example:

myapp.AddEditCustomer.created = function (screen) {  
function onPropertyChanged() {  
    // Do something.  
}  
screen.Customer.addChangeListener(  
    "Property", onPropertyChanged);  
  
function onEvent() {  
    // Do something.  
}  
screen.Customer.addEventListener(  
    "Event", onEvent);  
  
// Clean up when screen is closed.  
screen.details.rootContentItem  
.handleViewDispose(function () {  
    screen.Customer.removeChangeListener(  
        "Property", onPropertyChanged);  
    screen.Customer.removeEventListener(  
        "Event", onEvent);  
});  
};  

validate: Runs defined validation rules on the value property and updates the value of the validationResults property.

validate(recursive)

Optional parameter recursive: Indicates if child content items should also be validated. If true, the validationResults property on child content items are updated. Type: Boolean.

msls.ContentItemKind

Specifies the kind of a content item.

ValueDescription
collectionSpecifies a content item that binds to a visual collection.
commandSpecifies a content item that binds to a command that invokes a method.
detailsSpecifies a content item that binds to an object such as an entity.
groupSpecifies a content item that contains other content items.
popupSpecifies the root content item of a popup on a screen.
screenSpecifies the root content item of a screen.
tabSpecifies the root content item of a tab on a screen.
valueSpecifies a content item that binds to a value such as a number, date or string.

msls.DataService(dataWorkspace)

Represents a data service.

Optional parameter dataWorkspace: The data workspace that owns this data service. Type: msls.DataWorkspace.

Members

MemberDescriptionType
dataServiceGets the data service that owns this details object.msls.DataService
dataWorkspaceGets the data workspace that manages the data service, if any.msls.DataWorkspace
detailsRepresents the details for a data service.msls.DataService.Details
hasChangesGets a value that indicates whether the data service has changes (that is, whether there are entities pending addition, modification or deletion).Boolean
oncontentchangeGets or sets a handler for the contentchange event, which is called any time any entity owned by the data service changes.Function
ownerGets the data service that owns this details object.msls.DataService
propertiesGets the set of property objects for the data service.msls.DataService.Details.PropertySet

msls.DataServiceQuery(source, rootUri, queryParameters)

Represents a data service query.

Parameter source: A source queryable object.

Optional parameter rootUri: The root request URI if this is a root data service query (for example, a collection navigation query). Type: String.

Optional parameter queryParameters: The query parameters, if available (for example, a screen query based a query operation with parameters). Type: String.

msls.DataWorkspace()

Represents a data workspace.

Members

MemberDescriptionType
dataWorkspaceGets the data workspace that owns this details object.msls.DataWorkspace
detailsRepresents the details for a data workspace.msls.DataWorkspace.Details
hasChangesGets a value that indicates whether the data workspace has changes (that is, whether there are entities pending addition, modification or deletion).Boolean
hasNestedChangeSetsGets a value that indicates whether the data workspace has any nested change sets.Boolean
NestedChangeSet(owner)Represents a nested change set.
oncontentchangeGets or sets a handler for the contentchange event, which is called any time any entity owned by any data service owned by this data workspace changes.Function
ownerGets the data workspace that owns this details object.msls.DataWorkspace
propertiesGets the set of property objects for the data workspace.msls.DataWorkspace.Details.PropertySet

msls.Entity(entitySet)

Represents an entity.

Optional parameter entitySet: An entity set that should contain this entity. Type: msls.EntitySet.

Members

MemberDescriptionType
detailsRepresents the details for an entity.msls.Entity.Details
entityGets the entity that owns this details object.msls.Entity
entitySetGets the entity set that contains the entity.msls.EntitySet
entityStateGets the state (from msls.EntityState) of the entity.String
hasEditsGets a value that indicates whether the entity has edits (that is, if it was added and has been edited, or it is modified or deleted).Boolean
ownerGets the entity that owns this details object.msls.Entity
PropertiesGets the set of property objects for the entity.msls.Entity.Details.PropertySet

msls.EntityCollection(details, data)

Represents a local collection of entities.

Parameter details: The details object for the entity that owns this entity collection. Type: msls.Entity.Details.

Parameter data: An object that provides property data. Type: Object.

Members

MemberDescriptionType
oncollectionchangeGets or sets a handler for the collection change event.Function

msls.EntitySet(dataService, entry)

Represents an entity set.

Parameter dataService: The data service that owns this entity set. Type: msls.DataService.

Parameter entry: An entity set property entry.

Members

MemberDescriptionType
canDeleteGets a value that indicates whether entities in this entity set can be deleted.Boolean
canInsertGets a value that indicates whether entities can be added to this entity set.Boolean
canUpdateGets a value that indicates whether entities in this entity set can be modified.Boolean
dataServiceGets the data service that owns this entity set.msls.DataService
nameGets the name of this entity set.String

msls.EntityState

Specifies the state of an entity.

ValueDescription
addedThe entity is added.
deletedThe entity is marked as deleted.
discardedThe entity is discarded.
modifiedThe entity is modified.
unchangedThe entity is unchanged.

msls.HeightSizingMode

Specifies how the height of a content item is calculated.

ValueDescription
FitToContentSpecifies that the content item height is based on the height of its content.
FixedSizeSpecifies that the content item height is fixed.
StretchToContainerSpecifies that the content item height is based on the available height provided by its parent content item.

msls.HorizontalAlignment

Specifies the horizontal alignment of a content item.

ValueDescription
LeftSpecifies that the content item is left-aligned.
RightSpecifies that the content item is right-aligned.

msls.MergeOption

Specifies how entities that are being loaded into the data workspace are merged with entities that are already in the data workspace.

ValueDescription
appendOnlyEntities that do not exist in the data workspace are added to the data workspace. If an entity is already in the data workspace, the current and original values of the entity's properties are not overwritten with data source values. This is the default merge option.
unchangedOnlyEntities that do not exist in the data workspace are added to the data workspace. If an entity is already in the data workspace and its entity state is unchanged, the current and original values of the entity's properties are overwritten with data source values.

msls.MessageBoxButtons

Specifies the buttons to show in a message box.

ValueDescription
okSpecifies the OK button.
okCancelSpecifies the OK and Cancel buttons.
yesNoSpecifies the Yes and No buttons.
yesNoCancelSpecifies the Yes, No, and Cancel buttons.

msls.MessageBoxResult

Specifies the button in a message box that was chosen.

ValueDescription
cancelSpecifies that the Cancel button was invoked.
noSpecifies that the No button was invoked.
okSpecifies that the OK button was invoked.
yesSpecifies that the Yes button was invoked.

msls.NavigateBackAction

Specifies the action that was taken when navigating back from a screen.

ValueDescription
cancelSpecifies that changes on the previous screen were canceled.
commitSpecifies that changes on the previous screen were committed to the data source.

msls.ObjectWithDetails

Represents an object that contains a details object.

Members

MemberDescriptionType
detailsRepresents the details for an object with details.msls.ObjectWithDetails.Details
onchangeGets or sets a handler for the change event, which is called any time the value of an observable property on this object changes.Function
ownerRepresents the object that owns this details object.msls.ObjectWithDetails
propertiesGets the set of property objects for the owner's properties.msls.ObjectWithDetails.Details.PropertySet

msls.PageKind

Specifies the kind of page represented by a content item.

ValueDescription
NoneSpecifies that the content item does not represent a page.
PopupSpecifies that the content item represents a popup that is shown using a nested boundary option.
TabSpecifies that the content item represents a tab that appears in the screen tabs bar.

Screen(dataWorkspace, modelId, screenParameters)

Represents a screen.

Parameter dataWorkspace: The data workspace associated with the screen. Type: msls.DataWorkspace.

Parameter modelId: The identifier of the model item that defines this screen. Type: String.

Optional parameter screenParameters: An object containing parameters to the screen. Type: Array.

Members

MemberDescriptionType
dataWorkspaceGets the data workspace that provides the screen's data.msls.DataWorkspace
descriptionGets or sets the description for the screen.String
detailsRepresents the details for a screen.msls.Screen.Details
displayNameGets or sets the display name for the screen.String
ownerGets the screen that owns this details object.msls.Screen
pagesGets an array of the root content items for the screen's tabs and popups.msls.ContentItem
propertiesGets the set of property objects for the screen.msls.Screen.Details.PropertySet
rootContentItemGets the root content item for the screen.msls.ContentItem
saveChangesToGets an array of the editable data services for the screen.msls.DataService
screenGets the screen that owns this details object.msls.Screen
serverErrorsGets the server validation errors that occurred when the screen was last saved.msls.ValidationResult
startPageGets the root content item for the screen's start page.msls.ContentItem

msls.Sequence()

Represents a sequence.

Members

MemberDescriptionType
ArrayGets an array that represents this sequence.Object

msls.TransitionAnimationLevel

Specifies the level of animation that occurs during transitions.

ValueDescription
FullUse full-transition animations.
SimpleUse simpler transition animations that are less processor or power intensive.

msls.ValidationResult(property, message)

Represents a validation result.

Parameter property: A property to associate with the validation result. Type: msls.BusinessObject.Details.Property.

Parameter message: A message that describes the validation error. Type: String.

Members

MemberDescriptionType
messageGets a message that describes the validation error.String
propertyGets the property on which the validation error occurred.msls.BusinessObject.Details.Property

VisualCollection(screenDetails, loader)

Represents a collection of data that is shown by a screen.

Parameter screenDetails: The screen details object that owns the screen collection property whose value is this collection. Type: msls.Screen.Details.

Parameter loader: An object that is used to load data into the collection.

Members

MemberDescriptionType
canLoadMoreGets a value that indicates whether this collection is able to load more pages of data.Boolean
countGets the number of items that are currently in this collection.Integer
dataGets the items that are currently in this collection.Array
isLoadedGets a value that indicates whether this collection has loaded one or more pages of data.Boolean
loadErrorGets the last load error that occurred, or returns null if no error occurred.String
screenGets the screen that owns this collection.msls.Screen
selectedItemGets or sets the currently selected item.msls.Entity
stateGets the current state (from msls.VisualCollection.State) of this collection.String

VisualCollection.State values:

ValueDescription
idleSpecifies that the visual collection is not currently loading data.
loadingSpecifies that the visual collection is currently loading data.
loadingMoreSpecifies that the visual collection is currently loading more data.

msls.WidthSizingMode

Specifies how the width of a content item is calculated.

ValueDescription
FitToContentSpecifies that the content item width is based on the width of its content.
FixedSizeSpecifies that the content item width is fixed.
StretchToContainerSpecifies that the content item width is based on the available width provided by its parent content item.

How to: Handle Screen Events
How to: Modify a Screen by Using Code
HTML Client Screens

Show: