Ewa.BrowserUdfs.add(udfName, function, description, isVolatile, isAsync)
Applies to: apps for SharePoint | Excel Services | SharePoint Server 2013
In this article
Return Value
Remarks
Example
Adds a browser user-defined function (UDF) to the collection of browser UDFs available to the page.
Ewa.BrowserUdfs.add(udfName, udfFunc, description, isVolatile, isAsync);
Parameters
udfName
Type: string
The name of the UDF that is shown to the end user in AutoComplete. The UDF name should be a unique name (case insensitive) across all functions in the Excel model, including built-in functions and Excel Services UDFs.
Important
If a built-in function or Excel Services UDF with the same name exists, the browser UDF will be added but the existing function will take precedence over the browser UDF.
If a browser UDF with the same name is already registered, it will be replaced with the newer UDF with the same name.
udfFunc
Type: function
The function. This can also be the entire function body.
description
Type: string
The text that is shown as a tool tip when using the UDF.
isVolatile
Type: boolean
true if the UDF should be calculated on every calculation operation, regardless of input values changing; otherwise, false.
isAsync
Type: boolean
true if the UDF is going to run asynchronously; otherwise, false. When isAsync equals true, the signature for udfFunc must be constructed to include a context object as the first parameter. When the UDF is registered, Excel Services will set the context object to an [xlAsyncBrowserUdfContext] object. The [xlAsyncBrowserUdfContext] contains a method, [setResult], that is used to place the result of the asynchronous UDF.
Return Value
Type: Boolean
Remarks
Browser UDFs are UDFs that are authored by a web page author and which can be called by an Excel workbook hosted in the same web page. Browser UDFs are registered and unregistered using JavaScript that is included on the host web page. You use the [Ewa.BrowserUdfs.add] method to register and the Ewa.BrowserUdfs.remove(udfName) method to unregister a browser UDF.
Example
The following code example shows how to add a browser UDF to the page. The UDF takes a quantity of items and a price, calculates the cost, and then applies a 6% discount to the cost if the quantity is 100 items or more. The code example assumes that you are working with an Excel Web Access Web Part on SharePoint Server 2013.
<script type="text/javascript">
var ewa = null;
// Add event handler for onload event.
if (window.attachEvent) {
window.attachEvent("onload", ewaOnPageLoad);
}
else {
window.addEventListener("DOMContentLoaded", ewaOnPageLoad, false);
}
// Add event handler for applicationReady event.
function ewaOnPageLoad() {
Ewa.EwaControl.add_applicationReady(onApplicationReady);
}
function onApplicationReady(result) {
ewa = Ewa.EwaControl.getInstances().getItem(0);
var udfs = ewa.getBrowserUdfs();
// Add the browser UDF, "DISCOUNT" to the page
udfs.add("DISCOUNT", DISCOUNT, "Gives company discounted price.", false, false);
}
// UDF that returns a discount (6%) for orders with
// 100 or more items; otherwise it returns 0.
function DISCOUNT(quantity, price) {
var theDiscount = 0;
var discountCost = 0;
var initialAmount = 0;
if (quantity >= 100) {
initialAmount = quantity * price;
// Apply the 6% discount
theDiscount = initialAmount * 0.06;
discountCost = initialAmount - theDiscount;
}
else {
discountCost = initialAmount;
}
return discountCost;
}
</script>