ASP.NET Core MVC / Razor Pages: Layout Hooks
ABP theming system places the page layout into the theme NuGet packages. That means the final application doesn't include a Layout.cshtml
, so you can't directly change the layout code to customize it.
You copy the theme code into your solution. In this case you are completely free to customize it. However, then you won't be able to get automatic updates of the theme (by upgrading the theme NuGet package).
ABP provides different ways of customizing the UI.
The Layout Hook System allows you to add code at some specific parts of the layout. All layouts of all themes should implement these hooks. Finally, you can add a view component into a hook point.
Example: Add Google Analytics Script
Assume that you need to add the Google Analytics script to the layout (that will be available for all the pages). First, create a view component in your project:
NotificationViewComponent.cs
public class GoogleAnalyticsViewComponent : AbpViewComponent
{
public IViewComponentResult Invoke()
{
return View("/Pages/Shared/Components/GoogleAnalytics/Default.cshtml");
}
}
Default.cshtml
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-xxxxxx-1', 'auto');
ga('send', 'pageview');
</script>
Change UA-xxxxxx-1
with your own code.
You can then add this component to any of the hook points in the ConfigureServices
of your module:
Configure<AbpLayoutHookOptions>(options =>
{
options.Add(
LayoutHooks.Head.Last, //The hook name
typeof(GoogleAnalyticsViewComponent) //The component to add
);
});
Now, the GA code will be inserted in the head
of the page as the last item.
Specifying the Layout
The configuration above adds the GoogleAnalyticsViewComponent
to all layouts. You may want to only add to a specific layout:
Configure<AbpLayoutHookOptions>(options =>
{
options.Add(
LayoutHooks.Head.Last,
typeof(GoogleAnalyticsViewComponent),
layout: StandardLayouts.Application //Set the layout to add
);
});
See the Layouts section below to learn more about the layout system.
Layout Hook Points
There are some pre-defined layout hook points. The LayoutHooks.Head.Last
used above was one of them. The standard hook points are;
LayoutHooks.Head.First
: Used to add a component as the first item in the HTML head tag.LayoutHooks.Head.Last
: Used to add a component as the last item in the HTML head tag.LayoutHooks.Body.First
: Used to add a component as the first item in the HTML body tag.LayoutHooks.Body.Last
: Used to add a component as the last item in the HTML body tag.LayoutHooks.PageContent.First
: Used to add a component just before the page content (the@RenderBody()
in the layout).LayoutHooks.PageContent.Last
: Used to add a component just after the page content (the@RenderBody()
in the layout).
You (or the modules you are using) can add multiple items to the same hook point. All of them will be added to the layout by the order they were added.
Layouts
Layout system allows themes to define standard, named layouts and allows any page to select a proper layout for its purpose. There are three pre-defined layouts:
- "Application": The main (and the default) layout for an application. It typically contains header, menu (sidebar), footer, toolbar... etc.
- "Account": This layout is used by login, register and other similar pages. It is used for the pages under the
/Pages/Account
folder by default. - "Empty": Empty and minimal layout.
These names are defined in the StandardLayouts
class as constants. You can definitely create your own layouts, but these are the standard layout names and implemented by all the themes out of the box.
Layout Location
You can find the layout files here for the basic theme. You can take them as references to build your own layouts or you can override them if necessary.