best practices integrating custom themes with articulate in umbraco 12 core - Using Umbraco and getting started

Paul Griffiths 370 posts 1021 karma points

Feb 16, 2024 @ 10:21

Best Practices Integrating Custom Themes with Articulate in Umbraco 12 (core)

Hello,

Last night, I delved into the latest release of Umbraco 12, and, the installation process was impressively smooth and swift. Following the setup, I installed the Articulate starter kit package, aiming to integrate it with my theme. However, I've hit a little snag - applying styles to my own custom theme. I appreciate that there is documentation for Articulate e.g. https://github.com/Shazwazza/Articulate/wiki/Creating-a-theme but I have a question about this I can't find the answers for.

From the back office, I have copied the existing 'vapor' theme and it has created the following in my solution

enter image description here

In the cloned master file there is the following reference

<link href="articulate-vapor-css" rel="stylesheet" />

I have attempted to update this to the following but it breaks the link

<link href="/Views/ArticulateThemes/prgriffithsblog/Assets/css/screen.css" rel="stylesheet" />

My experience with .NET (Core) development is somewhat limited, but I understand that static resources are typically housed in the wwwroot folder. However, I'm a little confused about whether the files Articulate clones must reside in the generated location? For example, if i move them into the App_Pluggins directory alongside the other themes then views can't be located. This makes me think they need to be where they are. Where is 'articulate-vapor-css', i only see normalize and screen css files in the Articulate theme locations.

I'm sure the answer is probably straightforward forward but I would greatly appreciate some clarification on the setup process in .NET Core if anyone can advise, please.

Thank you

Copy Link

Garðar Þorsteinsson 119 posts 565 karma points

Feb 16, 2024 @ 12:44

Hi Paul,

You have copied the theme folder to a wrong place.

You should have Assets next to Views and not inside it.

Also you have Views inside of Views.

the structure should be:

/Assets/Theme/css /Assets/Theme/js /Assets/Theme/fonts

and

/Views/Partials/Theme/.....

But all Templates need to be in the root of Views.

/Views/Master.cshtml

And if you want to have multiple themes I would prefix the names of the templates like so

/Views/theme1Master.cshtml /Views/theme2Master.cshtml

Copy Link

Paul Griffiths 370 posts 1021 karma points

Feb 16, 2024 @ 17:40

Hi Garðar,

Thank you for responding.

I never manually copied the theme folder I wanted, I used the copy feature from inside the Settings > Articulate tab in the back office

enter image description here

The result of this operation is

enter image description here

Are you saying that this auto-creation is wrong ?

Thanks Paul

Copy Link

Shannon Deminick 1526 posts 5272 karma points MVP 3x

Feb 22, 2024 @ 00:52

Yes, please use the feature in the back office for copying themes. Articulate has it's own file system providers to handle various things. That said, you are correct with this:

I understand that static resources are typically housed in the wwwroot folder.

You should use assets within your www folder and store them wherever you want for your theme. The current theme copying doesn't cater for this - it could if you wished to contribute to Articulate, or contribute to the docs (since they are very outdated with the new version).

Please leave the Articulate views where they are, they are there for a reason:

~Views/ArticulateThemes/[Theme]

Copy Link

Paul Griffiths 370 posts 1021 karma points

Feb 22, 2024 @ 21:45

Hey Shannon,

Thank you for your reply.

Before receiving your response, I took the initiative to move the theme styles into the wwwroot directory, and I'm pleased to report that it worked as expected. However, I want to ensure that my approach aligns with best practices so thankful for your input.

Having delved into the documentation and resources available for the Articulate Starter Kit, I understand that adhering to certain conventions, such as the view structure, is key to preventing impacting the intended functionality.

I am keen to learn more about Articulate and am open to experimenting further and contributing to the existing documentation. However, this might require me to seek your expertise for accurate information, especially when it is not readily available. I guess that's what a PR is for :)

Thanks

Paul

Copy Link

Paul Griffiths 370 posts 1021 karma points

Feb 28, 2024 @ 12:33

Hi @Shannon,

I've been exploring the Articulate package functionality and concepts and have some questions if you don't mind. Your insights would be greatly appreciated whenever you have the time, of course. I appreciate this is a voluntary side project.

To try and set the scene and aid your understanding of what I have:

Site Structure and Setup: Within the Back office, I've structured the site using a custom Homepage doc type as the site root node and the Articulate 'Blog' node is positioned as a child node under the Homepage I've introduced. From what I have read i think this is perfectly acceptable...

enter image description here

Site Architecture: I'm aiming to follow the structure outlined in this resource. Specifically, I'm utilising route-hijacking to associate page requests with custom controllers. Currently, I have a HomePage controller set up as follows:

public class HomePageController : RenderController
{
    private IPublishedValueFallback _publishedValueFallback;
    public HomePageController(
            ILogger<HomePageController> logger,
            ICompositeViewEngine compositeViewEngine,
            IUmbracoContextAccessor umbracoContextAccessor,
            IPublishedValueFallback publishedValueFallback
         )
        : base(logger, compositeViewEngine, umbracoContextAccessor)
    {
        _publishedValueFallback = publishedValueFallback;
    }


public override IActionResult Index()
{
    var home = new HomePage(CurrentPage, _publishedValueFallback);
    var viewModel = new ComposedPageViewModel&lt;HomePage, HomePageViewModel&gt;
    {
        Page = home,
        ViewModel = new HomePageViewModel
        {
           //vm props
        }
    };


    return View("~/Views/HomePage.cshtml", viewModel);
}


}

View Rendering:

The view associated with the HomePageController renders the necessary components using a ViewModel. A you can see it references the a custom layout file that i have defined. Here's a snippet of the view:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ComposedPageViewModel<HomePage, HomePageViewModel>>

@{
    Layout = "_Layout.cshtml";
}

<div class="main-wrapper">
    // Rendering properties defined on the homepage doctype and ViewModel
    <h2>@Model.Page.Heading</h2>
    <p>@Model.Page.Subheading</p>
</div>

Layout Structure:

Finally, the site layout is organised in a basic structure with a header, footer, and main content areas, it is not strongly typed, as depicted in the snippet below:

<!DOCTYPE html>
<html lang="en">
<head>
    @await Component.InvokeAsync("MetaData")
    // Head section contents
</head>

<body>
    @await Component.InvokeAsync("Header")

    <div class="main-wrapper">
        @RenderBody()
    </div>

    @await Component.InvokeAsync("Footer")
</body>
</html>

I aim to unify the layout for the Articulate nodes with my custom pages, streamlining management from a single location. Although I'm uncertain if this approach is advisable, I've made adjustments to following Articulate templates, directing them to use my _Layout.cshtml file. Consequently, the Articulate master.cshtml file is no longer referenced

Author
List
Post
Tags

This seemingly works and the razor files mentioned above inherit my layout site structure and styles (see the Articulate blog page below accessible from https://localhost:44342/blog/ )

enter image description here

However, there is an issue with tags and categories which yields the following when browsing https://localhost:44342/blog/tags/Cafe

enter image description here

Is this a consequence of Articulate 'Blog' no longer being the 'Root Node' ? From reading your response in https://our.umbraco.com/packages/starter-kits/articulate/discussions/79901-how-to-get-tags-and-categories-pages-working I understand that Tags and Category routes are not Umbraco nodes in the tree and these are 'virtual nodes' created at startup. I have cloned down the Articulate project and trying to understand the logic but its not quite making sense, are you able to provide any further insights, please?

Do i need to do something with hostnames ?

enter image description here

Finally, is there anything that I have mentioned above that sets off the alarm bells e.g. should I be diverting the Articulate templates to not reference the master.cshtml that I've copied as part of my custom theme? I want to follow best practices and stick to conventions where possible.

Flag this post as spam?

Best Practices Integrating Custom Themes with Articulate in Umbraco 12 (core)