Lars-Erik's blog

Our.Umbraco.WysiwygGrid 1.0.0 beta released

Thu, 23 Apr 2020 12:09:36 Z

A while ago I blogged about the state of WYSIWYG in the Umbraco grid editor. We're now about to add this script to a second and likely third Umbraco 8 site, so I had to generalize and package up the code.

There's nothing much to hide or earn from here, so I decided to put it up on github and nuget instead of our internal scm and feeds.

Hope to see some more community members fiddling with it, if nothing else that it inspires the block editor team to make the backoffice experience more similar to the frontend look and feel.

A definite change from the previous blogpost is that we favor grid settings over inline styling. By slightly modifying the bootstrap view (we use v4 anyway), we can add multiple classes instead of attributes as is done the original views. As such we can have settings like these:

Those will generate extra classes named padding-lots and theme-inverse.
Those classes are added to rows or cells in both the backoffice and the front-end.
By doing some fancy sass include ninjaing, we can hopefully limit the amount of duplication, while still mimicing the front-end as much as possible in the backoffice.

There are some samples in the github repo if you're unsure how to get started. The SQLCE database is included with a fairly common test username/password. 😇

Without further ado, here's the nuget and github links:

https://github.com/lars-erik/Our.Umbraco.WysiwygGrid
https://www.nuget.org/packages/Our.Umbraco.WysiwygGrid/1.0.0-beta01

Hope you enjoy it, and as usual, hope for a good discussion or feedback from the community!

The state of WYSIWYG grid editing in Umbraco - a prototype

Fri, 03 Apr 2020 13:26:14 Z

The state of the grid

Since the grid was launched at the CG talk "The sky is the limit" back in 2015 (i think), it has been a joy to use for editors, designers and developers alike. Granted, there's been the other feature that could've gotten more love (configuration and settings), but generally it does the job swell.
However, it's still just a white canvas with "settings applied".
Antoine made LePainter back in 2015, but likely didn't get much traction.
I was just told about it today by Callum. Shame on me for not watching the package space enough, how embarrasing. 😳

Anyway...

Why should we care

Recently, I've been in lots of discussions; near battles IMO; about which CMS to sell to our customers.
The feedback is that editors wonder why what they see while editing does not match what they see in the front-end. We do work with another CMS where the backoffice experience has a near 1:1 layout and design with the front-end. As developers, we tend to think structured data is the better solution. Think nested- and stacked content. I tend to agree. But in a sales meeting, those arguments are total losing arguments. A competing agency will bury you when they oversell the fancy editing experience. Even though the not-so-apparent technical features of the competing CMS are totally useless.
And I do agree - the editing experience is what Umbraco likes to sell as well!

What can we do?

The current HQ efforts are working on the "block based" editor. It's been going on for the better part of a year, but the publicly available information is mostly just an RFC with screenshots looking like stacked / nested content, and that's it. The technical aspects seem super, but there's nothing much (but text) about the general editing experience. Also, and I know this is a hot take, editors DO want to see three columns in the editor when it ends up three columns in the front-end.

Hopefully, as mentioned in the RFC, it can act as a stepping stone towards the "Grid 2.0" (which we started work on at the retreat two years ago).

But as far as I'm concerned, this could just as well end up never happening. The effort is not very visible, Project UniCore 🦄 has (rightly) high priority, and in the mean time we're stuck with Grid 1.0, or maybe, hopefully, a rumored commercial package called Bento by the eminent Peter Gregory and his colleagues at KØBEN Digital.

A prototype

So back using Grid 1.0 for projects to be delivered imminently, I've started doing some prototypes for something similar to what LePainter did for early v7 projects.

I asked the community if it was madness or worth pursuing, and the general feedback is that it's both. Hence this blog post to explore it some more, and hopefully gather some more feedback or at least provide feedback to the block editor team. (Hope they receive it. 😁)

Here's a quick little preview of what I've been doing so far:

The issues

Actually getting the styling into the grid is "just" a matter of including a few pagefuls of JavaScript and a limited and scoped CSS file in a package.manifest file for the site. Both classes and styles are applied as expected, and with some due dilligence it doesn't look half bad.

The biggest issue I have is that the cells and controls are styled white, and while styling one have to mind not messing up the GUI text like "Settings applied".

I attempted to lessen the opacity of the cells and controls, and it works to a degree. The minute one adds a background image however, the entire thing starts to crumble. How to keep the WYSIWYG experience while still seeing the GUI? One could fantasize about doing an average color sample of the image and toggling between white and black text, maybe? Could be done in a short hacking sprint...
Could just keep it fairly white like I've done in the prototype. Could keep just the active rows white. This is where I start struggling. 😳

To be frank, the biggest problem lies in the fact that the "Add content" button is in the grid. Other CMSes have drag drop functionality from a menu over to the side. It could possibly still just be white or slightly transparent. The last problem then is all those "settings applied" and empty cells with the other type of "Add content" button.

I can't help but think this is all within grasp, albeit just out of my limited back-ender reach. 😆

The settings dialog issues

The settings dialog is a chapter of itself. It's a mystery to me why we still have a concept of individual "prevalue editors" in Umbraco. Property editors have the same model, and can be sneaked in there by just providing a full path.

However, as experienced when working on our ContentList package, nesting property editors using built-in directives wreaks total havok on the styling. There's some grey background and drop shadows - that I haven't seen being actively used anywhere. It's generally just a mystery, and a huge candidate for backoffice re-work.

Also, for instance the slider property editor does look a bit weird when used as a setting editor. I do hope that those things will get an overhaul and are made more uniform sooner or later.

I'll just leave that hanging, since I know (and appreciate) there are several HQ and community efforts going on to clean things up.

The code

Since I managed to sneak in a few new events in the grid, making it work was a matter of hooking into the "grid.initialized" event and start watching the model. There might be some performance issues with large grids since it's a deep watch, but with todays computers that might be irrational over engineering to think as well.

It adds the configured styles as expected.
For the configuration, it just adds the value of the configuration setting called "class". If there's more it concats the setting key with the setting value, delimited by a dash.

You can scrutinize the JavaScript here, or in this gist.

angular.module("umbraco").run(["eventsService", function(eventsService) {
    function findModelScope(scope) {
        if (!scope) {
            return null;
        }
        if (scope.model) {
            return scope;
        }
        return findModelScope(scope.$parent);
    }

    function isProtectedClass(className) {
        return className === "umb-row-inner" ||
            className === "umb-cell-inner" ||
            className.substr(0, 2) === "ng-" ||
            className.substr(0, 2) === "ui-";
    }

    function addClasses(element, gridItem) {
        function classNameFromConfig(e) {
            if (e === "class") {
                return gridItem.config[e];
            } else {
                return e + "-" + gridItem.config[e];
            }
        }

        var classes = (element.className || "").split(/\s+/);
        var newClasses = classes.filter(isProtectedClass);
        var nameClass = (gridItem.name || "").toLowerCase().replace(" ", "-");
        var configClasses = Object.keys(gridItem.config || {}).map(classNameFromConfig);
        newClasses.push(nameClass);
        newClasses = newClasses.concat(configClasses);
        element.className = newClasses.join(" ");
    }

    function addStyles(element, gridItem) {
        function styleFromKeyPair(e) {
            return e + ":" + gridItem.styles[e];
        }

        var stylesValues = Object.keys(gridItem.styles || {}).map(styleFromKeyPair);
        element.style = stylesValues.join(";");
    }

    eventsService.on("grid.initialized",
        function(evt, data) {
            var modelScope = findModelScope(data.scope);
            var model = modelScope.model;
            var jqEl = data.element;
            var el = data.element.get(0);
            jqEl.addClass("stylized-grid");

            modelScope.$watch(
                "model",
                function () {
                    var areaElements = el.getElementsByClassName("umb-column");
                    if (areaElements.length === 0) {
                        return;
                    }
                    model.value.sections.forEach(function (area, ai) {
                        var rowElements = areaElements[ai].getElementsByClassName("umb-row-inner");
                        area.rows.forEach(function (row, ri) {
                            var rowElement = rowElements[ri];
                            addClasses(rowElement, row);
                            addStyles(rowElement, row);

                            var cellElements = rowElement.getElementsByClassName("umb-cell-inner");
                            row.areas.forEach(function(cell, ci) {
                                addClasses(cellElements[ci], cell);
                                addStyles(cellElements[ci], cell);
                            });
                        });
                    });
                },
                true
            );
        });

}]);

The CSS

To not interfere with any other backoffice styling, the script adds the class "stylized-grid" to the grid container. Here's the (S)CSS I used to make things more transparent:

.umb-grid.stylized-grid { 

    .umb-cell-content {
        background-color: rgba(255, 255, 255, .8);
    }

    .umb-cell-content:hover {
        background-color: rgba(255, 255, 255, 1);
    }

    .umb-cell-content.-has-editors {
        background-color: rgba(255, 255, 255, .8);
    }

    .umb-cell-content.-has-editors:hover {
        background-color: rgba(255, 255, 255, 1);
    }

    .umb-grid-add-more-content {
        background-color: rgba(255, 255, 255, 1);
    }

    .umb-control-bar, .umb-grid-has-config {
        font-family: Lato, Helvetica Neue, Helvetica, Arial, sans-serif !important;
    }

    iframe {
        background-color: transparent;
    }

    @import "../../../Assets/grid";
}

The import at the bottom is the sass that styles our individual components in the front-end, and that should be reflected in the backoffice.

Conclusion

We'll be diving into deep water and testing this out on a real customer. I'm a bit weary, but we need to get the experience.

I do hope I've been able to provide some inspiration, and that WYSIWYG editing in Umbraco might get the renaissance (I believe) it deserves.

Feel free to drop your comments below or ping me on Twitter or Slack!
Also happy to continue the discussion on our or github, but not sure the best way forward, if any.

Templatable grid for Umbraco

Wed, 28 Sep 2016 20:33:56 Z

Have you ever created several documents in a row and set up more or less the same grid layout for each page? Becomes a hassle after a few pages, doesn't it? Distress no more! Here's a package that let's you create default layouts for your grids to get a flying start.

TL;DR: There's a video at the bottom.

Word to the wise

This is an alpha, and it's probably still got some quirks. We use it in production for all our newer sites, so it should be quite safe. However, if you're going to modify your existing grids:
MAKE SURE YOU NOTE DOWN THE CONFIGURATION!
The data type will reset back to the default grid settings when you change the property editor.
You could probably just change the property editor alias in the database, but I'll leave that for the savvy ones.
There's one other drawback, namely that it cannot be set up properly when using the document type editor to edit the datatype.

Usage

In addition to the built-in prevalues for layout and RTE configuration, there is an additional prevalue for the default layout. Add rows and editors like in a regular document, until you've got a nice starting point for all pages.
NB! When changing the layout configuration, especially renaming things, you may have to use the "Reset layout" button to be able to create a new layout.

Core potential

I've made a PR for this to be part of the core since I believe it's a pretty useful feature for many sites. Feel free to give the issue a vote if you'd like to see it built-in too. By "popular" demand, I decided to release it as a package for better community support. Thanks, Lee! :)

Oh shut up, just show me how it works

Aww, OK. At least I hope I got some proper SEO out of the babble above. :)

Building a text flow editor for the grid

Tue, 20 Sep 2016 18:08:20 Z

I'm continuing my journey in search of a good separation between content and layout in Umbraco. I'm fairly confident it should be quite quick to get a prototype together. Even when blogging while doing it. Let's see if we can't create a grid editor which can be configured to show another rich text editor property in the document. It should also have a way to limit said content. Say n root elements from the HTML.

In our sites, we've modified the grid slightly. There's a PR hoping to be pulled to the core. (Now also a package) It makes it possible to create a "template" for new grids of a type. Whenever the user creates a "Page", it has a grid with a header, a summary and a body. It's also got a column for widgets and hullabaloo's. The template is just the grid on the data type settings page. It's just another setting. If I put that on tab number 2, then in many cases, editors wouldn't even have to relate to the layout. They'll tackle that when they do need to add a form or other functionality.

So with this new editor, I'm hoping to swap out the header and the rich text editors with pointers to some structured fields instead. As an added challenge, my eminent colleague and world class UX expert Stig Hammer insists this will only be used by 5% of all editors. It'll be too abstract and complex for the general crowd to use. We'll see. We might just be surprised.

Follow along?

The code for this article is on GitHub. There's a chance I'll miss an update or two in the samples here, but there's working code in the repo. I'll also omit large setup fragments and other things that obscure the valuable bits.

First iteration: UI prototype

I'd like to start off by having a placeholder in the grid. It should make use of grid editor settings (a cog for grid editors) and two settings where we'll use some one-off "virtual" property editors. We'll stick with the "nerdy" UX for now and see about some sugar later.

Except for the views, it should pretty much just be package.manifest configuration. Here's what I'm starting out with:

{
    "gridEditors": [
        {
            "name": "Flowing text",
            "alias": "flowingText",
            "view": "/App_Plugins/FlowingText/editor.html",
            "icon": "icon-article",
            "config": {
                "settings": {
                    "source-property": {
                        "label": "Source property",
                        "key": "source-property",
                        "description": "The source for the text",
                        "view": "/umbraco/views/propertyeditors/dropdown/dropdown.html",
                        "config": {
                            "items": {
                                "dummy": "Dummy",
                                "dummy2": "Dummy 2"
                            }
                        }
                    },
                    "fragments": {
                        "label": "Fragments to show",
                        "key": "fragments",
                        "description": "How many paragraphs or fragments to show",
                        "view": "/umbraco/views/propertyeditors/integer/integer.html",
                        "config": {

                        }
                    }
                }
            }
        }
    ]
}

We'll just stub up a simple view for now to see if the settings dialog works as expected.

<div>Some day I'll flow like a river!</div>

I've changed the Fanoe Text Page to have an RTE called "Body Text" on a tab before the one with the "Content" grid on it. I've changed the tab names so the body is in "Content" and the grid is in "Layout".

Jumping into the layout and the grid, I've enabled "Flowing text" for a couple of the row defs. Adding one and clicking the cog gives me this:

I'd say that's a feasible prototype to start with, so let's see if we can feed the properties of the document into that dropdown and show some text.

Second Iteration: Live data

Since the "property editors" we used for the settings are just pointing to the views and not the property editor defintions themselves, we're free to configure them as we want. Fortune wants it so that the entire graph from the package.manifest makes its way to the controllers we add to our grid editors. Umbraco also has this nice little service called editorState. It holds the current entity of the main editor area. In our case - the document.

I'll do this test-driven for kicks. Here's the stub of a unit test that verifies our code will populate the dropdown with the properties in the document. I've omitted some setup stuff, but you can see the entire test in the GitHub repo.

/// <reference path="/Umbraco/lib/angular/1.1.5/angular.js" />
/// <reference path="/Umbraco/lib/angular/1.1.5/angular-mocks.js" />
/// <reference path="../flowingtext.js" />
(function () {

    describe("Flowing text grid editor", function () {

        var rootScope,
            scope,
            controllerFactory,
            defaultEditorState = { ... },
            model = { ... };

        beforeEach(module("umbraco"));
        beforeEach(
            inject(function ($controller, $rootScope) {
                controllerFactory = $controller;
                rootScope = $rootScope;
                scope = rootScope.$new();
                scope.control = angular.extend({}, model);
            })
        );

        it("populates the source property options with the properties of the document", function () {

            var sourcePropertySetting = scope.control.editor.config.settings["source-property"];

            controllerFactory("our.umbraco.flowingtext.controller", {
                "$scope": scope,
                "editorState": angular.extend({}, defaultEditorState)
            }),

            expect(sourcePropertySetting.config.items).toEqual({
                "bodyText": "Body text",
                "content": "Content"
            });

        });

    });

}());

I want to verify that "content" isn't in that list, but I'll leave that for a later iteration for now. If you can't guess why i'd like that, take 2 minutes to think about that right now. ;)

In any case, let's add the controller and hook it up to our view and see where that takes us:

(function () {
    var umbraco;

    function FlowingTextController(scope, editorState) {
        var model = scope.control,
            ti, pi, 
            tab,
            prop,
            items = {},
            sourcePropertySetting = model.editor.config.settings["source-property"];

        sourcePropertySetting.config = angular.extend(
            sourcePropertySetting.config,
            { items: items }
        );

        for (ti = 0; ti < editorState.current.tabs.length; ti++) {
            tab = editorState.current.tabs[ti];
            for (pi = 0; pi < tab.properties.length; pi++) {
                prop = tab.properties[pi];
                items[prop.alias] = prop.label;
            }
        }
    }

    function initializeUmbraco() {} // Fancy testing requirements inside

    initializeUmbraco();
    umbraco.controller("our.umbraco.flowingtext.controller", [
        "$scope",
        "editorState",
        FlowingTextController
    ]);
}());

And the view:

<div ng-controller="our.umbraco.flowingtext.controller">
    Some day I'll flow like a river, really!
</div>

And don't forget the package.manifest like I did. :)

...
"javascript": [
    "~/App_Plugins/FlowingText/flowingtext.js"
],
"gridEditors": [
...

Now how does it look when we pop the settings for the editor? On second thought, let's skip the click-the-cog step for new editors. Should be a quick fix....

We'll add an empty function to the test variable list:

editGridItemSettings = function() {};

And we'll add it to the root scope in the beforeEach(inject()) call:

rootScope.editGridItemSettings = editGridItemSettings;

Add a tad to the controller

if (!model.config) {
    model.config = {};
    scope.editGridItemSettings(model, 'control');
}

Et voilà, when we now add a "Flowing text" to the grid, it has all the properties we could want in it's list. And the settings dialog show by default.

We should probably try to remove a few irrelevant properties. Not to mention the "Content" one. (What? You didn't realise why yet? Go think about it some more! Think Inception...)

I'm happy for now though. Let's see if we can't make it so that when we select "Body text" the entire contents of the rich text editor is shown in our preview.

Third iteration: Present the text

First off, until now I've tried hard to keep this as compatible with property editors as I could. I'll get sloppy now, but I promise I'll return with a post about that, or just fix this up. The code should be pretty similar, if not the same for Archetype or Nested Content versions. So anyway, here's me getting sloppy. I'm sorry.

We'll need to watch the editor's config. When we submit the settings dialog, the root scope.control.config will be given key/value pairs from the settings dialog. For a property-editor in NC or Archetype, you'd have to watch scope.model.config. So you see where the sloppyness takes place.

I've also cached up the properties in the loop where we populate the dropdown:

for (pi = 0; pi < tab.properties.length; pi++) {
    prop = tab.properties[pi];
    properties.push(prop); // Remember to declare it...
    items[prop.alias] = prop.label;
}

Let's not get ahead of ourselves, though. We add a value to the defaultEditorState's bodyText property, then we go ahead and assert it's set as model.value when we digest:

    it("sets the value when a source property is selected", function() {
        var expectedText = "<p>The expected value</p>",
            initialText = "<p>Unexpected value</p>"
            property = defaultEditorState.current.tabs[0].properties[0];

        property.value = initialText;

        scope.control.config = {
            "source-property": "bodyText"
        };
        scope.$digest();

        // we have to do double digest here to simulate update to the text
        property.value = expectedText;
        scope.$digest();

        expect(scope.control.value).toBe(expectedText);

    });

So as we expect, whenever control.config["source-property"] changes, the editor value changes to the value of that property.

Here's the satisfying code:

        scope.$watch("control.config['source-property']", function() {
            if (model.config["source-property"]) {
                sourceProperty = $.grep(properties, function(p) {
                    return p.alias === model.config["source-property"];
                })[0];

                if (watch) {
                    watch(); // unregister if source changes
                }

                watch = scope.$watch(function() {
                    return sourceProperty.value;
                }, function() {
                    model.value = sourceProperty.value;
                });
            }
        });

And the view can now show the value:

<div ng-controller="our.umbraco.flowingtext.controller"
     ng-bind-html-unsafe="control.value">
</div>

Those of you still awake will notice a little gray json snippet there. I got desperate for a little while, so I added the universal debugging tool for any angular developer:

<div ng-controller="our.umbraco.flowingtext.controller" 
     ng-bind-html-unsafe="control.value">
</div>
<pre>{{control | json}}</pre>

We're more or less done with a nice little mirroring grid editor now. It can actually already replace my header grid editor with something mirroring a single document property for the header. We just need a razor view. I know you guys know how to fix that, so let's see if we can't make it do what we set out to now.

Forth iteration: Bringing it all together

We're almost there now, and it's getting late. Let's just jump straight at the next test:

    it("gets a limited amount of fragments", function () {
        var expectedText =
                "<h1>Expected header</h1>" +
                "<p>The expected value</p>",
            allText =
                expectedText +
                "<p>Unexpected value</p>",
            property = defaultEditorState.current.tabs[0].properties[0];

        property.value = allText;

        scope.control.config = {
            "source-property": "bodyText",
            "fragments": 2
        };
        scope.$digest();

        expect(scope.control.value).toBe(expectedText);
    });

I've added some more fragments to the other property. We configure it to show only two fragments. So we expect a heading and a paragraph. Here's a quite changed controller. I'll excuse myself and claim I'll come back and refactor it. Hope you can make sense of it.

    function FlowingTextController(scope, editorState) {
        var model = scope.control,
            ti, pi, 
            tab,
            prop,
            items = {},
            properties = [],
            watch,
            sourceProperty,
            sourcePropertySetting = model.editor.config.settings["source-property"];

        // We now update the value from two watches, so the function is extracted
        function updateFlow() {
            var elements,
                begin = 0,
                end = begin + model.config.fragments;
            if (!sourceProperty) {
                return;
            }
            elements = $.grep($(sourceProperty.value), function(e) {
                return !(e instanceof Text);
            });
            model.value =
                $("<div>").append(
                    $(Array.prototype.slice.call(elements, begin, end))
                )
                .html();
        }

        sourcePropertySetting.config = angular.extend(
            sourcePropertySetting.config,
            { items: items }
        );

        for (ti = 0; ti < editorState.current.tabs.length; ti++) {
            tab = editorState.current.tabs[ti];
            for (pi = 0; pi < tab.properties.length; pi++) {
                prop = tab.properties[pi];
                properties.push(prop);
                items[prop.alias] = prop.label;
            }
        }

        // Initialize an empty config
        if (!model.config) {
            model.config = {};
            scope.editGridItemSettings(model, 'control');
        }

        // Watch the fragments too
        scope.$watch("control.config['fragments']", updateFlow);

        scope.$watch("control.config['source-property']", function() {
            if (model.config["source-property"]) {
                sourceProperty = $.grep(properties, function(p) {
                    return p.alias === model.config["source-property"];
                })[0];

                if (watch) {
                    watch();
                }

                watch = scope.$watch(function() {
                    return sourceProperty.value;
                }, updateFlow);
            }
        });
    }

There are some polish needed here to adher to all practices. But again, I'll excuse myself. It's almost 12 am. :) Running this code now let's us add the first few fragments of the body text over and over again in the grid. I've put some text from slipsum.com in the body text and had a go with it (header's mine for motivation though):

I can almost feel it now. Let's do one more iteration and see if we can't get that second editor to show the rest of the body text instead of the same first parts.

Fifth iteration: Making it flow

We'll jump right into the next test again:

    it("gets the fragments remaining from the previous ones", function() {
        var expectedText =
                "<p>Expected paragraph</p>" +
                "<p>Another expected paragraph</p>",
            allText =
                "<h1>Unexpected header</h1>" +
                expectedText +
                "<p>Unexpected value</p>",
            property = defaultEditorState.current.tabs[0].properties[0];

        property.value = allText;

        scope.control.config = {
            "source-property": "bodyText",
            "fragments": 2
        };

        gridModel.value.sections[0].rows[0].areas[0].controls = [
            {
                editor: {
                    alias: "flowingText"
                },
                config: {
                    "source-property": "bodyText",
                    fragments: 1
                }
            },
            scope.control
        ];

        scope.$digest();

        expect(scope.control.value).toBe(expectedText);
    });

});

I've added the grid model to the root scope. It'll be there on scope.model in the controller. So this test inserts another editor before the one under test. It shows one fragment, so our instance under test should show the two next ones.

The code to satisfy this is by far the most incompatible with Archetype and Nested Context. I hope some of you guys find this interesting enough to hunt for a nice solution for those. Give me a shout if you need a hand.

Again, there's a lot of code omitted by now, but you can find it all on GitHub.

For the controller, I've added this big traversing method that finds the previous editors' fragment counts. It could most definitely be prettified, but I'm in a hurry to get this post to market and myself to bed. Here's the entire nested mess of it:

        function alreadyRenderedFragments() {
            var sections = scope.model.value.sections,
                section, si, row, ri, area, ai, control, ci,
                fragments = 0;
            for (si = 0; si < sections.length; si++) {
                section = sections[si];
                for (ri = 0; ri < section.rows.length; ri++) {
                    row = section.rows[ri];
                    for (ai = 0; ai < row.areas.length; ai++) {
                        area = row.areas[ai];
                        for (ci = 0; ci < area.controls.length; ci++) {
                            control = area.controls[ci];
                            if (control === model) {
                                return fragments;
                            }
                            if (control.editor.alias === model.editor.alias &&
                                control.config["source-property"] === model.config["source-property"]) {
                                fragments += control.config.fragments;
                            }
                        }
                    }
                }
            }
            return fragments;
        }

The only change to the rest of the controller is that updateFlow now initializes begin to the result of alreadyRenderedFragments.

                ...
                begin = alreadyRenderedFragments(),
                ...

Now updating our text pages gives us something more interesting:

Mesa like! There's the macro we don't want in the middle of our RTEs. Glimmering between the second and third paragraph of the body text.

Rounding up

There's a few more issues to tackle here. We should allow blank fragment configurations to represent "to the end of the text" or something along those lines. We should inform the user that there is no more fragments to render. I guess there's no real end to this. But I'm certainly satisfied with the proof of concept, and excited to see if it spawns some nice collaboration in the community.

What I'd really like next for this tool, is to make it so the first editor you add show everything by default. Closing the settings dialog and hovering the editor shows a scissor and a line between the fragments where you're currently hovering. Clicking splits the editor in two and let's you move the second one to another area. That would hopefully be a pleasant user experience.

I hope you enjoyed tagging along with me for this experiment. I certainly enjoyed bringing you. And thanks a lot for staying with me if you got this far. I'll see about continuing this, but for now, head over to GitHub, fork the project and have some fun with it.

Here's a video showing the final spin of the code so far.

Separating data and content from layout in Umbraco

Mon, 19 Sep 2016 20:07:12 Z

There's been some discussion on twitter and the issue tracker recently, about whether macros should be discontinued in Umbraco. They all end up discussing ways to use the grid or nested content, even archetype, to replace macro usage in rich text editors. The latter being a somewhat painful artifact from times forgotten. I also had an enjoyable discussion with Søren at uCommerce about whether storing data in the grid is a good idea at all. His point being quite valid, that the grid defines layout and should do only that, while content should be put in some other part of the document graph. While I find that a bit radical, I still appreciate the point. Here's a few of my thoughts on separating data from content with our current tools.

Context

First of all, it's all about context. Many early grid adopters have embraced the grid as salvation for "feature" pages. I really dunno if that's the right term, but you know the billboards going on and on. New colors and background images for each new area on a long scrolling page.
These pages are seldom more than gateways to the real meat, if there is any. Otherwise, they all lead the way to a big contact form or CTA at the bottom. The pages should be easily find on Google, but you're not that hard pressed for them in the internal site search.

But then there's your good old feature- and news articles, blog posts and what-nots. These are carefully structured into headings, summaries, body-texts, feature image, tags and all these things we find interesting in search and presentation contexts. You cannot as easily extract these interesting properties of an article type from the grid. After all, you'd have to traverse a big row/column tree checking editor aliases to find each item.

So it's all about context. There's pages where layout and content is deeply intertwined, and there's pages where layout has nothing to do with the content. And of course there's all the in-betweens.

The in-betweens

The discussions we had showcased a few pretty common scenarios. Editors want to insert a form, a quote or even an image gallery in the midst of their articles or pages. For ages, the solution has been macros inserted into the rich text editor representing the body of the page. Then came Archetype and Nested Content, which allowed us to create a list of rich text editors with stuff in between them. A body could consist of some text, a gallery, some more text, a form, and some finishing text. Maybe even a discussion plug-in at the bottom. (I guess some would)

I don't quite fancy this model. It can be done even worse with the grid. You'd separate the contents of an article even more than just in a list. There'd be rows and columns in between.

To be frank, our latest starter site per fall 2016 is just like that. We use the grid for a lot, although we still have and use my precious article document type. While thinking about this post, I've found several things I want to try out. But here's the rationale for keeping the main coherent text of a page out of your layout and widgets.

Main body

Imagine writing a book or and article. While working on the content, would you care to fiddle around with the figures, fact-boxes and images while putting your thoughts to paper? Imagine being the editor re-reading the text several times. How relevant is all the final extras to the core of the text you're editing? What about the proof-reader? Should everything be evaluated each time?

My point is - when writing this article, I leave out all links and illustrations until I'm satisfied with the content. I'll add this stuff later. It shouldn't really be part of the body of the article. There has to be a way to separate the decoration from the content.

More issues occur too when we mingle functionality and presentation with the content. What if a search result highlights the last two words of a rich text editor next to a form. It might show the containing phrases around the two words, including the label of the first field in the form. That'd be a bit embarrassing.

What others did

I guess already in the 80s or even 70s, desktop publishing programs could take a text and spread it out in columns, with images at fixed positions, boxes in fixed positions and everything that makes magazines nice to look at. They've got these nice little algorithms that pads text and makes it fit and spread nicely into whatever layout it's given. The text, however, is more or less plain ASCII stored in a linked text file. (Like this markdown)

Could we do the same with our content?

How about...

With either Nested Content or the grid, we could device an artifact that defines from which, and how many paragraphs to show. This means that we could keep our precious body RTE with naught but Hn, ul, b, i and a as allowed formatting. If I'd like to be able to insert a form at paragraph 3, I'd go to my NC or grid property. There, I'd add the body-text widget and configure paragraph 1-2. I'd add my macro or custom thingy next. Then I'd add another body-text widtget and configure paragraph 3-4. And so on. As you can see from the illustration, there are only pointers stored in our layout definition.

Hopefully, the other devices in the layout also actually reside as their own respective object graphs somewhere. So the only things we put in the list or grid is pointers to- and/or limiters to our content. Layout is kept separate from content.

The exceptions

As mentioned initially, it's all about context. Some of the stuff we put into our layout definitions are only to be used there. Ever! It's short. It might be two sentences ment to lure the user to click on them. It might be a bullet-list only relevant in this page.

These things I'll forgive putting into the grid or nested content. They're not relevant enough to be stored in a structured way. But we should really be adamant in our consideration of what should go into a layout definition and what should be structured content.

Products, re-usable content, forms, images, galleries (maybe not) and everything you might want to address individually from code or search should be persisted individually. To use them in grids or lists, you should refer to them. Create pointers. Create relations. Create layout definitions. You'll thank your past self for it some time in the future.

Disclaimer

This whole article is not to say you shouldn't go and abuse the new support for custom examine indexing of JSON coming in 7.6. ;)
(Yours truly might have had something to do with that)

A prototype

The day after I wrote this, I wrote a prototype. You can follow along here.