V11: Using IFileProvider to access assets added from packages

[elit0451]

Details

• In this PR tours, icons, package.manifest and grid.editors.config.js files are considered;
• The changes include accessing the file system through File Providers (by using IFileProvider) and thus providing those ⬆️ files;
• That way if a package adds those types of files, the physical files wouldn't clutter the Umbraco solution;
• We will look in the web root, and then check in RCLs;
• Check below for the folders, the files mentioned above should be located in, in order to be discovered (same location as stated in our docs);
• In some places, magic strings are used to filter out and optimize the loops we will make through the file system until we find the folder where the specific files are located. If a better solution comes to mind, comment down below 😋.

Test

• Tours
  • Add a new .json file in /App_Plugins/<YourTourPlugin>/backoffice/tours - ref: Backoffice Tours docs
    • You can use Umbraco.Cms.StaticAssets project for quick testing as it is an RCL -> ❗ create the App_Plugins folder inside wwwroot;
  • Create a tour object, like:

[
  {
    "name": "My Custom Backoffice tour",
    "alias": "myCustomBackofficeTour",
    "group": "Get things done!!!",
    "groupOrder": 1,
    "allowDisable": true,
    "culture": "en-US",
    "contentType": "",
    "requiredSections": [ "content", "media" ],
    "steps": [
      {
        "title": "Welcome",
        "content": "<p>In this tour . . .</p>",
        "type": "intro"
      }
    ]
  }
]

• • Verify that the new tour appears and that you can complete it;
  • Add another tour file in /App_Plugins folder at the root of Umbraco.Web.UI project and verify that this tour also appears -> that the old functionality still works;
    • ❗ Follow the same path structure as before;

• Icons

  • Add an .svg file inside Umbraco.Cms.StaticAssets\wwwroot\App_Plugins\<YourTourPlugin>\backoffice\icons
  • It can be this one;
  • Create a new document type and change the default icon to the one you just added;

• package.manifest

  • Add the following package.manifest file in /App_Plugins/{YourPackageName} as stated in the Package Manifest docs;
  • You can use the Umbraco.Cms.StaticAssets\wwwroot location again for the /App_Plugins folder;

{
    "name": "Sir Trevor",
    "version": "1.0.0 beta",
    "allowPackageTelemetry": true,
    "bundleOptions": "Default",
    "packageView": "/App_Plugins/SirTrevor/SirTrevor-config.html",
    "propertyEditors": [
        {
            "alias": "Sir.Trevor",
            "name": "Sir Trevor",
            "editor": {
                "view": "/App_Plugins/SirTrevor/SirTrevor.html",
                "hideLabel": true,
                "valueType": "JSON",
                "supportsReadOnly": true
            }
        }
    ],
    "javascript": [
        "/App_Plugins/SirTrevor/SirTrevor.controller.js"
    ]
}

• • On a document type, try to select a property editor and make sure you can find the Sir Trevor property editor we added through the package.manifest file;

• grid.editors.config.js

  • Add the following file ⬇️ into /config/grid.editors.config.js (ref: Grid Editors docs) - You can use Umbraco.Cms.StaticAssets project: Umbraco.Cms.StaticAssets\wwwroot\config\grid.editors.config.js file location:

[
    {
        "name": "Rich text editor",
        "alias": "rte",
        "view": "rte",
        "icon": "icon-article"
    }
]

• • In a document type, add a property with a Grid layout - keep the default settings;
  • Create a content node and add a row for our grid: ex: Headline;
    • The rich text editor appears immediately, as it is the only option;
  • Click again "Add content" and verify that there is indeed just one option - the one we added in our grid.editors.config.js
  • Delete the file from the config folder and verify that the types that appear for the Headline content are the ones that Umbraco comes with - namely the ones listed in Umbraco.Core\EmbeddedResources\Grid\grid.editors.config.js
    • This shows that we will check if we have a custom grid.editors.config.js file, otherwise, we will default to the embedded file.

---

Update:

• Nested package manifests are also discoverable both in RCLs and on disk - info in comment;
• The flow of discovering grid.editors.config.js file is the following:
  • Try to get file on disk;
  • If no file, check in RCLs;
  • If still no file, get the embedded one from Umbraco.
• For tours, in the case that the same tour (both file name and exact path match starting from App_Plugins folder) is found in both the website project and any RCL, RCL will be preferred. Check comment for explanation. If this is the case, we recommend changing the plugin folder name.

[kjac]

@elit0451 I've been trying this out and the described test flows work just fine.

However it seems like the code favors RCL files over files on disk in scenarios where the same files exist in both places. That doesn't seem right? I would expect the files on disk to take precedence, but maybe that's just me? I have observed this for tours and packages (both for manifests and for the files referenced within), but not for icons - though it might be worth doing a double check here for good measure.

I am also unable to serve a grid.editors.config.js file from disk. The old code would allow that file to exist under /config and take precedence over the embedded file.

I haven't reviewed the code yet, these are just initial test observations. It may very well be me that is testing this all wrong, but could you please have a look?

[elit0451]

Those are some valid concerns @kjac which we can definitely revisit, as at least my initial understanding of this task was that we would prefer the files from RCL which now that you mention it, might not make sense in all cases. I will make sure to clarify the intended workflow and I will check the rest of the things you mentioned 💪

[kjac]

@elit0451 one more behavioural thing to take into account: Nested package manifests. Although it is not clearly (or remotely) documented, Umbraco allows for package manifests to be nested in sub folders to the plugin root folders. This goes for language files as well, as they are usually shipped with the packages.

Consider this structure with nested package manifests and language files (also attached as a zip file here):

In v11/dev this yields:

In this PR, the nested dashboards are missing - but as you can see, the nested localization files are read out correctly:

Here's an issue that mentions the use of nested plugins (from back when we added nested language files).

[elit0451]

Comment for @kjac: The PR is ready for review again! 💪

Comment for my future self: The reason why the said behaviour was observed - favouring "RCL files over files on disk in scenarios where the same files exist in both places" * - is because our custom file provider (one reading from the website project) is registered after the RCL/static assets one (.ConcatComposite()), therefore it's picking up the RCL file first.
The same behaviour is observed in aspnetcore.

Finally, there has also been a short discussion which outcome is also in agreement to what we saw that content from Razor Class Library (RCL) can't really be overridden. BUT again, the chances of the mentioned scenario* happening are very minimal. Overriding Umbraco files in relation to tours, lang files, grid.editors.config.js will be possible as those are embedded files.

[kjac]

@elit0451 the code looks great and tests out well👍 I have left a few small comments here and there for you to consider

[kjac]

Looks good to me 🎉