From 90af6242174cfd66958347bb7644dc1b78833863 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Wed, 7 Jul 2021 17:00:47 -0400 Subject: [PATCH] Add utilities page with input shims --- Utilities.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 Utilities.md diff --git a/Utilities.md b/Utilities.md new file mode 100644 index 0000000..748b861 --- /dev/null +++ b/Utilities.md @@ -0,0 +1,21 @@ +There are a number of utilities that help make Ionic Framework work better. This guide will go over how each utility works and the role they play in making Ionic Framework function. + +## Input Shims + +Our input shims can be found at `core/src/utils/input-shims`. These shims are enabled inside of the `ion-app` component, meaning you need to use `ion-app` in order to have these utilities activate. The main entry point for these utilities can be found in the `startInputShims` function in `core/src/utils/input-shims/input-shims.ts`. Below lists all of the shims we use. + +### Hide Caret + +When an input is focused, this utility will hide the caret when a user scrolls the page. Mobile browser engines such as WebKit have issues with the caret not scrolling with the input, so rather than have that visual glitch there we hide the caret while scrolling altogether. The reason this glitch happens is because on iOS the caret is not part of the webview, it is part of the operating system so it is does not know the scrolling position. Chromium used to have this issue, but the Chromium team has since fixed it. + +### Input Blurring + +When tapping outside of an input, the input should blur and the keyboard should hide. However, that should not happen when the user attempts to scroll, otherwise the input would be blurred at the slightest of scroll gestures. This utility ensures that tapping outside of an input blurs the input, unless the user is scrolling. + +### Scroll Assist + +A common pain point in mobile apps is the keyboard. Web APIs do not provide a great deal of control over the on screen keyboard, so an issue you will see frequently is the keyboard covering an input when tapping into it. Our scroll assist utility does its best to adjust the content scroll position so that the focused input is always shown above the keyboard. Because we do not always know the exact height of the keyboard, sometimes the content will be scrolled more than it needs. + +### Scroll Padding + +Typically when the keyboard opens on Capacitor or Cordova, the webview will resize to 100% of the screen height minus the height of the keyboard. This gives scroll assist enough scrolling real estate to adjust the content scroll position so that the focused input shows above the keyboard. Developers are given the ability to disable this webview resizing. When that happens, scroll assist will not have enough scrolling real estate to adjust the content scroll position. The scroll padding utility accounts for this by adding `padding-bottom` to the scrollable content roughly equal to the height of the keyboard. \ No newline at end of file