Merge remote-tracking branch 'origin/Docs' into develop

AaronSadlerUK · Jul 26, 2021 · b6ddfd6 · b6ddfd6
2 parents a180dd7 + 67364c1
commit b6ddfd6
Show file tree

Hide file tree

Showing 2 changed files with 100 additions and 9 deletions.
diff --git 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 &copy; 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
@@ -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<IEnumerable<UmbNavItem>>("umbNavPE");
+}
+@foreach (var item in umbNav)
+{
+    <a class="nav-link " href="@item.Url()" target="@item.Target" rel="@item.Noopener @item.Noreferrer">@item.Title</a>
+}
+```
+
+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
+<umbnavitem menu-item="item" mode="UrlMode" culture="Culture"></umbnavitem>
+```
+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.