| versionFrom |
|---|
8.0.0 |
UmbracoHelper is the unified way to work with published content/media on your website. You can use the UmbracoHelper to query/traverse Umbraco published data.
UmbracoHelper also has a variety of helper methods that are useful when working in your views and controllers.
Nearly all of Umbraco's base classes expose an instance of UmbracoHelper. If you are using MVC Views or Partial View Macros you can reference UmbracoHelper with the syntax: @Umbraco
If you are using SurfaceControllers, RenderMvcControllers, UmbracoApiControllers, or any controller inheriting from UmbracoController, these all expose an UmbracoHelper via the Umbraco property.
For webservices and HTTP handlers, these base classes expose UmbracoHelper via the Umbraco property: Umbraco.Web.WebServices.UmbracoHttpHandler, Umbraco.Web.WebServices.UmbracoWebService
UmbracoHelper will expose all content in the form of IPublishedContent. To get a reference to the currently executing content item from the UmbracoHelper, use UmbracoHelper.AssignedContentItem.
The samples below demonstrate using UmbracoHelper in Razor. Aside from the @ syntax, usage is the same inside controllers or UserControls.
Given a node ID, returns a IPublishedContent
@{
var page = Umbraco.Content(Guid.Parse("ca4249ed-2b23-4337-b522-63cabe5587d1"));
}
<h3>@(page.Value<string>("propertyAlias"))
</h3>
@foreach (var child in page.Children) {
<a href="@child.Url">@child.Name</a>
}Returns a collection of IPublishedContent objects from the Content tree.
// Get the children of the first content item found in the root
@foreach (var child in Umbraco.ContentAtRoot().First().Children) {
<a href="@child.Url">@child.Name</a>
}Queries the cache for content matching a given XPath query and returns a collection of IPublishedContent objects.
@{
var newsArticles = Umbraco.ContentAtXPath("//newsArticle");
var bodyText = newsArticles.First().Value("bodyText");
}Queries the cache for content matching a given XPath query and returns the first match as an IPublishedContent object.
@{
var newsArticle = Umbraco.ContentSingleAtXPath("//newsArticle");
var bodyText = newsArticle.Value("bodyText");
}Given a node ID, returns an IPublishedContent Media entity
@{
var media = Umbraco.Media(Guid.Parse("ca4249ed-2b23-4337-b522-63cabe5587d1"));
var image = media.Url;
var height = media.Value<int>("umbracoHeight");
}Returns a collection of IPublishedContent objects from the Media tree.
@foreach (var child in Umbraco.MediaAtRoot()) {
<img src="@child.Url" />
}Gets a lazily loaded reference to the tag context to allow you to work with tags
@{
var tagQuery = Umbraco.TagQuery;
}Get a collection of tags used by content items on the site, you can optionally pass in a group name to only list tags belonging to a specific tag group
@{
var allTags = Umbraco.TagQuery.GetAllContentTags();
var newsTags = Umbraco.TagQuery.GetAllContentTags("news");
}Get a collection of tags used by media items on the site, you can optionally pass in a group name to only list tags belonging to a specific tag group
@{
var allTags = Umbraco.TagQuery.GetAllMediaTags();
var newsTags = Umbraco.TagQuery.GetAllMediaTags("news");
}Get a collection of tags used by members on the site, you can optionally pass in a group name to only list tags belonging to a specific tag group
@{
var allTags = Umbraco.TagQuery.GetAllMemberTags();
var newsTags = Umbraco.TagQuery.GetAllMemberTags("news");
}Get a collection of tags used on the site, you can optionally pass in a group name to only list tags belonging to a specific tag group
@{
var allTags = Umbraco.TagQuery.GetAllTags();
var newsTags = Umbraco.TagQuery.GetAllTags("news");
}Get a collection of IPublishedContent by tag, and you can optionally filter by tag group as well
@{
var taggedContent = Umbraco.TagQuery.GetContentByTag("News");
}Get a collection of IPublishedContent by tag group
@{
var taggedContent = Umbraco.TagQuery.GetContentByTagGroup("BlogTags");
}Get a collection of Media by tag, and you can optionally filter by tag group as well
@{
var taggedContent = Umbraco.TagQuery.GetMediaByTag("BlogTags");
}Get a collection of Media by tag group
@{
var taggedContent = Umbraco.TagQuery.GetMediaByTagGroup("BlogTags");
}Get a collection of tags by entity id (queries content, media and members), and you can optionally filter by tag group as well
@{
var taggedContent = Umbraco.TagQuery.GetTagsForEntity(1234);
}Get a collection of tags assigned to a property of an entity (queries content, media and members), and you can optionally filter by tag group as well
@{
var taggedContent = Umbraco.TagQuery.GetTagsForProperty(1234,"propertyTypeAlias");
}Given a node ID, returns a single IPublishedContent Member
@{
var member = Umbraco.MembershipHelper.GetById(Guid.Parse("1f46e266-9acb-4f5b-afdb-5e26c23c56e3"));
var email = member.Value<string>("email");
}Returns a Boolean on whether there is currently a member profile
@if(Umbraco.MemberIsLoggedOn()) {
<h1>Welcome!</h1>
}Returns a Boolean on whether the currently logged in member has access to the page given its Umbraco path.
@if (Umbraco.MemberHasAccess(Model.Path))
{
<h1>Welcome!</h1>
}Returns a Boolean on whether a page with a given Umbraco path has public access restrictions set.
@foreach (var child in Model.Children) {
<h2>@child.Name</h2>
if(Umbraco.MembershipHelper.IsProtected(child.Path)){
<blink>Members only</blink>
}
}Returns a dictionary value(string) for the key specified.
<p>@Umbraco.GetDictionaryValue("createdOn"): @Model.CreateDate</p>Alternatively, you can also specify an altText which will be returned if the dictionary value is empty.
<p>@Umbraco.GetDictionaryValue("createdOn", "Date Created"): @Model.CreateDate</p>By default, Umbraco searches it's 'External' search index for any published content matching the provided search term.
@{
<ul>
@foreach (var result in Umbraco.ContentQuery.Search("ipsum"))
{
<li><a href="@result.Content.Url">@result.Content.Name</a></li>
}
</ul>
}Specifying the number of records 'to skip', and the number of records 'to take' is more performant when there are lots of matching search results and there is a requirement to implement paging.
@{
var search = Umbraco.ContentQuery.Search("ipsum", 5, 10, out long totalRecords);
<ul>
<li>
Total results: @totalRecords
<ul>
@foreach (var result in search)
{
<li><a href="@result.Content.Url">@result.Content.Name</a></li>
}
</ul>
</li>
</ul>
}For more complex searching you can construct an Examine QueryExecutor. In the example the search will execute against content of type "blogPost" only. Further information on using Examine
@{
if (!ExamineManager.Instance.TryGetIndex(Constants.UmbracoIndexes.ExternalIndexName, out IIndex index))
{
throw new InvalidOperationException($"No index found by name{ Constants.UmbracoIndexes.ExternalIndexName }");
}
var term = "ipsum";
var query = index.GetSearcher().CreateQuery(IndexTypes.Content);
var queryExecutor = query.NodeTypeAlias("blogPost").And().ManagedQuery(term);
foreach (var result in Umbraco.ContentQuery.Search(queryExecutor))
{
{
<li><a href="@result.Content.Url">@result.Content.Name</a></li>
}
}
}Renders a macro in the current page content, given the macro's alias, and parameters required by the macro.
@Umbraco.RenderMacro("navigation", new {root="1083", header="Hello"})Renders a template, as if a page with the given contentId was requested, optionally with an alternative template ID passed in.
@Umbraco.RenderTemplate(1234)