Add/Remove Layers 3.0 - Full Settings Panel Support for Enterprise Deployment

2 Kudos

I have spent all of December working on the fourth (and fifth) and hopefully final versions of my Add/Remove Layers Widget. This version of the widget is designed to be used in an Enterprise setting, as it is fully customizable from a relatively easy to use Settings Panel. Relative to teaching some how to code at least. As the person deploying the widget to your Enterprise, you can (and should) also pre-load this widget with pre-defined layers and groups that your users will find useful that they can use to start building their own layers and groups.

Purpose:

The purpose of this widget is to allow end-users to customize their maps at runtime. They can add/remove groups of layers at once or single layers one at a time. Adding layers as needed reduces map and layer list clutter, as well as, reducing memory and server load. FeatureLayers added with this widget have full data functionality as if they were added by the OOTB Add Data Widget. End users also can create their own groups of layers that persist between sessions for further personalization.

Release Versions:

The attached zip file contains two versions of this widget. In the Experience114 folder, you will find a widget designed and tested for Developer Edition 1.14 and Enterprise 11.3. (Maybe, you could make it work in older versions? I don't know.) Developer Edition 1.16 contains some breaking changes that added some new convenience functions for registering data as datasources and removes a key function for the 1.14 version of the widget. The Experience116 folder contains a version of the widget that was tested working in Developer Edition 1.16. It should also work in Enterprise 11.4 and (hopefully) future releases. These widgets will not function properly if used in the incorrect version number. Experience Builder 1.15 contained a bug that caused advanced data functions to stop working after layers were re-ordered, because of this neither will work properly in the 1.15 version.

Note: This widget itself contains breaking changes. Any user created groups in from the 2.5 version of this widget will not work in this version. Since the 2.0 version of this widget, the ids of FeatureLayers have been given the prefix 'custom_', this is no longer necessary in the 1.16 version of this widget and the prefix is no longer added.

Developer Instructions:

If you are not planning to deploy to an Enterprise environment, you can just skip to the Builder Instructions and not mess with the code at all.

Set the default layers and groups for your Enterprise by opening src/components/layers.ts. Replace the sample data in allLayersUnindexed with layers you want your users to use. Each layer must have a mapId, title, url, and specify if it is a FeatureLayer or MapImageLayer. If the layer is to be used in the first default group, it should also have the activeOnLoad: true property. Layers are expected to be sorted alphabetically by title (probably not necessary for you to do it). Default groups should be described in the groupsUnindexed array. Each group should have a name and contain a layers array referencing values in the allLayers array for the layers in that group. Items in this array should be ordered with the lowest layer in the drawing order first in the array. The first group in the groupsUnindexed array will be the default on load group. I wrote and tested this widget with groups and layers alphabetized. (Actually, almost alphabetized. One of the Default Layers is out of proper alphabetical order.) I don't think it is necessary for the data in layers.ts to actually be alphabetized in the final version. Layers and groups will automatically alphabetize themselves when taken off default settings. Once your layers and groups are set up, compile the widget and deploy to your Enterprise.

Security Note: There are several text boxes in this widget that accept raw input from the user. It is possible that a sophisticated user could exploit this for nefarious purposes. My feeling is if you have a sufficiently knowledgeable insider with the motivation to do bad things to you, they already have a thousand easier methods of attack, but if you're paranoid, you shouldn't deploy this widget to your Enterprise. (Or any custom widget you did not personally make.)

Builder Instructions:

This widget is not functional in the Builder/Live View mode. You will need to use Preview to see it in action.

Add the widget to your project and connect it to a Map Widget. At the bottom of the Settings Panel are these six options.

Turn off Allow Single Layers if you only want end users to add/remove data by group. Turn off Allow Groups if you only want users to add/remove data one layer at a time. Groups can still be used in the Settings Panel to control the Active On Load settings. (Dropdown menu will rearrange itself logically in response to these settings.) Turning off both of these options at the same time will make the widget invisible. In Invisible Mode, the Active On Load layers will still load when the widget loads, but the end user will have no controls. (Get creative. This option was built for making hacks. Tell me what you've done with it. I think there is some fun to be had putting this in a lazy-loading Section Widget. I have not tried to do anything with this yet.)

If you do not want the end user to make their own groups, turn off the Allow User Created Groups option.

Layers in groups will initially load in a pseudo-random order. This is designed to correct itself after a set amount of time. Increase or decrease the Reordering Delay so that it is slightly longer than the most complex group change. The Default Layer Order Button gives end users access to the reordering function if the reordering delay is not high enough or they want to reset after using the drag-and-drop reordering option. Turn this button off, if you don't want to show it to end users.

Layers in groups will draw starting from the index indicated. 0 is the lowest possible operational layer, just above the basemap. Do not make this number higher than the number of operational layers in your webmap.

The Settings Panel will open with scary red boxes saying that if you turn off the defaults, you can't go back. If you want to go back to the defaults, you will need to start again from a new widget. (In earlier attempts at building this widget, it was possible to restore defaults, but the possible permutations were endless and it kept making new bugs, until I went insane, then I gave up and made this widget a one-way street and everything worked.)

It is possible to turn off the Default Groups and change the group settings without altering the Default Layers. But turning off Default Layers or changing the Active On Load Group will, turn off both Default Layers and Groups.

While the Default Layers/Groups are still on, hit the Show Layers/Groups to see, but not edit, what Layers and Groups are available.

Once the Defaults are turned off, these buttons will change to Set Layers/Groups. The Default Layers and Groups will be used as starting values for your customizations.

Clicking the Set Layers button will open a submenu. In here, you may add Layer or edit or remove existing Layers. Removing a Layer will also delete any Groups it is used in. To start with a "clean slate", you can Remove All Layers. This will immediately remove all Layers and Groups.

Layers must have a Title, ID, URL and specify if it is to be used as a Feature Layer or a Map Image Layer. The Title will be displayed to the end-user and cannot be blank. The ID will be used internally by this widget and the Map Widget. It cannot be blank or be used by other Layers. It may only include letters or numbers. The URL should be the REST endpoint of the Layer and cannot be blank. Feature Layers will load with full data functionality. Map Image Layers will have less functionality, but typically load faster and have more advanced symbology and labeling options. This widget will not verify if the URL is a valid REST endpoint or if it can be used as the specified Layer Type. It is up to the application designer to use the correct options. The icon and text around the Layer's title will indicate if the updates are Valid (and saved), Invalid, or Not Saved. New Layers, Edits and Removals must be saved in the submenu then saved again using the normal Experience Builder Save Button.

The Active On Load property is controlled by the Active On Load Group. Changing the Active On Load Group will alter the Active On Load property of every Layer so they match the correct values. The Active On Load property is locked unless the Active On Load Group is set to None. Then, it can be altered in the Set Layers submenu. The Active On Load properties of the Layers will not change when setting the Active On Load Group to None. You will be expected to manually go through each Layer and set it as you wish. (Or use the hack in the paragraph below.)

Clicking Set Groups will open the Set Groups submenu where you can add new Groups or edit or remove existing Groups. Removing or altering Groups will not affect any Layers. (Note: If you add or remove layers from the current Active On Load Group or delete the Group entirely, the widget will start with the Active On Load values of the Layers will not change. Switch to a different Active On Load Group or None, then back to get the widget to notice the new Group layers. This bug can be exploited to create an Active On Load Group that is not available in the Groups menu easier than setting all the Layers manually.)

Each Group must have a unique name to be displayed to the end user and at least one layer. Use the checkboxes by the Layer titles to select which Layers should be in the Group, then Set Layer Order with the lowest drawing Layer being 1 and the highest number drawing at top. Every number from one to the highest number must be used exactly once. (Pay attention to the numbers. The ordering in the Builder is not consistent for reasons I don't fully understand and gave up on figuring out.) You will also need to save in the submenu and again in the Header Bar.

I've said it before, but easy-to-use and adaptable are directly competing goals and I have so much respect for the developers of Experience Builder for making a platform that scores quite highly on both metrics. Which is to say, I tried my best to make this as simple as I could, I'm sorry it's still complicated.

End User Instructions:

Click on Add/Remove Layers to add or remove layers. Groups made in the Build Mode will be on top with any Groups made by the user underneath in the User Groups section. Only one Group can be active at any time. Selecting a new Group will remove any layers not in the new Group and add all the Layers in the Group. Active Groups and Layers are indicated with a check mark. Clicking a checked Layer or Group will remove the Layer or Group. Click Add/Remove Single Layers to open the All Layers submenu and alter the map by one layer at a time.

Please be patient when switching between Groups. You may notice Layers appearing and disappearing in the Map Layers Widget or Layers loading in the incorrect order. This should correct itself after a few seconds. If it does not, use the Default Layer Order Button. Using the All Layers submenu will disable this button.

To make your own Group, first select the set of Layers you wish to save in the menu. The widget will remember what order they were added in and later draw them in the same order, but not any later reordering, so you may wish to remove all Layers first to add them in a specific order. When your Layers are chosen, click the Save Current Layers As... Button, and give your Group a name. Your Group Name can only contain letters (no numbers, spaces or other characters are allowed). If your name is valid you can click Save Group and it will save the Layers active at the moment it's saved to a new User Group. Saving again with the same Group Name will overwrite the Group with a new set of Layers. You may delete a User Group with the trashcan next to the name of the User Group in the Add/Remove Layers Menu. Your User Groups will be deleted if you clear the cookies for this site and each Group will expire after one year. Re-saving under the same name should reset the one year timer.

The appearance of the widget and what options are available to you may change based on options selected in the Build Mode.

JeffreyThompson2 · ‎01-14-2025

I think I found a big bug that will prevent you from adding layers. I will come back and correct it when I have time. In components\layerPicker.tsx. Find the JSX for the Save Button. It should look like this.

<Button
    type='primary'
    block
    disabled={currentStatus !== 'Not Saved'}
    onClick={() => handleUpdateLayer(internalId)}
>
    <SaveFilled/>
    Save Changes
</Button>

Change the onClick function so it looks like this.

<Button
    type='primary'
    block
    disabled={currentStatus !== 'Not Saved'}
    onClick={() => handleUpdateLayer(internalId || '')}
>
    <SaveFilled/>
    Save Changes
</Button>

Edit: The code should now be corrected. Fixed in a slightly different way than described above, but the above should also work.

Add/Remove Layers 3.0 - Full Settings Panel Support for Enterprise Deployment