Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Overview of multiple ways of querying, filtering, and searching published content for use on your website.
Umbraco stores identifiers in UDI format for most Umbraco object types. This identifier stores all of the metadata required to retrieve an Umbraco object and is parse-able within text. Example: umb://document/4fed18d8c5e34d5e88cfff3a5b457bf2
. UDI's can be used in many of the querying APIs.
IPublishedContent
is strongly typed model for content, media and members that is used to render content in your views for your website.
UmbracoHelper is the unified way to work with published content/media on your website. Whether you are using MVC or WebForms you will be able to use UmbracoHelper to query/traverse Umbraco published data.
IMemberManager
is an user manager interface for accessing member data in the form of MemberIdentityUser
and converting it to IPublishedContent
.
The IPublishedContentQuery
interface contains query methods for accessing strongly typed content in services etc.
The ITagQuery
interface allows to work with tags in Umbraco.
The UmbracoContext is a simplified way to work with the current request on your website.
Querying in views with IPublishedContentQuery in Umbraco
The IPublishedContentQuery
interface contains different query methods for accessing strongly typed content in services etc.
In order to inject the IPublishedContentQuery
into your services, you must add a using statement for Umbraco.Cms.Core
and inject the service using the constructor.
Now you can access the IPublishedContentQuery
through _publishedContentQuery
By default, IPublishedContentQuery
will search on Umbraco's 'External' search index for any published content matching the provided search term.
Specifying the number of records 'to skip' and the number of records 'to take' improves performance with many matching search results. This approach is beneficial when there is a requirement to implement paging.
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
Using the IMemberManager
IMemberManager
has a variety of methods that are useful for managing members in controllers and views. In this article, we'll have a look at how some of these can be used.
For the full list of methods, see the IMemberManager Interface API Documentation.
There are different ways to reference IMemberManager
:
The recommended way is to create a Controller or Service and inject IMemberManager
in the constructor:
Alternatively, IMemberManager
can be injected directly into a template:
It is advisable to implement Controllers to manage this kind of view logic.
IMemberManager
has multiple ways to find members.
Finds a member by their ID
If we want to find a member by Udi
or Guid
we need to inject IIdKeyMap
service:
Udi
Guid
Finds a member by their email.
Finds a member by their login name.
The IMemberManager
methods returns members as MemberIdentityUser
.
Since Members Types are defined like Content Types in Umbraco, members can hold any number of properties. To access these properties, it can be beneficial to convert the member into an IPublishedContent
instance.
This is done using AsPublishedMember(MemberIdentityUser)
::
Returns the currently logged in member if there is one, else returns null value.
Returns the ID of a member.
Checks if the current request contains a logged-in member.
Checks if the current member is authorized as specific member types, member groups or concrete members.
For instance, you can use this method to verify if the current logged in member is part of a specific group:
Returns a Task<bool>
specifying if the content with a given Umbraco path has public access restrictions set.
Returns a Task<bool>
specifying if the currently logged in member has access to the content given its Umbraco path.
Validates that specific member credentials are correct (without performing a log-in).
Working with tags in Umbraco
The ITagQuery
interface is your primary way to work with tags in Umbraco, the interface allows you to get the various tags like content tags and media tags, as well as getting content by tag, for instance getting all content nodes with the "Umbraco" tag.
If you're using it in Views or Partial views you can inject ITagQuery
using the @inject
keyword, for example
After this you can use _tagQuery
to access the ITagQuery
.
If you're using it in controllers, you can inject it into the constructor like so:
The example below uses UmbracoApiController which is obsolete in Umbraco 14 and will be removed in Umbraco 15.
ITagQuery
is a scoped service, meaning that it should only be injected into scoped or transient services, for more information see the official Microsoft Documentation
All examples are from a view using the injection shown above, but working with tags in controllers will be the same.
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
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
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
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
Get a collection of IPublishedContent by tag, and you can optionally filter by tag group as well
Get a collection of IPublishedContent by tag group
Get a collection of Media by tag, and you can optionally filter by tag group as well
Get a collection of Media by tag group
Get a collection of tags by entity id (queries content, media and members), and you can optionally filter by tag group as well
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
Umbraco stores identifiers in UDI format for most Umbraco object types. This identifier stores all of the metadata required to retrieve an Umbraco object and is parse-able within text. Example: umb://document/4fed18d8c5e34d5e88cfff3a5b457bf2
. UDI's can be used in many of the querying APIs.
UDI is currently not an acronym for something. There is no official definition of what it's short for. Therefore it's called UDI
An Umbraco UDI consists of three parts: the scheme, the type and a GUID Identifier. For example: umb://document/4fed18d8c5e34d5e88cfff3a5b457bf2
.
Breaking it down:
The scheme is umb://
- this is always the same and makes it identifiable as an Umbraco UDI
The type is document
- so in this is an Umbraco node, but it could also be media
, member
, etc.
The GUID Id is 4fed18d8c5e34d5e88cfff3a5b457bf2
- this is a GUID (dashes removed) which is randomly generated when the item is being created
You can use UDIs in some of the Querying and Management/Service APIs.
There are 2 types of UDIs:
Using the Umbraco Helper
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.
If you are using Views you can reference UmbracoHelper with the syntax: @Umbraco
If you need an UmbracoHelper
in your own controllers, you need to inject an instance.
Example of getting UmbracoHelper
in a controller:
If you need to use an UmbracoHelper in a service with a singleton lifetime you would instead need to make use of the IUmbracoHelperAccessor interface to obtain a temporary reference to an instance.
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. Working with the UmbracoHelper
will be the same in controllers, except for the fact that you must resolve it with IUmbracoHelperAccessor
like shown above.
Given a node ID, returns a IPublishedContent
Returns a collection of IPublishedContent
objects from the Content tree.
Given a node ID, returns an IPublishedContent
Media entity
Returns a collection of IPublishedContent
objects from the Media tree.
Returns a dictionary value(string
) for the key specified.
Alternatively, you can also specify an altText
which will be returned if the dictionary value is empty.
The UmbracoContext is a helpful service provided on each request to the website
The UmbracoContext is the simplified way to work with the current request on your website.
You can use UmbracoContext to access the content and media cache. Other useful properties are the original and cleaned URLs of the current request. You can also check if the current request is running in "preview" mode.
If you are using Views you can reference the UmbracoContext with the syntax: @UmbracoContext
If you need an UmbracoContext
in your own controllers, you need to inject an IUmbracoContextAccessor
.
The following is an example of how to get access to the UmbracoContext
in a controller:
The example below uses UmbracoApiController which is obsolete in Umbraco 14 and will be removed in Umbraco 15.
IPublishedContent
is a strongly typed model for content, media and members and is used to render content in your views for your website.
To access the current page in your templates, copy-paste the below Razor code.
Listing and explanation of IPublishedContent properties and standard helpers for Content and Media.
Methods for IPublishedContent collections and filtering.
A library of extension methods to simplify working with IPublishedContent in collections to modify your HTML output. Examples of using IsHelpers
could be injecting CSS classes for alternating rows or to modify margins.
UmbracoHelper is registered with a scoped lifetime (see for more information), as a service scope is created for each request you can resolve an instance directly in a controller.
Previously the UmbracoHelper
could be used to work with tags, this has been moved out of UmbracoHelper
and is now available from ITagQuery
which you can read more about in the .
Previously the UmbracoHelper
could be used to work with members, this has ben moved out of UmbracoHelper
and is now available from IMemberManager
, see for more information
Previously the UmbracoHelper
could be used to run queries on your content, this has been moved out of UmbracoHelper
and is now available from IPublishedContentQuery
, see for more information.
UmbracoContext is registered with a scoped lifetime. See the for more information. A service scope is created for each request, which means you can resolve an instance directly in a controller.
All collections of IPublishedContent
are IEnumerable<IPublishedContent>
. This means that all C# LINQ statements can be used to filter and query the collections.
Returns a collection of child items available in the current culture, below the current content item.
Returns a collection of child items for all cultures, below the current content item, regardless of whether they are available for the current culture.
Returns a collection of child items available in the specified culture with a default of the current one, below the current content item.
Returns all ancestors of the current page (parent page, grandparent and so on)
Returns the first ancestor of the current page
Returns a collection of all ancestors of the current page (parent page, grandparent and so on), and the current page itself
Returns all descendants of the current page (children, grandchildren etc)
Returns all descendants of the current page (children, grandchildren etc), and the current page itself
Filters a collection of content by content type alias
Filtering and Ordering are done with LINQ.
Some examples:
Groups collection by content type alias
Return only the number of items for a collection specified by the integer value.
Return items from the collection after skipping the specified number of items.
You can combine Skip and Take when using for paging operations
Returns the number of items in the collection
Returns a boolean True/False value determined by whether there are any items in the collection
Some filtering and routing behaviour is dependent upon a set of special naming conventions for certain properties. See also: Routing Property Conventions
If you create a checkbox property on a document type with an alias umbracoNaviHide
then the value of this property is used by the IsVisible()
extension method when filtering.
Use case: When displaying a navigation menu for a section of the site, following this convention gives editors the option to 'hide' certain pages from appearing in the section navigation. (hence the unusual umbracoNaviHide property alias!)
The IsHelper methods are a set of extension methods for IPublishedContent to help perform quick conditional queries against IPublishedContent nodes in a collection.
IsHelper methods are ternary operators, however they work a little nicer since they can be embedded in properties. They are also quicker to write because fewer brackets are needed for Razor to understand them.
An IsHelper can be invoked as a method of an IPublishedContent
.
Test whether the content is of a content type composed of the given alias.
Test whether the specified templateId
is an allowed template for the current node.
Test whether the specified templateAlias
is an allowed template for the current node.
By default the above template methods are disabled. To enable them, make sure to modify your appsettings.json to include the following JSON config keys inside Umbraco.CMS section:
Test if the current node is equal (by Id) to another node.
Test if the current node is not equal (by Id) to another node.
Test if the current node is a descendant of another node.
Test if the current node is the same as or a descendant of another node.
Test if the current node is an ancestor of another node.
Test if the current node is the same as or an ancestor of another node.
Built-in properties, which exists on all content objects by default
Common Examples
Returns the unique Id for the current content item
Returns the Name of the current content item in the current culture
Returns the Name of the current content item in the specified culture, null falls back to the current culture
Returns a strongly typed 'PublishedContentType' object representing the content type the IPublishedContent item is based on, that gives access to the alias
Returns a culture from a configured domain in the content tree.
Returns the parent content item
Returns a comma delimited string of Node Ids that represent the path of content items back to root.
Returns the Level (depth) this content item is in its tree path
Returns the id of the default Template object used with this content item.
There are extension methods to retrieve template alias (Model.GetTemplateAlias())
Returns the index the page is on, compared to its siblings
Returns the Url to the page.
Example: Getting a Danish Url for a site where a Danish language has been set up.
Example: Getting an Absolute Danish Url for a site where a Danish language has been set up.
Returns the Url encoded name of the page (slug) of the current culture
Returns the Url encoded name of the page (slug) of the specified culture
Returns the id of the Umbraco backoffice user that performed the last update operation on the content item.
Returns the name of the Umbraco backoffice user that initially created the content item.
Returns the id of the Umbraco backoffice user that initially created the content item
Returns the name of the Umbraco backoffice user that initially created the content item.
Returns the DateTime the page was created
Returns the DateTime the page was modified
All content and media items contain a reference to all the data defined by their Document Type. Custom property access is achieved using variations of the method: Value
Returns the property value for the specified property alias
The type returned of this property value is object
. This is fine in most cases since when using the above syntax, Razor will automatically execute a ToString()
on the result value.
See Model.Value<T>(string)
for how to return a strongly typed object for the property
Returns the property value for the specified property alias converted to 'T' - the requested output type of the property value.
For example, to return the string
result of "siteName":
If the current content item doesn't have the requested value, use an alternative 'fallback' value in its place.
Each of the examples below make use of an injected PublishedValueFallback. This is achieved by adding the following at the top of your Razor file:
This parameter is optional, but can make unit testing easier.
If a content page has a 'title' property, to fallback to use the 'Name' of the content item if the 'title' is not populated. Set the Fallback type to be Fallback.ToDefaultValue, and set the DefaultValue accordingly:
or to a specific value
Look for a property value on the current page. If it doesn't exist look for the property value on the parent page. Then the parent's parent page and so on. This approach allows specifying 'global property values' all the way up the content tree. These values can be overridden in different sections or individual pages.
If working with variants - fallback to a different language value - if perhaps the value hasn't been populated yet for the current language:
Use Fallback.To() to 'combine' Fallback options.
The following would first look for a 'title' property on all ancestors, before defaulting to the current page's name:
There are a few helpful methods to help check if a property exists, has a value or is null.
Returns a boolean value representing if the IPublishedContent has a property with the specified alias.
Returns a boolean value representing if the IPublishedContent property has had a value set.
It's possible to use 'Fallbacks' with HasValue: