View Source

Class UmbracoHelper

A helper class that provides many useful methods and functionality for using Umbraco in templates

Inheritance

System.Object

Namespace: Umbraco.Cms.Web.Common

Assembly: Umbraco.Web.Common.dll

Syntax

public class UmbracoHelper

Remarks

This object is a request based lifetime

Constructors

UmbracoHelper(ICultureDictionaryFactory, IUmbracoComponentRenderer, IPublishedContentQuery)

Initializes a new instance of UmbracoHelper.

Declaration

public UmbracoHelper(ICultureDictionaryFactory cultureDictionary, IUmbracoComponentRenderer componentRenderer, IPublishedContentQuery publishedContentQuery)

Parameters

Type	Name	Description
ICultureDictionaryFactory	cultureDictionary
IUmbracoComponentRenderer	componentRenderer
IPublishedContentQuery	publishedContentQuery

Remarks

Sets the current page to the context's published content request's content item.

Properties

AssignedContentItem

Gets (or sets) the current IPublishedContent item assigned to the UmbracoHelper.

Declaration

public IPublishedContent AssignedContentItem { get; set; }

Property Value

Type	Description
IPublishedContent

Remarks

Note that this is the assigned IPublishedContent item to the UmbracoHelper, this is not necessarily the Current IPublishedContent item being rendered that is assigned to the UmbracoContext. This IPublishedContent object is contextual to the current UmbracoHelper instance.

In some cases accessing this property will throw an exception if there is not IPublishedContent assigned to the Helper this will only ever happen if the Helper is constructed via DI during a non front-end request.

Exceptions

Type	Condition
System.InvalidOperationException	Thrown if the UmbracoHelper is constructed with an UmbracoContext and it is not a front-end request.

CultureDictionary

Returns the ICultureDictionary for access to dictionary items

Declaration

public ICultureDictionary CultureDictionary { get; }

Property Value

Type	Description
ICultureDictionary

Methods

Content(IEnumerable<Int32>)

Gets the contents corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Content(IEnumerable<int> ids)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.Int32>	ids	The content identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing contents corresponding to the identifiers.

Remarks

If an identifier does not match an existing content, it will be missing in the returned value.

Content(IEnumerable<Object>)

Gets the contents corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Content(IEnumerable<object> ids)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.Object>	ids	The content identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing contents corresponding to the identifiers.

Remarks

If an identifier does not match an existing content, it will be missing in the returned value.

Content(IEnumerable<String>)

Gets the contents corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Content(IEnumerable<string> ids)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.String>	ids	The content identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing contents corresponding to the identifiers.

Remarks

If an identifier does not match an existing content, it will be missing in the returned value.

Content(IEnumerable<GuidUdi>)

Gets the contents corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Content(IEnumerable<GuidUdi> ids)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<GuidUdi>	ids	The content identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing contents corresponding to the identifiers.

Remarks

If an identifier does not match an existing content, it will be missing in the returned value.

Content(IEnumerable<Udi>)

Gets the contents corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Content(IEnumerable<Udi> ids)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<Udi>	ids	The content identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing contents corresponding to the identifiers.

Remarks

If an identifier does not match an existing content, it will be missing in the returned value.

Content(Guid)

Gets a content item from the cache.

Declaration

public IPublishedContent Content(Guid id)

Parameters

Type	Name	Description
System.Guid	id	The key of the content item.

Returns

Type	Description
IPublishedContent	The content, or null of the content item is not in the cache.

Content(Guid[])

Gets content items from the cache.

Declaration

public IEnumerable<IPublishedContent> Content(params Guid[] ids)

Parameters

Type	Name	Description
System.Guid[]	ids	The keys of the content items.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The content items that were found in the cache.

Content(Int32)

Gets a content item from the cache.

Declaration

public IPublishedContent Content(int id)

Parameters

Type	Name	Description
System.Int32	id	The unique identifier of the content item.

Returns

Type	Description
IPublishedContent	The content, or null of the content item is not in the cache.

Content(Int32[])

Gets content items from the cache.

Declaration

public IEnumerable<IPublishedContent> Content(params int[] ids)

Parameters

Type	Name	Description
System.Int32[]	ids	The unique identifiers of the content items.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The content items that were found in the cache.

Content(Object)

Gets a content item from the cache.

Declaration

public IPublishedContent Content(object id)

Parameters

Type	Name	Description
System.Object	id	The unique identifier, or the key, of the content item.

Returns

Type	Description
IPublishedContent	The content, or null of the content item is not in the cache.

Content(Object[])

Gets content items from the cache.

Declaration

public IEnumerable<IPublishedContent> Content(params object[] ids)

Parameters

Type	Name	Description
System.Object[]	ids	The unique identifiers, or the keys, of the content items.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The content items that were found in the cache.

Remarks

Does not support mixing identifiers and keys.

Content(String)

Gets a content item from the cache.

Declaration

public IPublishedContent Content(string id)

Parameters

Type	Name	Description
System.String	id	The unique identifier, or the key, of the content item.

Returns

Type	Description
IPublishedContent	The content, or null of the content item is not in the cache.

Content(String[])

Gets content items from the cache.

Declaration

public IEnumerable<IPublishedContent> Content(params string[] ids)

Parameters

Type	Name	Description
System.String[]	ids	The unique identifiers, or the keys, of the content items.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The content items that were found in the cache.

Remarks

Does not support mixing identifiers and keys.

Content(GuidUdi[])

Gets the contents corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Content(params GuidUdi[] ids)

Parameters

Type	Name	Description
GuidUdi[]	ids	The content identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing contents corresponding to the identifiers.

Remarks

If an identifier does not match an existing content, it will be missing in the returned value.

Content(Udi)

Declaration

public IPublishedContent Content(Udi id)

Parameters

Type	Name	Description
Udi	id

Returns

Type	Description
IPublishedContent

Content(Udi[])

Gets the contents corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Content(params Udi[] ids)

Parameters

Type	Name	Description
Udi[]	ids	The content identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing contents corresponding to the identifiers.

Remarks

If an identifier does not match an existing content, it will be missing in the returned value.

ContentAtRoot()

Declaration

public IEnumerable<IPublishedContent> ContentAtRoot()

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>

ContentAtXPath(String, XPathVariable[])

Declaration

public IEnumerable<IPublishedContent> ContentAtXPath(string xpath, params XPathVariable[] vars)

Parameters

Type	Name	Description
System.String	xpath
XPathVariable[]	vars

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>

ContentAtXPath(XPathExpression, XPathVariable[])

Declaration

public IEnumerable<IPublishedContent> ContentAtXPath(XPathExpression xpath, params XPathVariable[] vars)

Parameters

Type	Name	Description
System.Xml.XPath.XPathExpression	xpath
XPathVariable[]	vars

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>

ContentSingleAtXPath(String, XPathVariable[])

Declaration

public IPublishedContent ContentSingleAtXPath(string xpath, params XPathVariable[] vars)

Parameters

Type	Name	Description
System.String	xpath
XPathVariable[]	vars

Returns

Type	Description
IPublishedContent

GetDictionaryValue(String)

Returns the dictionary value for the key specified

Declaration

public string GetDictionaryValue(string key)

Parameters

Type	Name	Description
System.String	key

Returns

Type	Description
System.String

GetDictionaryValue(String, String)

Returns the dictionary value for the key specified, and if empty returns the specified default fall back value

Declaration

public string GetDictionaryValue(string key, string altText)

Parameters

Type	Name	Description
System.String	key	key of dictionary item
System.String	altText	fall back text if dictionary item is empty - Name altText to match Umbraco.Field

Returns

Type	Description
System.String

Media(IEnumerable<Int32>)

Gets the medias corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Media(IEnumerable<int> ids)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.Int32>	ids	The media identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing medias corresponding to the identifiers.

Remarks

If an identifier does not match an existing media, it will be missing in the returned value.

Media(IEnumerable<Object>)

Gets the medias corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Media(IEnumerable<object> ids)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.Object>	ids	The media identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing medias corresponding to the identifiers.

Remarks

If an identifier does not match an existing media, it will be missing in the returned value.

Media(IEnumerable<String>)

Gets the medias corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Media(IEnumerable<string> ids)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.String>	ids	The media identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing medias corresponding to the identifiers.

Remarks

If an identifier does not match an existing media, it will be missing in the returned value.

Media(IEnumerable<GuidUdi>)

Gets the medias corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Media(IEnumerable<GuidUdi> ids)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<GuidUdi>	ids	The media identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing medias corresponding to the identifiers.

Remarks

If an identifier does not match an existing media, it will be missing in the returned value.

Media(IEnumerable<Udi>)

Gets the medias corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Media(IEnumerable<Udi> ids)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<Udi>	ids	The media identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing medias corresponding to the identifiers.

Remarks

If an identifier does not match an existing media, it will be missing in the returned value.

Media(Guid)

Declaration

public IPublishedContent Media(Guid id)

Parameters

Type	Name	Description
System.Guid	id

Returns

Type	Description
IPublishedContent

Media(Int32)

Declaration

public IPublishedContent Media(int id)

Parameters

Type	Name	Description
System.Int32	id

Returns

Type	Description
IPublishedContent

Media(Int32[])

Gets the medias corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Media(params int[] ids)

Parameters

Type	Name	Description
System.Int32[]	ids	The media identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing medias corresponding to the identifiers.

Remarks

If an identifier does not match an existing media, it will be missing in the returned value.

Media(Object)

Overloaded method accepting an 'object' type

Declaration

public IPublishedContent Media(object id)

Parameters

Type	Name	Description
System.Object	id

Returns

Type	Description
IPublishedContent

Remarks

We accept an object type because GetPropertyValue now returns an 'object', we still want to allow people to pass this result in to this method. This method will throw an exception if the value is not of type int or string.

Media(Object[])

Gets the medias corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Media(params object[] ids)

Parameters

Type	Name	Description
System.Object[]	ids	The media identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing medias corresponding to the identifiers.

Remarks

If an identifier does not match an existing media, it will be missing in the returned value.

Media(String)

Declaration

public IPublishedContent Media(string id)

Parameters

Type	Name	Description
System.String	id

Returns

Type	Description
IPublishedContent

Media(String[])

Gets the medias corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Media(params string[] ids)

Parameters

Type	Name	Description
System.String[]	ids	The media identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing medias corresponding to the identifiers.

Remarks

If an identifier does not match an existing media, it will be missing in the returned value.

Media(GuidUdi[])

Gets the medias corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Media(params GuidUdi[] ids)

Parameters

Type	Name	Description
GuidUdi[]	ids	The media identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing medias corresponding to the identifiers.

Remarks

If an identifier does not match an existing media, it will be missing in the returned value.

Media(Udi)

Declaration

public IPublishedContent Media(Udi id)

Parameters

Type	Name	Description
Udi	id

Returns

Type	Description
IPublishedContent

Media(Udi[])

Gets the medias corresponding to the identifiers.

Declaration

public IEnumerable<IPublishedContent> Media(params Udi[] ids)

Parameters

Type	Name	Description
Udi[]	ids	The media identifiers.

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>	The existing medias corresponding to the identifiers.

Remarks

If an identifier does not match an existing media, it will be missing in the returned value.

MediaAtRoot()

Declaration

public IEnumerable<IPublishedContent> MediaAtRoot()

Returns

Type	Description
System.Collections.Generic.IEnumerable<IPublishedContent>

RenderMacroAsync(String)

Renders the macro with the specified alias.

Declaration

public async Task<IHtmlEncodedString> RenderMacroAsync(string alias)

Parameters

Type	Name	Description
System.String	alias	The alias.

Returns

Type	Description
System.Threading.Tasks.Task<IHtmlEncodedString>

RenderMacroAsync(String, IDictionary<String, Object>)

Renders the macro with the specified alias, passing in the specified parameters.

Declaration

public async Task<IHtmlEncodedString> RenderMacroAsync(string alias, IDictionary<string, object> parameters)

Parameters

Type	Name	Description
System.String	alias	The alias.
System.Collections.Generic.IDictionary<System.String, System.Object>	parameters	The parameters.

Returns

Type	Description
System.Threading.Tasks.Task<IHtmlEncodedString>

RenderMacroAsync(String, Object)

Renders the macro with the specified alias, passing in the specified parameters.

Declaration

public async Task<IHtmlEncodedString> RenderMacroAsync(string alias, object parameters)

Parameters

Type	Name	Description
System.String	alias	The alias.
System.Object	parameters	The parameters.

Returns

Type	Description
System.Threading.Tasks.Task<IHtmlEncodedString>

RenderTemplateAsync(Int32, Nullable<Int32>)

Renders the template for the specified pageId and an optional altTemplateId

Declaration

public async Task<IHtmlEncodedString> RenderTemplateAsync(int contentId, int? altTemplateId = null)

Parameters

Type	Name	Description
System.Int32	contentId	The content id
System.Nullable<System.Int32>	altTemplateId	If not specified, will use the template assigned to the node

Returns

Type	Description
System.Threading.Tasks.Task<IHtmlEncodedString>