Building Dashboards / Parameters in SharePoint Pages / Custom Parameters with Nevron JavaScript API
In This Topic
    Custom Parameters with Nevron JavaScript API
    In This Topic

    To define parameters and give SharePoint users the ability to interactively modify these parameter values trough AJAX, Nevron SharePoint Vision exposes a simple Parameters JavaScript API. This gives you the needed flexibility to develop SharePoint dashboards that blend with the overall SharePoint design that you use, and visualize/manipulate parameters through third party Web UI controls. In order to use the Parameters JScript API, you only need some simple tool, like the Content Web Part, that allows you to deploy custom HTML and Java Script on the client side of the SharePoint page. The Parameters JScript API is automatically deployed to the client side of the SharePoint page, if there is at least one Nevron Web Part dropped on the page.

    The Parameters JScript API, implements functions that perform the three most important tasks related to parameterization.

    1. Query Data Source - these are functions that query the data source of a specific web part for information about distinct values, minimum and maximum. With the help of these functions you can initialize parameters with relevant settings for your data source.

    2. Initialize/display parameters - these are functions that initialize the parameters for the SharePoint page. These functions are generally called from a global script block (i.e. immediately after the SharePoint page is loaded). All initialization functions also allow you to specify the id of a placeholder HTML element, the content of which is replaced with a default for the specific parameter type editor.

    3. Get/Set parameter values - these are functions that let you get/set parameters values from/to the current SharePoint user session that Nevron Web Parts create on the server.  As Nevron SharePoint Vision does not focus on Web UI controls, you will primary use these functions, when you need to use the Parameters JScript API with third party Web UI toolkits (for example jQuery UI, ExtJS, YUI, SAP UI 5 etc.).

    4. Refresh the Web Parts - these are functions that help you force a refresh of all or just concrete web parts on the page.

    The custom parameters that are created by the Parameters JScript API, are available to all Nevron Web Parts that are created on the page.

    The rest of this topic explains these functions in details:

     Query Data Source
    Function Signature Description Examples
    NQueryDistinct(placeholderId, columnName, separator, callback) Queries the data source of the specified web part for distinct values in the specified column. The arguments are:

    placeholderId - the id of the webpart placeholder which to query. See notes below.
    columnName - the name of column for which the query executes.
    separator - separator with which to join the values.
    callback - function which to call when the query returns.    		 HTML
    <div id="CompanyId"/>

    JS
    NQueryDistinct("NWebPart_g_6e168b9c_a328_4f40_97bc_d5308aadb318", "Company", ";",
        function(result) {
            var options = result.split(";");
            NInitSTRParam("CompanyId", "Company", {
                InitialValue: options[0],
                RefreshMode: "auto",
                EnumValues: options});
    });
    NQueryMin(placeholderId, columnName, separator, callback) Queries the data source of the specified web part for min value in the specified column. The arguments are:

    placeholderId - the id of the webpart placeholder which to query. See notes below.
    columnName - the name of column for which the query executes.
    callback - function which to call when the query returns.

    HTML
    <div id="MinSalesId"></div>

    JS
    NQueryMin("NWebPart_g_6e168b9c_a328_4f40_97bc_d5308aadb318", "Sales",
        function (result) {
            NInitNUMParam("MinSalesId", "MinSales", {
                InitialValue: result,
                RefreshMode: "auto",
                Decimals: 2
            });
    });
    NQueryMax(placeholderId, columnName, separator, callback) Queries the data source of the specified web part for max value in the specified column. The arguments are:

    placeholderId - the id of the webpart placeholder which to query. See notes below.
    columnName - the name of column for which the query executes.
    callback - function which to call when the query returns.

    HTML
    <div id="MaxSalesId"></div>

    JS
    NQueryMax("NWebPart_g_6e168b9c_a328_4f40_97bc_d5308aadb318", "Sales",
        function (result) {
            NInitNUMParam("MaxSalesId", "MaxSales", {
                InitialValue: result,
                RefreshMode: "auto",
                Decimals: 2
            });
    });

     

    The placeholder id is a string that is generated from the webpart id prefixed with the "NWebPart_" prefix.

    For example if your webpart id is "g_3f5485fe_039e_49f3_96ea_0249de90d670", the web part placeholder id will be: "NWebPart_g_3f5485fe_039e_49f3_96ea_0249de90d670".

    You can get the webpart id of each Nevron web part from the editing info bar at design time.

    In the SharePoint page HTML, the Query functions JS needs to placed after the respective webparts, whose data sources the functions query. This is because the Query functions obtain information from the placeholder HTML, so it needs to be rendered before the Query functions are executed. One nice idea is to always place your JS at the bottom of the HTML page. You can alternatively call your JS when the document is loaded.
     Initializing and Displaying Parameters
    Function Signature Description Examples
    NInitBOOLParam(id, name, settings)

    Initializes a boolean parameter and replaces the inner HTML of the element with the specified Id, with an HTML <INPUT type=''checkbox"> element. The arguments are:

    id - the id of the HTML element whose inner HTML must be replaced.
    name - the parameter name.
    settings - an options bag with the following properties:

    InitialValue - the initial value for the parameter, if not yet defined. Possible values area: true and false. By default false.
    RefreshMode - the mode in which the parameter refreshes the web parts. Possible values area: none and auto. By default none.

    HTML
    <div id="MyBoolParamId"/>

    JS
    NInitBOOLParam("MyBoolParamId", "MyBoolParam", {
    InitialValue:  true,
    RefreshMode: "auto"
    });
    NInitSTRParam(id, name, settings) Initializes a string parameter and replaces the inner HTML of the element with the specified Id, with an HTML element that depends on the EnumValues and MiltiLine settings. The arguments are:

    id - the id of the HTML element whose inner HTML must be replaced.
    name - the parameter name.
    settings - an options bag with the following properties:

    InitialValue - the initial value for the parameter, if not yet defined. By default an empty string.
    RefreshMode - the mode in which the parameter refreshes the web parts. Possible values area: none and auto. By default none.
    EnumValues - an array of strings that defines the possible values for the parameter. If specified, the string parameter is displayed as an HTML <SELECT> element. 
    MiltiLine - only taken into account if EnumValues is not specified. If set to true the parameter is rendered as a HTML <TEXTAREA> element. Otherwise it is rendered as an <INPUT> element.

    Combo Box

    HTML
    <div id="MyStrComboParamId"/>

    JS
    NInitSTRParam("MyStrComboParamId", "MyStrComboParam", {
    InitialValue:  "Asia",
    RefreshMode: "auto",
    EnumValues: new Array("", "US", "Europe", "Asia")
    });

    Text Box

    HTML
    <div id="MyStrTextBoxParamId"/>

    JS
    NInitSTRParam("MyStrTextBoxParamId", "MyStrTextBoxParam", {
    InitialValue:  "Type something here",
    RefreshMode: "auto"
    });
    NInitNUMParam(id, name, settings)

    Initializes a number parameter and replaces the inner HTML of the element with the specified Id, with an HTML INPUT element that would accept only a valid number. The arguments are:

    id - the id of the HTML element whose inner HTML must be replaced.
    name - the parameter name.
    settings - an options bag with the following properties:

    InitialValue - the initial value for the parameter, if not yet defined. By default 0.
    RefreshMode - the mode in which the parameter refreshes the web parts. Possible values area: none and auto. By default none.
    Decimals - the number of digits to accept behind the decimal point. By default 0.
    Min - the minimal number to accept. By default: -1000000000.
    Max - the maximum number to accept. By default: 1000000000.

    Integer Number Editor

    HTML
    <div id="MyIntParamId"/>

    JS
    NInitNUMParam("MyIntParamId", "MyIntParam", {
    InitialValue: 10,
    RefreshMode: "auto"
    });

    Float Number Editor

    HTML
    <div id="MyFloatParamId"/>

    JS
    NInitNUMParam("MyFloatParamId", "MyFloatParam", {
    InitialValue:  10.3,
    RefreshMode: "auto",
    Decimals : 2
    });

     

    The RefreshMode setting in all initialization functions, defines whether the web parts that reside on the page should be refreshed after the parameter has changed or not. The default setting of none specifies that the web parts should not be refreshed. When you use this option, you must typically create a refresh button, to force the refresh of all web parts (see Web Parts Functions below). The other option - auto - means that all web parts are automatically refreshed when the value of the parameter has changed from the editor.

    All parameters initialization functions are also providing some default HTML representations. If you want to initialize parameters, that do not have a HTML representation (e.g. are invisible or need to be edited in a different way) you can call the respective initialization function with a non existing HTML element id - for example the Id of a randomly generated GUID.
     Getting and Setting Parameter Values
    Function Signature Description Examples
    NSetBOOLParam(paramName, value, setCallback)

    Sets the value of a boolean parameter. The arguments are:

    paramName - the name of the parameter.
    value - parameter value. Should be having the string equivalent of "true" to set to true. All other values evaluate to false.
    setCallback - a function that is executed when the set command has been executed.

    		 NSetBOOLParam("MyBOOLParam", true, function(){
        NGetBOOLParam("MyBOOLParam", function(value){
            alert(value);
        });
    });
    NSetSTRParam(paramName, value, setCallback)

    Sets the value of a string parameter. The arguments are:

    paramName - the name of the parameter.
    value - parameter value. Can be any string
    setCallback - a function that is executed when the set command has been executed.

    		 NSetSTRParam("MySTRParam", "Hello World", function(){
        NGetSTRParam("MySTRParam", function(value){
            alert(value);
        });
    });
    NSetNUMParam(paramName, value, setCallback)

    Sets the value of a numeric parameter. The arguments are:

    paramName - the name of the parameter.
    value - parameter value. Should be having the string equivalent of a numeric value that is formatted according to the "en-us" culture formatting.
    setCallback - a function that is executed when the set command has been executed.

    		 NSetNUMParam("MyNUMParam", 20.56, function(){
        NGetNUMParam("MyNUMParam", function(value){
            alert(value);
        });
    });
    NGetBOOLParam(paramName, getCallback)

    Gets the value of a boolean parameter. The arguments are:

    paramName - the name of the parameter.
    getCallback - a function that is executed when the get command has been executed. The passed argument is a string representation of the of the boolean parameter value - e.g. contains a "true" or "false" string.

    		 NSetBOOLParam("MyBOOLParam", true, function(){
        NGetBOOLParam("MyBOOLParam", function(value){
            alert(value);
        });
    });
    NGetSTRParam(paramName, getCallback)

    Gets the value of a string parameter. The arguments are:

    paramName - the name of the parameter.
    getCallback - a function that is executed when the get command has been executed. The passed argument is a string.

    		 NSetSTRParam("MySTRParam", "Hello World", function(){
        NGetSTRParam("MySTRParam", function(value){
            alert(value);
        });
    });
    NGetNUMParam(paramName, getCallback)

    Gets the value of a numeric parameter. The arguments are:

    paramName - the name of the parameter.
    getCallback - a function that is executed when the get command has been executed. The passed argument is a string that contains the string representation of the number in "en-us" culture formatting.

    		 NSetNUMParam("MyNUMParam", 20.56, function(){
        NGetNUMParam("MyNUMParam", function(value){
            alert(value);
        });
    });

     

     Refreshing the Nevron WebParts

    Function Signature Description Examples
    NRefreshWebPart(id)

    Refreshes the Nevron web part with the specified Id.

    		 NRefreshWebPart("NWebPart_g_63dd3f48_6335_4bde_b6d2_578bec3e9b75");
    NRefreshWebPartAfter(id, milliseconds)

    Refreshes the Nevron web part with the specified Id, after the period of time defined by the milliseconds argument elapses.

    		 NRefreshWebPart("NWebPart_g_63dd3f48_6335_4bde_b6d2_578bec3e9b75", 2000);
    NRefreshAllWebParts()

    Refreshes all Nevron web parts that reside on the current page.

    		 NRefreshAllWebParts();
    NRefreshAllWebPartsAfter(milliseconds)

    Refreshes all Nevron web parts that reside on the current page, after the period of time defined by the milliseconds argument elapses.

    		 NRefreshAllWebPartsAfter(3000);

     

    The web parts refresh functions give you the ability to refresh individual web parts as well as all web parts immediately and after a certain period of time. In general all Nevron Web Parts will render a content placeholder, that has an HTML id argument with the "NWebPart_" prefix, followed by the SharePoint web part Id. The designer of each individual web part shows the SharePoint web part id in its' info bar (located before the main toolbar).
    See Also
    Parameters
    Custom Parameters with SharePoint Filter WebParts
    Actions and Drill Down reports

     

     

    © Nevron Software LLC. All rights reserved. Send Feedback.