Share via


How to: Customize the Asset Picker

The asset picker tool allows authors to easily insert a URL or an image from any SharePoint library or list in the current site collection. You can use the asset picker to insert content without having to type the URL that points to it. The asset picker is available in many field controls found on publishing sites, such as:

  • The HTML Editor field control

  • The Image field control

  • The Summary Links Web Part

The Look In pane on the left side of the picker window contains shortcuts to predefined SharePoint libraries. These shortcuts are designed to help authors locate content quickly and easily without having to navigate through the folders in the site collection. In image pickers, these shortcuts point to:

  • The image library for the current site

  • The image library for the current site collection

In URL pickers, they point to:

  • The pages library for the current site

  • The document library for the current site

  • The document library for the current site collection

If your authors frequently need to insert documents that are not found in these default locations, you can define an additional shortcut pointing to another location in your site collection. You can define one custom shortcut to image pickers and one to URL pickers. When defined, these shortcuts appear in the Look In pane next to the default shortcuts. You can define custom picker shortcuts only in the scope of one control: After you edit the markup for a control in a template file, only asset pickers launched from that control display the specified custom shortcuts.

Customizing the Asset Picker at the Page Layout Level

You can define a custom picker shortcut for a RichHtmlField or a RichImageField control inside a page layout:

  1. Navigate to \Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\PublishingLayouts\PageLayouts and open a page layout .aspx file.

  2. Find the Publishing field control associated with the control that uses the asset picker. For example, <PublishingWebControls:RichHtmlField> represents the HTML Editor field control.

  3. Add one or both of the following attributes to this tag:

    • DefaultAssetLocation: Defines the URL for the custom shortcut in a URL picker.

    • DefaultAssetImageLocation: Defines the URL for the custom shortcut in an image picker.

      These URLs should be site collection–relative URLs pointing to a library, list, or other location in your site collection, such as "/ReusableContent".

      For example, the following <PublishingWebControls:RichHtmlField> control defines the custom shortcuts /URLpicker and /imagepicker for URL and image pickers, respectively.

      <PublishingWebControls:RichHtmlField id="Content" FieldName="PublishingPageContent" DefaultAssetLocation="/URLpicker" DefaultAssetImageLocation= "/imagepicker" />
      

      Similarly, the following <PublishingWebControls:RichHtmlField> control defines a custom shortcut for its image picker.

      <PublishingWebControls:RichImageField id="Content" FieldName="PublishingPageImage" DefaultAssetImageLocation= "/imagepicker" />
      
  4. Save changes and close the page layout .aspx file.

Add an AssetUrlSelector Control to Any .aspx Page in Your Application

You can add a <cms:AssetUrlSelector> server control to any .aspx page in your application. This server control renders a TextBox that displays the currently selected URL and a LinkButton that, when clicked, runs the appropriate JavaScript code to launch the Asset Picker user interface.

You can use the following attributes of the <cms:AssetUrlSelector> control to customize the Asset Picker dialog box.

Attribute Description

DefaultOpenLocationUrl

Sets the default location where the asset picker should be opened.

DefaultsToLastUsedLocation

Set to True to open the asset picker window in the last used location. The first you use the asset picker, it opens in the location specified by the DefaultOpenLocationUrl property.

Set to False if you always want it to open in the location specified in DefaultOpenLocationUrl.

DisplayLookInSection

Set to True to display a Look In section in the asset picker window. Otherwise, set to False.

OverrideDialogFeatures

Overrides various properties in the Asset Picker dialog box.

OverrideDialogTitle

Sets the title of the Asset Picker dialog box.

OverrideDialogDescription

Sets the description displayed near the top of the Asset Picker dialog box.

OverrideDialogImageUrl

Sets the icon displayed in the upper-right of the Asset Picker dialog box.

AssetTextClientID

When specified, this ID is used to find the HTML element for the AssetText value returned by the asset picker.

Defaults to the ClientID of the child TextBox control.

AsserUrlClientID

When specified, this ID is used to find the HTML element for the AssetUrl value that the asset picker returns.

Defaults to the ClientID of the child TextBox control.

ClientCallback

A string containing a JavaScript function to call when the asset picker dialog box returns a value.

Defaults to String.Empty.

UseImageAssetPicker

Set to True to use the image version of the asset picker.

Set to False to use the URL version. The image picker opens by default in Thumbnail view. If a user selects a URL that does not point to an image, the application warns the user.

AllowExternalURLs

Set to True to allow external URLs to be specified.

The default is False.

AssetUrlTextBoxVisible

Set to False to hide the URL text box.

The default is True.

AssetPickerButtonVisible

Set to False to hide the button that launches the picker window.

The default is True.

AutoPostBack

Set to True to cause the Asset Picker to automatically post back when the user either changes the selected URL by typing directly in the text box, or selects a different item in the asset picker window. The default is False.

AsserUrlClientID

When specified, this ID is used to find the HTML element for the returned AssetUrl value returned by the asset picker.

Defaults to the ClientID of the child TextBox control.

Example

This example <cms:AssetUrlSelector> control uses many of the available attributes.

<CMS:AssetUrlSelector
    DefaultOpenLocationUrl="~SiteCollection/"
    DefaultToLastUsedLocation="false"
    DisplayLookInSection="true"
    OverrideDialogFeatures="resizable: no; status: yes; scroll: yes; help: no; dialogWidth:500px; dialogHeight:500px;"
    OverrideDialogTitle="Custom Picker Title"
    OverrideDialogDescription="Custom Picker Description"
    OverrideDialogImageUrl="~Site/PublishingImages/AssetPickerLogo.jpg"
    AssetTextClientID="testAssetTextClientIDCust"
    ClientCallback="function(returnedUrl) { window.alert('ClientCallback[AssetTextClientID]: ' + returnedUrl); }"
    id="assetSelectedImageCustomLauncher" 
    UseImageAssetPicker=true 
     />