Skip to content

Commit 21f9061

Browse files
OmbuwebOmbuweb
authored
docs(iqkeyboardmanager): update (#456)
1 parent bc7e4f1 commit 21f9061

File tree

1 file changed

+57
-30
lines changed

1 file changed

+57
-30
lines changed

‎packages/iqkeyboardmanager/README.md

Lines changed: 57 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,65 @@
11
# @nativescript/iqkeyboardmanager
22

3-
A NativeScript wrapper for the popular [IQKeyboardManager](https://cocoapods.org/pods/IQKeyboardManager) iOS framework, which provides an elegant solution for preventing the iOS keyboard from covering `UITextView` controls.
4-
5-
![Example of using the IQKeyBoardManager NativeScript plugin on an iOS device](https://github.com/raw/NativeScript/nativescript-IQKeyboardManager/master/screenshot.gif)
6-
73
## Contents
4+
* [Intro](#intro)
85
* [Installation](#installation)
9-
* [Usage](#usage)
6+
* [Use @nativescript/iqkeyboardmanager](#use-nativescriptiqkeyboardmanager)
107
* [Core](#core)
118
* [Angular](#angular)
129
* [Vue](#vue)
1310
* [Svelte](#svelte)
1411
* [React](#react)
15-
* [Adding a hint text to a TextView's accessory bar](#adding-a-hint-text-to-a-textviews-accessory-bar)
12+
* [Adding a hint text to the TextView accessory bar](#adding-a-hint-text-to-the-textview-accessory-bar)
1613
* [Core](#core-1)
1714
* [Angular](#angular-1)
1815
* [Vue](#vue-1)
1916
* [Svelte](#svelte-1)
20-
17+
* [Demo app](#demo-apps)
2118
* [Tweaking the appearance and behavior](#tweaking-the-appearance-and-behavior)
2219
* [Multi-factor one-time code auto-fill](#multi-factor-one-time-code-auto-fill)
23-
* [Documentation](#documentation)
20+
* [Native documentation](#native-documentation)
2421
* [Maintainers](#maintainers)
2522
* [License](#license)
2623

24+
## Intro
25+
26+
A NativeScript wrapper for the popular [IQKeyboardManager](https://cocoapods.org/pods/IQKeyboardManager) iOS framework, which provides an elegant solution for preventing the iOS keyboard from covering `UITextView` controls.
27+
28+
![Example of using the IQKeyBoardManager NativeScript plugin on an iOS device](https://github.com/raw/NativeScript/nativescript-IQKeyboardManager/master/screenshot.gif)
29+
30+
2731
## Installation
2832

33+
To install the plugin, run the following command from the root folder of your project:
34+
2935
```cli
3036
npm install @nativescript/iqkeyboardmanager
3137
```
3238

33-
## Usage
39+
## Use @nativescript/iqkeyboardmanager
3440

35-
Related text fields should be siblings for the IQKeyboardManager to automatically
41+
The following sections describe how to use the `@nativescript/iqkeyboardmanager` plugin in the different flavors that NativeScript supports.
42+
43+
> **Note** Make related text fields siblings for the IQKeyboardManager to automatically
3644
add the `previous`(`<`) and `next`(`>`) buttons to the accessory bar. The user can then use those buttons to jump back and forth.
3745
3846
### Core
39-
To register the plugin in core/plain NativeScript, use the `xmlns` attribute to add it to the xml namespace.
47+
1. Register the plugin namespace with Page's `xmlns` attribute under a prefix( `IQKeyboardManager` for example) that you can use to access the `PreviousNextView`.
48+
49+
```xml
50+
<Page xmlns:IQKeyboardManager="@nativescript-iqkeyboardmanager">
51+
```
52+
2. Access the `PreviousNextView` using the prefix.
53+
54+
```xml
55+
<IQKeyboardManager:PreviousNextView><!-- add this 'wrapper' to enable those previous / next buttons -->
56+
<StackLayout>
57+
<TextField hint="Email"/>
58+
<TextField hint="Password"/>
59+
</StackLayout>
60+
</IQKeyboardManager:PreviousNextView>
61+
```
62+
The 2 preceding steps result in the code below:
4063

4164
```xml
4265
<Page xmlns="http://schemas.nativescript.org/tns.xsd" xmlns:IQKeyboardManager="@nativescript-iqkeyboardmanager">
@@ -53,14 +76,15 @@ To register the plugin in core/plain NativeScript, use the `xmlns` attribute to
5376

5477
### Angular
5578

56-
Register the `PreviousNextView` element in the `.modules.ts` file where you want to use this feature (or the `app.module.ts`).
79+
1. Register the `PreviousNextView` element in the `.modules.ts` file where you want to use this feature (or the `app.module.ts` for global access).
80+
5781
```ts
5882
import { registerElement } from '@nativescript/angular';
5983
import { PreviousNextView } from '@nativescript/iqkeyboardmanager';
6084
registerElement('PreviousNextView', () => PreviousNextView);
6185
```
6286

63-
Then use the element in the markup as follows:
87+
2. Add `PreviousNextView` to the markup as follows:
6488

6589
```html
6690
<ScrollView>
@@ -76,12 +100,12 @@ Then use the element in the markup as follows:
76100

77101
### Vue
78102

79-
Register the component by adding the following code to the `app.ts` file.
103+
1. Register `PreviousNextView` by adding the following code to the `app.ts` file.
80104

81105
```ts
82106
registerElement('PreviousNextView', () => require('@nativescript/iqkeyboardmanager').PreviousNextView);
83107
```
84-
Then use it in a markup file.
108+
2. Use `PreviousNextView` in markup.
85109

86110
```xml
87111
<ScrollView>
@@ -97,12 +121,12 @@ Then use it in a markup file.
97121

98122
### Svelte
99123

100-
Register the component by adding the following code to the `app.ts` file.
124+
1. Register `PreviousNextView` by adding the following code to the `app.ts` file.
101125

102126
```ts
103-
registerNativeViewElement('PreviousNextView', () => require('@nativescript/iqkeyboardmanager').PreviousNextView);
127+
registerNativeViewElement('previousNextView', () => require('@nativescript/iqkeyboardmanager').PreviousNextView);
104128
```
105-
Then use it.
129+
2. Add `previousNextView` to markup.
106130

107131
```xml
108132
<previousNextView><!-- add this 'wrapper' to enable those previous / next buttons -->
@@ -112,8 +136,9 @@ Then use it.
112136
</stackLayout>
113137
</previousNextView>
114138
```
139+
For a demo app, visit [NativeScript Svelte: IQ Keyboard Manager](https://stackblitz.com/edit/nativescript-stackblitz-templates-rygnsk?file=app/components/Home.svelte).
115140

116-
### Adding a hint text to a TextView's accessory bar
141+
### Adding a hint text to the TextView accessory bar
117142

118143
By default, when a `TextField` is focused, the keyboard manager shows the field's hint label in the accessory bar above the keyboard.
119144

@@ -168,11 +193,10 @@ Register the component.
168193
```javascript
169194
.registerNativeViewElement('textViewWithHint', () => require('@nativescript/iqkeyboardmanager').TextViewWithHint);
170195
```
171-
You can find the complete demo at [NativeScript Svelte](https://stackblitz.com/edit/nativescript-stackblitz-templates-rygnsk?file=app/components/Home.svelte)
172196

173197
### React
174198

175-
1. Register the component.
199+
1. Register the `TextViewWithHint` component.
176200

177201
```ts
178202
interface PreviewNextViewAttributes extends ViewAttributes {
@@ -197,7 +221,7 @@ registerElement("previousNextView", ()=> require("@nativescript/iqkeyboardmanage
197221
registerElement("textViewWithHint", ()=> require("@nativescript/iqkeyboardmanager").TextViewWithHint)
198222

199223
```
200-
2. Use it in markup:
224+
2. Use `TextViewWithHint` in markup:
201225
```xml
202226
<previousNextView>
203227
<stackLayout>
@@ -209,11 +233,18 @@ registerElement("textViewWithHint", ()=> require("@nativescript/iqkeyboardmanage
209233
</stackLayout>
210234
</previousNextView>
211235
```
236+
### Demo apps
237+
238+
The following are links to the plugin demo apps in the different JS flavors.
212239

213-
See the full example at [NativeScript React: iqkeyboardmanager](https://stackblitz.com/edit/nativescript-stackblitz-templates-5uygfj?file=src/components/ScreenOne.tsx)
240+
* [NativeScript TS: IQ Keyboard Manager](https://stackblitz.com/edit/nativescript-stackblitz-templates-sia8th?file=app/main-page.xml).
241+
* [NativeScript Svelte: IQ Keyboard Manager](https://stackblitz.com/edit/nativescript-stackblitz-templates-rygnsk?file=app/components/Home.svelte)
242+
* [NativeScript React: IQ Keyboard Manager](https://stackblitz.com/edit/nativescript-stackblitz-templates-5uygfj?file=src/components/ScreenOne.tsx)
214243

215244

216-
#### Tweaking the appearance and behavior
245+
### Tweaking the appearance and behavior
246+
247+
To tweak the appearance and behavior of `PreviousNextView`, follow the steps below:
217248

218249
1. Add the following path to your app’s `references.d.ts` file.
219250

@@ -235,17 +266,13 @@ iqKeyboard.overrideKeyboardAppearance = true;
235266
iqKeyboard.keyboardAppearance = UIKeyboardAppearance.Dark;
236267
```
237268

238-
For a full example, check out the example on StackBlitz at any of the following links.
239-
* [NativeScript TypeScript](https://stackblitz.com/edit/nativescript-stackblitz-templates-sia8th?file=app/main-page.xml)
240-
241-
242269
<img src="https://github.com/tjvantoll/nativescript-IQKeyboardManager/raw/master/demo.gif" width="320px"/>
243270

244271
#### Multi-factor one-time code auto-fill
245272

246273
iOS has a feature where a text field's QuickType search suggestion bar can suggest `one-time` code values for multi-factor authentication that were texted to your device.
247274

248-
If the field is identified as a `one-time` code field, the suggestion will appear for about 3 minutes after being received. The user simply has to tap the suggestion to fill in the value — no short-term memorization or copy/paste gestures required. Examples of message formats are:
275+
If the field is identified as a `one-time` code field, the suggestion will appear for about 3 minutes after being received. The user simply has to tap the suggestion to fill in the value — no short-term memorization or copy/paste gestures are required. Examples of message formats are:
249276

250277
- 123456 is your App Name code.
251278
- 123456 is your App Name login code.
@@ -269,7 +296,7 @@ if (mfaCodeField !== null && mfaCodeField.ios) {
269296

270297
There are other `textContentType` values you might want to use. You can read more about the property in [this article](https://medium.com/developerinsider/ios12-password-autofill-automatic-strong-password-and-security-code-autofill-6e7db8da1810).
271298

272-
## Documentation
299+
## Native documentation
273300

274301
For more details on how IQKeyboardManager works, including more detailed API documentation, refer to [the library's CocoaPod page](https://cocoapods.org/pods/IQKeyboardManager).
275302

0 commit comments

Comments
 (0)