Helpful SharePoint JavaScript functions

[转] http://ruudheemskerk.net/archive/2010/08/03/helpful-sharepoint-javascript-functions.aspx

The init.js and core.js JavaScript files in the layouts directory of SharePoint 2007 contain a lot of helpful JavaScript functions. Here is a brief list of some of the most helpful classes, functions and variables available.

If you are looking for SharePoint 2010, check out the extensive ECMAScript Class Library reference on MSDN: http://msdn.microsoft.com/en-us/library/ee538253.aspx, the SP.Utilities namespace contains loads of helpful utility functions.

function STSScriptEncode(str)

This function can be used to encode javascript variable for usage in scripts.

Location
init.js

Parameters
str
   The string that has to be encoded.

Return value
The encoded string that can be used in scripts.

Example
var strAction = "STSNavigate('" + STSScriptEncode(currentItemUrl) + "')";

function STSScriptEncodeWithQuote(str)

This function can be used to encode and quote javascript variable for usage in scripts.

Location
init.js

Parameters
str
   The string that has to be encoded.

Return value
The encoded string that can be used in scripts, that is enclosed in quotes (").

Example
var strAction = 'STSNavigate(' + STSScriptEncodeWithQuote(currentItemUrl) + ')';

function STSHtmlEncode(str)

This function can be used to encode a string to html.

Location
init.js

Parameters
str
   The string that has to be encoded.

Return value
The string encoded to html.

Example
var html = STSHtmlEncode('htmlString');

function STSNavigate(url)

This function can be used to navigate to a given url.

Location
init.js

Parameters
url
   A string that contains the url to navigate to.

Example
STSNavigate('http://www.microsoft.com');

function STSPageUrlValidation(url)

This function can be used to validate an url whether it starts with "http" or with a slash '/'. The function raises an alert when the url is not valid.

Location
init.js

Parameters
url
   A string that contains the url to check

Return value
If the url is valid it will return the url that has been given as the parameter, if it is not valid it wil return an empty string.

Example
var url = PageUrlValidation('http://www.microsoft.com');

function GetUrlKeyValue(kenName, bNoDecode, url)

This function can be used to get a querystring parameter.

Location
init.js

Parameters
keyName
   A string that contains the name of the parameter.

bNoDecode
   A boolean that states whether the value has will not be encoded, this parameter is optional, default is false.

url
   A string that contains the url to fetch the querystring parameters from, this is optional, the window.location.href will be used if the parameter is null.

Return value
The value of the parameter, encoded if bNoDecode was false.

Example
var action = GetUrlKeyValue('action');

function GetSource(defaultSource)

This function can be used to get the source parameter from the querystring.

Location
init.js

Parameters
defaultSource
   A string that contains the default source, this parameter is optional.

Return value
If the source querystring parameter exists it will return the value of that parameter, otherwise if the defaultSource parameter was given it will return that. In any oter case it will return window.location.href.

Example
var source = GetSource();

function LoginAsAnother(url, bUseSource)

This function can be to change the current user.

Location
init.js

Parameters
url
   A string that contains url to go to after the login.

bUseSource
   A boolean that indicates that the source will be added to the url, otherwise the source will be the window.location.href. This parameter is optional, default is false.

Example
<a href="#" onclick="javascript:LoginAsAnother('\u002f_layouts\u002fAccessDenied.aspx?loginasanotheruser=true', 0)">Log on as a different user</a>


function GoToPage(url)

This function can be used to navigate to an url, adding a source querystring parameter.

Location
init.js

Parameters
url
   A string that contains url to navigate to.

Example
<a href="#" onclick="javascript:GoToPage('/_layouts/settings.aspx')">Settings</a>


function TrimSpaces(str)

This function can be to trim spaces on a string.

Location
init.js

Parameters
str
   A string that will be trimmed.

Return value
The trimmed string.

Example
var trimmed = TrimSpaces(" string with spaces "); // Returns "string with spaces".


function TrimWhiteSpaces(str)

This function can be to trim whitespaces on a string, that is spaces, tabs and linebreaks (\t \n \r \f).

Location
init.js

Parameters
str
   A string that will be trimmed.

Return value
The trimmed string.

Example
var trimmed = TrimWhiteSpaces("\t\tstring with spaces\n");  // Returns "string with spaces".


function escapeProperly(str)

This function takes a string and returns a URL-encoded string.

Location
init.js

Parameters
str
   A string that will be encoded.

Return value
The encoded string.

Example
var urlEncodedValue = escapeProperly("My Value"); // Returns "My%20Value".


function unescapeProperly(str)

This function takes a URL-encoded string and returns an string.

Location
init.js

Parameters
str
   A string that will be decoded.

Return value
The string.

Example
var urlDecodedValue = unescapeProperly("My%20Value"); // Returns "My Value".


class JSRequest

The JSRequest object provides parsing of the querystring, you can easily use this object to get querystring variables, filenames and pathnames.

Location
init.js

Example
JSRequest.EnsureSetup();

// The current url in this example is http://localhost/pages/default.aspx?debug=true
var debug = JSRequest.QueryString["debug"]; // Returns 'true'.
var fileName = JSRequest.FileName; // Returns 'default.aspx'.
var pathName = JSRequest.PathName; // Returns '/pages/default.aspx'.


array _spBodyOnLoadFunctionNames

This array allows you to register additional JavaScript methods that should run in the body onload event.

Location
core.js

Example
_spBodyOnLoadFunctionNames.push('functionName');

You can also pass arguments, for example an id. The next example shows an argument of type string.

_spBodyOnLoadFunctionNames.push('functionName("functionArgument")');

variable L_Menu_BaseUrl

This variable contains the base URL of the current site or subsite.

Location
Inline

Example
document.location = L_Menu_BaseUrl + 'Lists/Tasks/AllItems.aspx';


variable L_Menu_LCID

This variable contains the LCID setting of the current site.

Location
Inline


variable L_Menu_SiteTheme

This variable contains the theme name of the current site.

Location
Inline

variable _spUserId

This variable contains the id of the current user.

Location
Inline

Deferred loading

Be careful using the out of the box scripts from the core.js when it is loaded deferred. In that case, add your scripts to the JQuery on document.ready or via _spBodyOnLoadFunctionNames to be sure that the functions are present.