Add support for managing shortcuts to navigate to specific pages

[dshokouhi]

Summary

Fixes: #918 let's close the issue for now and let users add additional enhancement requests

Got what I think is a good MVP for supporting shortcuts by first focusing on navigating to a specific page in home assistant.

Here is what is entailed:

• Android only supports a total of 5 static and dynamic shortcuts combined, given the nature of the app static shortcuts don't make sense. On top of that most launchers only support showing 4 so the 5th one may not show at all! Now its not a limitation to how many dynamic shortcuts they can move to the home screen its a limitation on whats available to drag. So users who use dynamic shortcuts have to be mindful of what shortcuts they have added to add more which sounds like a odd user experience. To allow dynamic shortcuts to do more we may need to rethink the approach but having 5 as the cut off for dynamic sounds like a safe call for now. Even here it can be odd as a user needs to first add 4 dynamic shortcuts, move some to the home screen, remove one from the list in settings and then add the 5th to display it. This would need to be done anytime they want to add a new one. Talk about a lot of steps.
• Shortcuts are only supported on certain versions of android, pinned shortcuts have a higher API level and require launcher support
• There is no limit to the amount of pinned shortcuts
• Preferences are ideal to use here as the 5 shortcuts are predictable since thats the maximum allowed to show in the app icon list
• Supported devices will have a UI to add as many pinned shortcuts as they like with the ability to edit any active pinned shortcut that we can find
• Dynamic shortcuts can be removed from the long press list
• All shortcuts can be updated once added
• For now short label, long label and the webview path are required fields

In the future:

• Allow more icons instead of the default (maybe first start with all icons the app has?)
• Allow more types of shortcuts like executing a button widget or any service call (might start with scripts/scenes)
• Accept more shortcut parameters if we need to
• What else users can think of that makes sense :)

Screenshots

Link to pull request in Documentation repository

Documentation: home-assistant/companion.home-assistant#482

Any other notes

https://developer.android.com/guide/topics/ui/shortcuts
Replaced a few hard coded strings with translated strings in the Settings fragment

[dshokouhi]

Now that #1446 is merged I can confirm that entityId:<entity> does indeed load the more info panel with shortcuts. May need to rethink the webview path naming OR introduce different shortcut types to switch between the two. For this MVP though not sure if it needs to be changed as it still works 🤷‍♂️ Maybe just adjust the edit text name?

[chriss158]

I did a quick test.
On my O+5T devices with android 10 i had no serious problems 👍 , but i noticed some things:

• I needed to reset my storage, to see the manage shortcuts link. I've updated the app from one of my PR beta builds.
• If i open the app by its normal app icon, the webview reloads every time.
• Every shortcut (1-5) can be pinned to the home screen. And also pinned shortcuts can be added at the "Pinned Shortcut category". Don't know if it's only me, but it's really confusing that you can maintain pinned shortcuts with two settings. I would separate those two features. "Add shortcuts", "Add pinned shortcuts". I know that way a user might maintain two shortcuts for the same destination, but i think that a user doesn't do this so often anyway.
• Maybe a shortcut should be added/edited in a extra screen, to reduce scrolling.
• For a pinned shortcut it would be ideal to list all in a listview where you can select it and edit the shortcut.

[chriss158]

Now that #1446 is merged I can confirm that entityId:<entity> does indeed load the more info panel with shortcuts. May need to rethink the webview path naming OR introduce different shortcut types to switch between the two. For this MVP though not sure if it needs to be changed as it still works 🤷‍♂️ Maybe just adjust the edit text name?

Maybe leave the edit field for now to not confuse the user by too many options.
As an alternative: Add a ? to the top right corner or maybe a ? directly to the edit text field, that will link to the companion docs.

[chriss158]

This condition is used really often. Maybe it is possible to refactor it as method.

[dshokouhi]

So the first case this condition is used is for the 5 hard coded dynamic shortcuts to show that they can be pinned (if supported) The next time this condition is used is to hide the pinned category if the users device does not support it. I didnt see a good way to refactor this since the underlying code is different

[dshokouhi]

actually there is more than 2 instances but has a different purpose, will need to see if i can refactor some of them

[chriss158]

Something like this:

Instead of

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && shortcutManager.isRequestPinShortcutSupported)

something like this one:

if (pinShortcutsSupported())

[dshokouhi]

Now that we are removing the ability to pin the dynamic shortcuts there is only one instance of this check :) So doesnt make sense but a lot less code now

[dshokouhi]

• I needed to reset my storage, to see the manage shortcuts link. I've updated the app from one of my PR beta builds.
• If i open the app by its normal app icon, the webview reloads every time.

That sounds to be expected if your updating from one PR build to another, webview reloading might be due to no background permission? I normally dont grant it myself when im beta testing a PR :)

• Every shortcut (1-5) can be pinned to the home screen. And also pinned shortcuts can be added at the "Pinned Shortcut category". Don't know if it's only me, but it's really confusing that you can maintain pinned shortcuts with two settings. I would separate those two features. "Add shortcuts", "Add pinned shortcuts". I know that way a user might maintain two shortcuts for the same destination, but i think that a user doesn't do this so often anyway.

So the reason there are 2 optoins is because dynamic shortcuts is in android 7.0 and pinned shortcuts is in android 8.0 so not all users will see everything depends on the device. Also dynamic shortcuts only show up under the app long press action and for that reason I opted to keep Add Shortcut and Pin Shortcut separate since its technically separate functionality eventhough shortcuts are identical. Renaming the label might be good to make it more clear but for users who only support dynamic they will only see dynamic controls and nothing related to pins.

• Maybe a shortcut should be added/edited in a extra screen, to reduce scrolling.

One thing we could do is to mimic what was done with pinned shortcuts as we show a listview of all pinned items, and put the amount of dynamic shortcuts fully in user control. I opted to do 5 fields to make it easy on us and the user.

• For a pinned shortcut it would be ideal to list all in a listview where you can select it and edit the shortcut.

This is already done but if you are using one of the 5 categories above it you won't see the listview, it has to be a new unique ID for it to be editable. I did this because all users on android 7+ will have access to those 5 shortcuts and users with android 8 have the option to add more. Once a new shortcut is added using the below category the listview will appear and populate. For the 5 shortcuts above we have hardcoded ID's to make it predictable in the app.

Maybe leave the edit field for now to not confuse the user by too many options.
As an alternative: Add a ? to the top right corner or maybe a ? directly to the edit text field, that will link to the companion docs.

I like linking to companion docs, might add a link under the instructions now that I think about it :)

[chriss158]

That sounds to be expected if your updating from one PR build to another, webview reloading might be due to no background permission? I normally dont grant it myself when im beta testing a PR :)

The debug app has the same permissions as the productive app. Even if i open the app instantly after i "closed" it by going to the homescreen, the webview will reload. Maybe this is normal in the debug app? Dunno.

So the reason there are 2 optoins is because dynamic shortcuts is in android 7.0 and pinned shortcuts is in android 8.0 so not all users will see everything depends on the device. Also dynamic shortcuts only show up under the app long press action and for that reason I opted to keep Add Shortcut and Pin Shortcut separate since its technically separate functionality eventhough shortcuts are identical. Renaming the label might be good to make it more clear but for users who only support dynamic they will only see dynamic controls and nothing related to pins.

Yes i would keep it separate. But for every dynamic shortcut you can also create a pinned shortcut Update Pinned Shortcut Data. I would remove that, and let the user only create a pinned shortcut in the Pinned Shortcut Category

I like linking to companion docs, might add a link under the instructions now that I think about it :)

That would be also a possible solution for other areas in the settings.

[dshokouhi]

Yes i would keep it separate. But for every dynamic shortcut you can also create a pinned shortcut Update Pinned Shortcut Data. I would remove that, and let the user only create a pinned shortcut in the Pinned Shortcut Category

Ok will keep it separate to lessen confusion.