|
| 1 | +# Doc Type Grid Editor - Developers Guide |
| 2 | + |
| 3 | +### Contents |
| 4 | + |
| 5 | +1. [Introduction](#introduction) |
| 6 | +2. [Getting Set Up](#getting-set-up) |
| 7 | + * [System Requirements](#system-requirements) |
| 8 | +3. [Configuring The Doc Type Grid Editor](#configuring-the-doc-type-grid-editor) |
| 9 | +4. [Hooking Up The Doc Type Grid Editor](#hooking-up-the-doc-type-grid-editor) |
| 10 | +5. [Rendering a Doc Type Grid Editor](#rendering-a-doc-type-grid-editor) |
| 11 | + * [DocTypeGridEditorSurfaceController](#doctypegrideditorsurfacecontroller) |
| 12 | +6. [Useful Links](#useful-links) |
| 13 | + |
| 14 | +--- |
| 15 | + |
| 16 | +### Introduction |
| 17 | + |
| 18 | +**Doc Type Grid Editor** is an advanced grid editor for the new Umbraco grid, offering similar functionality as the macro grid editor but using the full power of the doc type editor and data types. |
| 19 | + |
| 20 | +With the macro grid editor you are limited to only using the macro builder and thus the handful of parameter editors that are available. Of course you can create / config your own parameter editors, however this is cumbersome compared to how we can configure data types. |
| 21 | + |
| 22 | +With the **Doc Type Grid Editor** then, we bridge that gap, allowing you to reuse doc type definitions as blue prints for complex data to be rendered in a grid cell. |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +### Getting Set Up |
| 27 | + |
| 28 | +#### System Requirements |
| 29 | + |
| 30 | +Before you get started, there are a number of things you will need: |
| 31 | + |
| 32 | +1. .NET 4.5+ |
| 33 | +2. Umbraco 7.2.0+ |
| 34 | +3. The **Doc Type Grid Editor** package installed |
| 35 | + |
| 36 | +--- |
| 37 | + |
| 38 | +### Configuring The Doc Type Grid Editor |
| 39 | + |
| 40 | +The **Doc Type Grid Editor** is configured via the grid.editors.config.js config file located in the /Config folder. A default configuration should be installed along with the package, but for details on the configuration options, please see below. |
| 41 | + |
| 42 | +#### Example |
| 43 | + |
| 44 | +```javascript |
| 45 | + 1. [ |
| 46 | + 2. ... |
| 47 | + 3. { |
| 48 | + 4. “name”: ”Doc Type”, |
| 49 | + 5. “alias”: ”docType”, |
| 50 | + 6. “view”: ”/App_Plugins/../doctypegrideditor.html”, |
| 51 | + 7. “render”: ”/App_Plugins/../doctypegrideditor.cshtml”, |
| 52 | + 8. “icon”: ”icon-item-arrangement”, |
| 53 | + 9. “config”: { |
| 54 | + 10. “allowedDocTypes: [...], |
| 55 | + 11. “enablePreview”: true, |
| 56 | + 12. “viewPath”: “/Views/Partials/” |
| 57 | + 13. }, |
| 58 | + 14. ... |
| 59 | + 15. ] |
| 60 | +``` |
| 61 | +
|
| 62 | +
|
| 63 | +The **Nested Content** property editor is set-up/configured in the same way as any standard property editor, via the *Data Types* admin interface. To set-up your Nested Content property, create a new *Data Type* and select **Nested Content** from the list of available property editors. |
| 64 | +
|
| 65 | +You should then be presented with the **Nested Content** property editors prevalue editor as shown below. |
| 66 | +
|
| 67 | + |
| 68 | +
|
| 69 | +The prevalue editor allows you to configure the following properties. |
| 70 | +
|
| 71 | +| Member | Type | Description | |
| 72 | +|-----------------|---------|-------------| |
| 73 | +| Doc Types | List | Defines a list of doc types to use as data blue prints for this **Nested Content** instance. For each doc type you can provide the alias of the tab you wish to render (first tab is used by default if not set) as well as a template for generating list item labels using the syntax `{{propertyAlias}}`. | |
| 74 | +| Min Items | Int | Sets the minimum number of items that should be allowed in the list. If greater than 0, **Nested Content** will pre-populate your list with the minimum amount of allowed items and prevent deleting items below this level. Defaults to 0. |
| 75 | +| Max Itemd | Int | Sets the maximum number of items that should be allowed in the list. If greater than 0, **Nested Content** will prevent new items being added to the list above this threshold. Defaults to 0. | |
| 76 | +| Confirm Deletes | Boolean | Enabling this will require item deletions to require a confirmation before being deleted. Defaults to TRUE | |
| 77 | +| Show Icons | Boolean | Enabling this will display the items doc type icon next to the name in the **Nested Content** list. | |
| 78 | +| Hide Label | Boolean | Enabling this will hide the property editors label and expand the **Nested Content** property editor to the full with of the editor window. | |
| 79 | +
|
| 80 | +Once your data type has been configured, simply set-up a property on your page doc type using your new data type and you are set to start editing. |
| 81 | +
|
| 82 | +--- |
| 83 | +
|
| 84 | +### Editing Nested Content |
| 85 | +
|
| 86 | +The **Nested Content** editor takes a lot of styling cues from the new Umbraco grid in order to keep consistency and a familiarity to content editors. |
| 87 | +
|
| 88 | +When viewing a **Nested Content** editor for the first time, you’ll be presented with a simple icon and help text to get you started. |
| 89 | +
|
| 90 | + |
| 91 | +
|
| 92 | +Simply click the  icon to start creating a new item in the list. |
| 93 | +
|
| 94 | +If your **Nested Content** editor is configured with multiple doc types you will be presented with a dialog window to select which doc type you would like to use. |
| 95 | +
|
| 96 | + |
| 97 | +
|
| 98 | +Simply click the icon of the doc type you wish to use and a new items will be created in the list using that doc type. |
| 99 | +
|
| 100 | +If you only have one doc type configured for your **Nested Content** editor, then clicking the  will not display the dialog and instead will jump straight to inserting an entry in the editor for you ready to edit. |
| 101 | +
|
| 102 | + |
| 103 | +
|
| 104 | +More items can be added to the list by clicking the  icon for each additional item. |
| 105 | +
|
| 106 | +To close the editor for an item / open the editor for another item in the list, simply click the  icon. |
| 107 | +
|
| 108 | + |
| 109 | +
|
| 110 | +To reorder the list, simply click and drag the  icon up and down to place the items in the order you want. |
| 111 | +
|
| 112 | +To delete an item simply click the  icon. If the minimum number of items is reached, then the  icon will appear greyed out to prevent going below the minimum allowed number of items. |
| 113 | +
|
| 114 | +#### Single Item Mode |
| 115 | +
|
| 116 | +If **Nested Content** is configured with a minimum and maximum item of 1, then it goes into single item mode. |
| 117 | +
|
| 118 | +In single item mode, there is no icon displayed to add new items, and the single items editor will be open by default and it’s header bar removed. |
| 119 | +
|
| 120 | +In this mode,** Nested Content** works more like a fieldset than a list editor. |
| 121 | +
|
| 122 | + |
| 123 | +
|
| 124 | +--- |
| 125 | +
|
| 126 | +### Rendering Nested Content |
| 127 | +
|
| 128 | +To render the stored value of your **Nested Content** property, a built in value convert is provided for you. Simply call the `GetPropertyValue<T>` method with a generic type of `IEnumerable<IPublishedContent>` and the stored value will be returned as a list of `IPublishedContent` entity. |
| 129 | +
|
| 130 | +Example: |
| 131 | +
|
| 132 | +```csharp |
| 133 | +@inherits Umbraco.Web.Mvc.UmbracoViewPage |
| 134 | +@{ |
| 135 | + var items = Model.GetPropertyValue<IEnumerable<IPublishedContent>>("myProperyAlias"); |
| 136 | + |
| 137 | + foreach(var item in items) |
| 138 | + { |
| 139 | + // Do your thang... |
| 140 | + } |
| 141 | +} |
| 142 | +``` |
| 143 | +
|
| 144 | +Because we treat each item as a standard `IPublishedContent` entity, that means you can use all the property value converters you are used to using, as-well as the built in `@Umbraco.Field(...)` helper methods. |
| 145 | +
|
| 146 | +Example: |
| 147 | +```csharp |
| 148 | +@inherits Umbraco.Web.Mvc.UmbracoViewPage |
| 149 | +@{ |
| 150 | + var items = Model.GetPropertyValue<IEnumerable<IPublishedContent>>("myProperyAlias"); |
| 151 | + |
| 152 | + foreach(var item in items) |
| 153 | + { |
| 154 | + <h3>@item.GetPropertyValue("name")</h3> |
| 155 | + @Umbraco.Field(item, "bodyText") |
| 156 | + } |
| 157 | +} |
| 158 | +``` |
| 159 | +
|
| 160 | +#### Single Item Mode |
| 161 | +
|
| 162 | +If your **Nested Content** property editor is configured in single item mode then the value converter will automatically know this and will return a single `IPublishedContent` entity rather than an `IEnumerable<IPublishedContent>` list. Therefore, when using **Nested Content** in single item mode, you can simply call `GetPropertyValue<T>` with a generic type of `IPublishedContent` and you can start accessing the entities property straight away, rather than having to then fetch it from a list first. |
| 163 | +
|
| 164 | +Example: |
| 165 | +```csharp |
| 166 | +@inherits Umbraco.Web.Mvc.UmbracoViewPage |
| 167 | +@{ |
| 168 | + var item = Model.GetPropertyValue<IPublishedContent> ("myProperyAlias"); |
| 169 | +} |
| 170 | + <h3>@item.GetPropertyValue("name")</h3> |
| 171 | + @Umbraco.Field(item, "bodyText") |
| 172 | +``` |
| 173 | +
|
| 174 | +--- |
| 175 | +
|
| 176 | +### Useful Links |
| 177 | +
|
| 178 | +* [Source Code](https://github.com/leekelleher/umbraco-doc-type-grid-editor) |
| 179 | +* [Our Umbraco Project Page](http://our.umbraco.org/projects/backoffice-extensions/doc-type-grid-editor) |
0 commit comments