AssetUrlSelector Class
Collapse the table of content
Expand the table of content

AssetUrlSelector Class

Renders HTML input field and button or generates JavaScript that launches the Asset Picker dialog box used to select a link or image URL from a site collection.


Namespace:  Microsoft.SharePoint.Publishing.WebControls
Assembly:  Microsoft.SharePoint.Publishing (in Microsoft.SharePoint.Publishing.dll)

[AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level = AspNetHostingPermissionLevel.Minimal)]
[SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
public sealed class AssetUrlSelector : WebControl, 
	INamingContainer, IPostBackEventHandler, ICompositeInputControl

You can use an object of this class as a simple server control that provides a text box and a browser button HTML user interface (UI). You can use the object to select a URL that points to an object in the current site collection. The AssetUrl property of the server control shows the current value of the URL selected in the text box.

You can customize the behavior and appearance of the dialog box and change the display of the textbox and button by setting the control's properties. By default, the Asset Picker dialog box opens to allow of the user to select a link URL, and points to either the current AssetUrl location or the last stored location from which the user selected a link URL in an Asset Picker. If there is no current or stored location, then the Asset Picker defaults to any DefaultOpenLocationUrl property that was specified, or to the known locations for the current site and site collection that is presented in the "Look In" section on the left side of the Asset Picker dialog box. By default, when the user selects or types a URL in the Asset Picker dialog box and closes it, the URL is added to the AssetUrlSelector text box.

You can use the AssetUrl property to get this value from the Asset Picker dialog box after a postback event. This class can also be used to launch the Asset Picker dialog box from an HTML element other than the button provided. In this case, any of the Visible(), AssetPickerButtonVisible, or AssetUrlTextBoxVisible properties can be set to false and the GetClientLaunchPickerReference method can be used to return a JavaScript string you can used to launch the Asset Picker dialog box with an HTML element client onClick function or a JavaScript function. You must call the GetClientLaunchPickerReference method before or during the OnPreRender phase of the page life cycle, and you must set properties before calling this method for the correct client JavaScript to register in the page.

Any changes to the control properties after calling the GetClientLaunchPickerReference method do not affect dialog box behavior because the client script that is controlling the dialog box is already registered in the page. You can instantiate an object of this class by adding it to the ASPX page, or by using the AssetUrlSelector constructor and adding it to the child controls for a Control or Page object.

The code samples for this class can be added into any C# Web control or code behind project. They require references to System.Web and Microsoft.SharePoint.Publishing.

This example contains two samples: AddVisibleAssetUrlSelectorControl and GenerateAssetUrlSelectorLaunchScript. Each sample demonstrates properties and methods available in this class.

  • The AddVisibleAssetUrlSelectorControl sample creates a new AssetUrlSelector control, defines its properties and on-event behaviors, and adds the control to the Asset Picker dialog box.

  • The GenerateAssetUrlSelectorLaunchScript sample creates a script that generates an AssetUrlSelector object and adds text boxes to a control collection on a Web.

using Control = System.Web.UI.Control;
using TextBox = System.Web.UI.WebControls.TextBox;
using ButtonType = System.Web.UI.WebControls.ButtonType;
using AssetUrlSelector = Microsoft.SharePoint.Publishing.WebControls.AssetUrlSelector;

namespace Microsoft.SDK.SharePointServer.Samples
    public static class AssetUrlSelectorSamples
        // You can change any of the following default const data
        //  used in the AssetUrlSelector samples.

        // These values control the appearance of the text box
        // and button for the control
        private const bool SampleAssetPickerButtonVisible = true;
        private const bool SampleAssetUrlTextBoxVisible = true;
        private const ButtonType SampleButtonType = ButtonType.Image;
        private const string SampleCssTextBox = "sample-textbox-css";
        private const string SamplePickerButtonImage = "/_layouts/images/icdoc.gif";
        private const string SamplePickerButtonText = "Sample Button Text";

                private const bool SampleAutoPostBack = true;
        private const bool SampleDecodeUrlPath = true;
        private const int SampleMaxLength = 100;
        private const bool SampleValidateUrl = true;
        private const bool SampleIsUrlRequired = true;
        private const bool SampleAllowExternalUrls = false;

        // These values control the appearance and behavior
        // of the Asset Picker dialog box.
        private const string SampleDefaultOpenLocationUrl = "~Site/Pages/";
        private const bool SampleDefaultToLastUsedLocation = false;
        private const bool SampleDisplayLookInSection = false;
        private const bool SampleUseImageAssetPicker = false;
        private const string SampleOverrideDialogDescription = "This is a sample description for the asset picker dialog instructional header";
        private const string SampleOverrideDialogFeatures = "resizable: yes; status: yes; scroll: yes; help: no; dialogWidth:730px; dialogHeight:500px;";
        private const string SampleOverrideDialogImageUrl = "/_layouts/images/icdoc.gif";
        private const string SampleOverrideDialogTitle = "Sample Selection Dialog Title";

        // These values control the complex client script behaviors.
        // This must be JavaScript returning a function object.
        private const string ScriptClientCallback = "function(newAssetUrl, newAssetText, configObject, returnedValue) { window.alert('Client callback with returned url value: ' + newAssetUrl); }";
       // This must be JavaScript returning a string
       // value for asset URL data.
        private const string ScriptGetAssetUrlValue = "window.location.href";

        // AddVisibleAssetUrlSelectorControl - 
        // This sample constructs an AssetUrlSelector with 
        // various settings and adds it to a control collection
        // in a Web page.  The sample function takes in one
        // required argument:
        // containerControl: The control for which the created
        // AssetUrlSelector is added as a child control
        public static void AddVisibleAssetUrlSelectorControl(
            Control containerControl)
            if (null == containerControl)
                throw new System.ArgumentNullException("containerControl", "The containerControl argument must not be null");

            if (null == containerControl.Page)
                throw new System.ArgumentException("The containerControl argument must be a valid control in a System.Web.UI.Page control tree");

            // Create the AssetUrlSelector
            AssetUrlSelector assetSelector = new AssetUrlSelector();

            // Set values for the appearance of the text box and 
            // button for the control
            assetSelector.AssetPickerButtonVisible = SampleAssetPickerButtonVisible;
            assetSelector.AssetUrlTextBoxVisible = SampleAssetUrlTextBoxVisible;
            assetSelector.ButtonType = SampleButtonType;
            assetSelector.CssTextBox = SampleCssTextBox;
            assetSelector.PickerButtonImage = SamplePickerButtonImage;
            assetSelector.PickerButtonText = SamplePickerButtonText;

            // Set values for the behavior and validation
            // for the text box.
            assetSelector.AutoPostBack = SampleAutoPostBack;
            assetSelector.DecodeUrlPath = SampleDecodeUrlPath;
            assetSelector.MaxLength = SampleMaxLength;
            assetSelector.ValidateUrl = SampleValidateUrl;
            assetSelector.IsUrlRequired = SampleIsUrlRequired;
            assetSelector.AllowExternalUrls = SampleAllowExternalUrls;

            // Set values for the apperance and behavior of the asset picker dialog
            assetSelector.DefaultOpenLocationUrl = SampleDefaultOpenLocationUrl;
            assetSelector.DefaultToLastUsedLocation = SampleDefaultToLastUsedLocation;
            assetSelector.DisplayLookInSection = SampleDisplayLookInSection;
            assetSelector.OverrideDialogDescription = SampleOverrideDialogDescription;
            assetSelector.OverrideDialogFeatures = SampleOverrideDialogFeatures;
            assetSelector.OverrideDialogImageUrl = SampleOverrideDialogImageUrl;
            assetSelector.OverrideDialogTitle = SampleOverrideDialogTitle;
            assetSelector.UseImageAssetPicker = SampleUseImageAssetPicker;

            // Sets an event handler for when the AssetUrl value changes on a postback
            assetSelector.AssetUrlChanged += 
                delegate(object sender, System.EventArgs ev)
                    string newAssetUrlValue = ((AssetUrlSelector)sender).AssetUrl;

                    // Perform event handling operations based on the newAssetUrlValue 

            // Add the configured assetSelector to the controls on the page

        // GenerateAssetUrlSelectorLaunchScript
        // This sample constructs an AssetUrlSelector with
        // various settings and adds visible text boxes to a control
        // collection on a Web 
        // page setting their double-click JavaScript 
        // events to launch an asset picker dialog. The sample function
        // takes in one required argument and one optional argument:
        // containerControl: The control for which the created
        //TextBox controls are added as a child control
        // launchPickerWithCurrentBrowserUrl:Determines
        // whether the current AssetUrl property value or the
        // current browser URL 
        value should be used when launching the Asset Picker.
        public static string GenerateAssetUrlSelectorLaunchScript(
            Control containerControl,
            bool launchPickerWithCurrentBrowserUrl)
            if (null == containerControl)
                throw new System.ArgumentNullException("containerControl", "The containerControl argument must not be null");

            if (null == containerControl.Page)
                throw new System.ArgumentException("The containerControl argument must be a valid control in a System.Web.UI.Page control tree");

            TextBox assetUrlControl = new TextBox();
            TextBox assetTextControl = new TextBox();

            // Add these text boxes to the container control so that
            // they get a completed ClientID property for 
            // their container control.

            AssetUrlSelector assetSelector = new AssetUrlSelector();

            // Setting the Page and ID properties is required when the
            // AssetUrlSelector control is not added to the page
            // control tree because
            // the AssetUrlSelector.GetClientLaunchPickerReference()
            // method needs register script in the page
            assetSelector.Page = containerControl.Page;
            assetSelector.ID = "SampleGenerateAssetUrlSelectorLaunchScript";

            // Uses text box client ID to connect the Asset
            // Picker to the text boxes for the resulting
            //  URL and default text values returned from the
            // Asset Picker dialog box.
            assetSelector.AssetUrlClientID = assetUrlControl.ClientID;
            assetSelector.AssetTextClientID = assetTextControl.ClientID;

            // Set the JavaScript to perform after populating the text boxes with the returned values
            assetSelector.ClientCallback = ScriptClientCallback;

            string clientLaunchPickerScript;
                // Use a client launch script that calculates
                // the current asset url with custom javascript
                // which in this example always is the current browser location URL
                clientLaunchPickerScript = assetSelector.GetClientLaunchPickerReference(ScriptGetAssetUrlValue);
                // Use the default client launch script that gets the
                // current asset URL value based on the AssetUrlClientID
                clientLaunchPickerScript = assetSelector.GetClientLaunchPickerReference();

            // Add the client launch script as an ondoubleclick handler for the two text boxes
            assetUrlControl.Attributes["ondblclick"] = clientLaunchPickerScript + "; return false;";
            assetTextControl.Attributes["ondblclick"] = clientLaunchPickerScript + "; return false;";

            // Return the client launch script which can be added to other javascript on the page
            return clientLaunchPickerScript;

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Community Additions

© 2016 Microsoft