diff --git a/README.md b/README.md index 61c8503..d2a7f23 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,25 @@ UmbNav adds a drag and drop menu builder to the Umbraco V8 backoffice. ## Getting started -This package is supported on Umbraco 8.7+. +This package is supported on Umbraco 8.7+ and Umbraco V9.0+ + +### Features + +- Set maximum child levels +- Hide menu items where `umbracoNaviHide` is true +- Auto expand the backoffice menu tree on hover +- Set the delay of the auto expand on hover (in ms) +- Add `noopener` to external links by clicking a checkbox +- Add `noreferrer` to external links by clicking a checkbox +- Auto add child nodes when rendering on the front end +- All menu items to be shown / hidden depending on member authentication status +- Add custom CSS classes to each menu item in the backoffice +- Display the property editor as full width in the back office (Hide the label) +- Enter an image url, id, guid or udi for each menu item this will be converted to the relevant url on render ### Installation -UmbNav is available from [Our Umbraco](https://our.umbraco.com/packages/backoffice-extensions/umbnav), [NuGet](https://www.nuget.org/packages/Our.Umbraco.UmbNav.Web), or as a manual download directly from GitHub. +UmbNav is available from [Our Umbraco (V8 only)](https://our.umbraco.com/packages/backoffice-extensions/umbnav), [NuGet](https://www.nuget.org/packages/Our.Umbraco.UmbNav.Web), or as a manual download directly from GitHub. #### NuGet package repository To [install UI from NuGet](https://www.nuget.org/packages/Our.Umbraco.UmbNav.Web), run the following command in your instance of Visual Studio. @@ -24,21 +38,31 @@ To [install Core from NuGet](https://www.nuget.org/packages/Our.Umbraco.UmbNav.C PM> Install-Package Our.Umbraco.UmbNav.Core -To [install api from NuGet](https://www.nuget.org/packages/Our.Umbraco.UmbNav.Api), run the following command in your instance of Visual Studio. +To [install API from NuGet](https://www.nuget.org/packages/Our.Umbraco.UmbNav.Api), run the following command in your instance of Visual Studio. PM> Install-Package Our.Umbraco.UmbNav.Api ## Umbraco Cloud Supported -UmbNav fully supports Umbraco Cloud including the content synchroniser,it has been fully tested transferring and restoring between environments. +UmbNav fully supports Umbraco Cloud including the content synchroniser, it has been fully tested transferring and restoring between environments. -### Integration +### Documentation -UmbNav is designed to be as clean and simple for developers as it is for content editors. +After installing the package, you will have a new property editor called UmbNav in the Umbraco backoffice, typically this would get added to your sites "Site Settings" or "Home" node. -### Documentation +Check out the integration guide [integration guide](docs/integration-guide.md) to learn how to embed the package in your site. + +### Screenshots + +![](https://raw.githubusercontent.com/AaronSadlerUK/Our.Umbraco.UmbNav/develop/Screenshots/UmbNav.1.jpeg) + +![](https://raw.githubusercontent.com/AaronSadlerUK/Our.Umbraco.UmbNav/develop/Screenshots/UmbNav.2.jpeg) + +![](https://raw.githubusercontent.com/AaronSadlerUK/Our.Umbraco.UmbNav/develop/Screenshots/UmbNav.3.jpeg) + +![](https://raw.githubusercontent.com/AaronSadlerUK/Our.Umbraco.UmbNav/develop/Screenshots/UmbNav.4.jpeg) -Coming soon! +![](https://raw.githubusercontent.com/AaronSadlerUK/Our.Umbraco.UmbNav/develop/Screenshots/UmbNav.5.jpeg) ### Contribution guidelines @@ -54,4 +78,4 @@ Copyright © 2021 [UmbHost Limited](https://umbhost.net), and other contribu Licensed under the MIT License. -As per the spirit of the MIT Licence, feel free to fork and do what you wish with thr source code, all I ask is that if you find a bug or add a feature to PR this repository. +As per the spirit of the MIT Licence, feel free to fork and do what you wish with the source code, all I ask is that if you find a bug or add a feature please create a to PR this repository. diff --git a/docs/integration-guide.md b/docs/integration-guide.md new file mode 100644 index 0000000..1616750 --- /dev/null +++ b/docs/integration-guide.md @@ -0,0 +1,67 @@ +# Integration guide + +UmbNav was designed to be as clean and easy for developers as it is for editors to use. + +## Strongly typed models + +Out of the box UmbNav can return strongly typed models for a given navigation. + +The following properties are available in the `UmbNavItem` class: + +| Property | Type | Description | +|-------------------|-------------------|-------------| +| Id | Int | The node ID of the selected content item. For external linking nav items this will be "0" | +| Udi | GuidUdi | The node UDI of the selected content item. For external linking nav items this will be null | +| Title | String | The link title, often the node name | +| Target | String | The link target | +| Noopener | String | noopener if set in the backoffice | +| Noreferrer | String | noreferrer if set in the backoffice | +| Url | String | The link url | +| QueryString | String | The link querystring / anchor | +| Level | Int | The level in the overall navigation that the current item sits at | +| Content | IPublishedContent | The IPublishedContent for the selected content item. For external linking nav items this will be null | +| Children | List | The picked child / sub items for the current item | +| Culture | String | The link culture +| CustomClasses | String | Any CSS classes set in the backoffice +| ImageUrl | String | An image url as set in the backoffice + +## Implementing Razor + +UmbNav was designed to closely follow the "Umbraco way" of doing things so we don't impose our own styles or markup on you. + +It's easy to implement in your own Razor: + +```csharp +@inherits Umbraco.Web.Mvc.UmbracoViewPage +@using UmbNav.Core.Extensions +@using UmbNav.Core.Models +@using Umbraco.Web; +@{ + var site = Model.Root(); + var umbNav = site.FirstChildOfType("siteSettings").Value>("umbNavPE"); +} +@foreach (var item in umbNav) +{ + @item.Title +} +``` + +There is also some helpers available to generate the each menu item: + + ```csharp + GetLinkHtml(this UmbNavItem item, string culture = null, UrlMode mode = UrlMode.Default, object htmlAttributes = null) + ``` + +and in Umbraco V9 there is a TagHelper available: + +```csharp + +``` +To make the tag helper work in Umbraco V9 you will need to add the following you your `_ViewImports.cshtml` + +```csharp +@using UmbNav.Core +@addTagHelper *, UmbNav.Core +``` + +**Note:** For large navigations with multiple levels it is highly recommended that you cache your navigation for optimal performance.