Skip to content
This repository was archived by the owner on Feb 10, 2024. It is now read-only.

Commit 72dc489

Browse files
leekelleherleekelleher
committed
Merge remote-tracking branch 'origin/temp/docs' into develop
Conflicts: README.md
2 parents 390897b + ad52209 commit 72dc489

File tree

3 files changed

+185
-2
lines changed

3 files changed

+185
-2
lines changed

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ A grid editor for Umbraco 7 that allows you to use Doc Types as a blue print for
1212

1313
### Installation
1414

15-
> *Note:* Doc Type Grid Editor has been developed against **Umbraco v7.1.4** and will support that version and above.
15+
> *Note:* Doc Type Grid Editor has been developed against **Umbraco v7.2.0** and will support that version and above.
1616
17-
Doc Type Grid Editor can be installed from either Our Umbraco package repository, or build manually from the source-code:
17+
Doc Type Grid Editor can be installed from either Our Umbraco package repository, or build manually from the source-code.
1818

1919
#### Our Umbraco package repository
2020

‎docs/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Doc Type Grid Editor
2+
## Documentation
3+
4+
* [Doc Type Grid Editor - Developers Guide](developers-guide.md)

‎docs/developers-guide.md

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
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+
![Nested Content - Prevalue Editor](assets/img/screenshot-01.png)
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+
![Nested Content - Add Item](assets/img/screenshot-02.png)
91+
92+
Simply click the ![Nested Content - Plus Icon](assets/img/icon-plus.png) 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+
![Nested Content - Plus Icon](assets/img/screenshot-02.5.png)
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 ![Nested Content - Plus Icon](assets/img/icon-plus.png) will not display the dialog and instead will jump straight to inserting an entry in the editor for you ready to edit.
101+
102+
![Nested Content - New Item](assets/img/screenshot-03.png)
103+
104+
More items can be added to the list by clicking the ![Nested Content - Plus Icon](assets/img/icon-plus.png) 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 ![Nested Content - Edit Icon](assets/img/icon-edit.png) icon.
107+
108+
![Nested Content - New Item](assets/img/screenshot-04.png)
109+
110+
To reorder the list, simply click and drag the ![Nested Content - Move Icon](assets/img/icon-move.png) icon up and down to place the items in the order you want.
111+
112+
To delete an item simply click the ![Nested Content - Delete Icon](assets/img/icon-delete.png) icon. If the minimum number of items is reached, then the ![Nested Content - Delete Icon](assets/img/icon-delete.png) 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+
![Nested Content - Single Item Mode](assets/img/screenshot-05.png)
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

Comments
 (0)