Extending the back office with custom sections

let's add a custom section. this will introduce a new top menu item for the custom section and also a new left menu to the backoffice.

first we need a place to put our javascript, custom references for javascript and css are put in the includes.cshtml file found at puckweb/Areas/puck/Views/Shared/includes.cshtml.

here's the javascript for the custom section:

<script>
    var puckCustomSections = [
        {
            title: "custom section",
            id:"customSection",
            hash: "#customSection",
            iconClasses:"fas fa-cog",
            leftItems: [
                {
                    title: "custom page",
                    hash: "#customSection?page=customPage",
                    iconClasses:"fas fa-cog"
                }
            ]
        }
    ];
    var puckCustomHashHandler = function (hash) {
        if (/^#\/?customSection/.test(hash)) {
            showCustomSection("customSection");
            var valueDictionary = getHashValues(hash);
            var page = valueDictionary["page"];
            if (page != undefined) {
                //load custom page
                
            }
            
        }
    }
</script>

as you can see, you specify your sections in the puckCustomSections global javascript variable. the above code will add a menu item to the top menu of the backoffice called "custom section" and will add a left menu with one item called "custom page".

the second part of this setup is another global variable puckCustomHashHandler which is a function that will handle the hash change event for your custom sections. the implementation above checks the hash is that of the current section then calls showCustomSection passing in the id for the custom section. then the hash variables are returned by calling getHashValues, so if you have a hash like #customSection?page=customPage&id=20, and you called var values = getHashValues(hash) then you would be able to access the page and id values by doing values["id"] and values["page"].

from here you're free to modify the page and load your custom pages. the variable cright is available as a jquery element to add your custom page html to. so cright.html("<div>this is my custom page</div>"); would add some html to the right area of the backoffice, where the edit screen is rendered.

if you need to display messages, you can call msg(true,"content updated") for example, to show a success message. you pass in false as the first argument for error messages and undefined for neutral notifications and messages

icons

puck uses FontAwesome for icons so check this page for the available icons you can use and their icon classes.

you can also add icons to the content tree by Type. to do so, add the following javascript variable in your includes.cshtml file:

<script>
       var treeIconClasses = { "Homepage": "fas fa-file" };
</script>

the content tree will then pick up these classes for any tree items of Type Homepage.

note

don't use global variables and global functions in the custom javascript that you put/reference in includes.cshtml. they may conflict with pucks global state.