The known and unknown of Include, IncludeOn, Exclude and ExcludeOn
These four settings have always been and are little headache for me and today I took some time trying to learn more about them.
Basically they work like this:
Include
A type array of typed content to specify which content types are available under a content instance of the type with the attribute.
Exclude
A type array of typed content to specify which content types are not available under a content instance of the type with the attribute.
IncludeOn
States that the content with this attribute is available under the typed content in the type array.
ExcludeOn
States that the content with this attribute is not available under any of the typed content in the type array.
This is pretty straight forward and the most importing part is to realize that the Include is not just including the defined types, it is also excluding all other things.
But the funny/hard thing to learn is what happens when you combine them together, which property is more important than the other.
To figure that out I took a normal Alloy site and changed the settings for StartPage and ProductPage.
[AvailableContentTypes(
Availability.Specific,
Include = new[] { typeof(SearchPage) },
ExcludeOn = new[] { typeof(ProductPage) })]
public class StartPage : SitePageData
[AvailableContentTypes(
Availability = Availability.Specific,
Include = new[] { typeof(StartPage), typeof(SearchPage) },
IncludeOn = new[] { typeof(StartPage) })]
public class ProductPage : StandardPage, IHasRelatedContent
That gave me this look inside admin:
This shows me that IncludeOn and ExcludeOn are prioritized over Include and Exclude, since even though I say that I should include StartPage on ProductPage, it is not included and even though I do not define ProductPage to be included below StartPage it is included on it.
Then I wounded what would happen if I say that the only thing that should be able to be created below ProductPage should be StartPage and keep saying to StartPage that it should be ExcludedOn Productpage. So I changed the code for ProductPage so it looks like this:
[AvailableContentTypes(
Availability = Availability.Specific,
Include = new[] { typeof(StartPage) },
IncludeOn = new[] { typeof(StartPage) })]
public class ProductPage : StandardPage, IHasRelatedContent
I thought that I would end up not being able to create anything at all below ProductPage but to my surprise this is what the result was:
Somehow I ended up with being able to create everything but StartPage and that was not I was hoping for and for me it feels like a bug, what does you think?
Sounds like a space to dig deeper :)
Had a quick look at this and would say that there is an issue here if the combined Include/IncludeOn and Exclude/ExcludeOn sets are matching up. The result will instead be the same as if only the exclude attributes were applied.
We figured out that if you use the Availability.Specific option you need to include at least one page in the Include clause
for the IncludeOn option to work for any sub pages you want to include on the page at a later point.
Hopefully this gets some love at some point, right now it is kind of confusing to use.
This is now fixed in EPiServer.CMS.Core 9.3.2
I’ve found discussion about related issue.
Why there is Availabilty property?
I see there should be Include automatically excluding all others, Exclude automatically including all others, IncludeOn automatically excluding content type (CT) on all other CTs and ExcludeOn automatically including CT on all other CTs.
Why there is need to tell the attribute what is my intention specifically?
I think about properties like ExclusivelyIncluded, ExclusivelyExcluded, ExclusivelyIncludedOn, ExclusivelyExcludedOn.
The answer for question of prioritizing one over other in non-on and on ones strife lays in design intentions, i.e. to be able to overwrite class behavior without option to change it or not to be able to do that, I think so.
I found this quite a hodgepodge.