Skip to content

Commit 748a034

Browse files
xsahil03xxsahil03x
committed
update README.md
Signed-off-by: xsahil03x <[email protected]>
1 parent 061f8b6 commit 748a034

File tree

6 files changed

+221
-27
lines changed

6 files changed

+221
-27
lines changed

‎README.md

+219-25
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,233 @@
1-
<!--
2-
This README describes the package. If you publish this package to pub.dev,
3-
this README's contents appear on the landing page for your package.
1+
A simple widget to add trigger based autocomplete functionality to your app.
42

5-
For information about how to write a good package README, see the guide for
6-
[writing package pages](https://dart.dev/guides/libraries/writing-package-pages).
3+
[![Open Source Love](https://badges.frapsoft.com/os/v1/open-source.svg?v=102)](https://opensource.org/licenses/MIT) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/xsahil03x/multi_trigger_autocomplete/blob/master/LICENSE) [![Dart CI](https://github.com/xsahil03x/multi_trigger_autocomplete/workflows/multi_trigger_autocomplete/badge.svg)](https://github.com/xsahil03x/multi_trigger_autocomplete/actions) [![CodeCov](https://codecov.io/gh/xsahil03x/multi_trigger_autocomplete/branch/master/graph/badge.svg)](https://codecov.io/gh/xsahil03x/multi_trigger_autocomplete) [![Version](https://img.shields.io/pub/v/multi_trigger_autocomplete.svg)](https://pub.dartlang.org/packages/multi_trigger_autocomplete)
4+
<p>
5+
<img src="asset/package_demo.gif" alt="An animated image of the MultiTriggerAutocomplete" height="400"/>
6+
</p>
77

8-
For general information about developing packages, see the Dart guide for
9-
[creating packages](https://dart.dev/guides/libraries/create-library-packages)
10-
and the Flutter guide for
11-
[developing packages and plugins](https://flutter.dev/developing-packages).
12-
-->
8+
## 💻 Installation
139

14-
TODO: Put a short description of the package here that helps potential users
15-
know whether this package might be useful for them.
10+
Add the following to your `pubspec.yaml` and replace `[version]` with the latest version:
1611

17-
## Features
12+
```yaml
13+
dependencies:
14+
multi_trigger_autocomplete: ^[version]
15+
```
16+
17+
## ❔ Usage
18+
19+
To use this package you must first wrap your top most widget
20+
with [Portal](https://pub.dev/documentation/flutter_portal/latest/flutter_portal/Portal-class.html) as this package
21+
uses [flutter_portal](https://pub.dev/packages/flutter_portal)
22+
to show the options view.
23+
24+
(Credits to: [Remi Rousselet](https://github.com/rrousselGit/flutter_portal))
25+
26+
> `Portal`, is the equivalent of [Overlay].
27+
>
28+
> This widget will need to be inserted above the widget that needs to render
29+
> _under_ your overlays.
30+
>
31+
> If you want to display your overlays on the top of _everything_, a good place
32+
> to insert that `Portal` is above `MaterialApp`:
33+
>
34+
> ```dart
35+
> Portal(
36+
> child: MaterialApp(
37+
> ...
38+
> )
39+
> );
40+
> ```
41+
>
42+
> (works for `CupertinoApp` too)
43+
>
44+
> This way `Portal` will render above everything. But you could place it
45+
> somewhere else to change the clip behavior.
46+
47+
Import the package:
48+
49+
```dart
50+
import 'package:multi_trigger_autocomplete/multi_trigger_autocomplete.dart';
51+
```
52+
53+
Use the widget:
54+
55+
```dart
56+
MultiTriggerAutocomplete(
57+
optionsAlignment: OptionsAlignment.topStart,
58+
autocompleteTriggers: [
59+
// Add the triggers you want to use for autocomplete
60+
AutocompleteTrigger(
61+
trigger: '@',
62+
optionsViewBuilder: (context, autocompleteQuery, controller) {
63+
return MentionAutocompleteOptions(
64+
query: autocompleteQuery.query,
65+
onMentionUserTap: (user) {
66+
final autocomplete = MultiTriggerAutocomplete.of(context);
67+
return autocomplete.acceptAutocompleteOption(user.id);
68+
},
69+
);
70+
},
71+
),
72+
AutocompleteTrigger(
73+
trigger: '#',
74+
optionsViewBuilder: (context, autocompleteQuery, controller) {
75+
return HashtagAutocompleteOptions(
76+
query: autocompleteQuery.query,
77+
onHashtagTap: (hashtag) {
78+
final autocomplete = MultiTriggerAutocomplete.of(context);
79+
return autocomplete
80+
.acceptAutocompleteOption(hashtag.name);
81+
},
82+
);
83+
},
84+
),
85+
AutocompleteTrigger(
86+
trigger: ':',
87+
optionsViewBuilder: (context, autocompleteQuery, controller) {
88+
return EmojiAutocompleteOptions(
89+
query: autocompleteQuery.query,
90+
onEmojiTap: (emoji) {
91+
final autocomplete = MultiTriggerAutocomplete.of(context);
92+
return autocomplete.acceptAutocompleteOption(
93+
emoji.char,
94+
// Passing false as we don't want the trigger [:] to
95+
// get prefixed to the option in case of emoji.
96+
keepTrigger: false,
97+
);
98+
},
99+
);
100+
},
101+
),
102+
],
103+
// Add the text field widget you want to use for autocomplete
104+
fieldViewBuilder: (context, controller, focusNode) {
105+
return Padding(
106+
padding: const EdgeInsets.all(8.0),
107+
child: ChatMessageTextField(
108+
focusNode: focusNode,
109+
controller: controller,
110+
),
111+
);
112+
},
113+
),
114+
```
115+
116+
## 🔅 Demo
18117

19-
TODO: List what your package can do. Maybe include images, gifs, or videos.
118+
| Mention Autocomplete | Hashtag Autocomplete | Emoji Autocomplete |
119+
|----------------------------------------------------------------------|-----------------------------------------------------------------------------|-------------------------------------------------------------------------|
120+
| <img src="asset/mention_demo.gif" height="400" alt="Mention Autocomplete"/> | <img src="asset/hashtag_demo.gif" height="400" alt="Hashtag Autocomplete"/> | <img src="asset/emoji_demo.gif" height="400" alt="Emoji Autocomplete"/> |
20121

21-
## Getting started
122+
## 🎨 Customization
22123

23-
TODO: List prerequisites and provide or point to information on how to
24-
start using the package.
124+
### MultiTriggerAutocomplete
25125

26-
## Usage
126+
```dart
127+
MultiTriggerAutocomplete(
128+
// Defines the autocomplete trigger that will be used to match the
129+
// text.
130+
autocompleteTriggers: autocompleteTriggers,
131+
132+
// Defines the alignment of the options view relative to the
133+
// fieldView.
134+
//
135+
// By default, the options view is aligned to the bottom of the
136+
// fieldView.
137+
optionsAlignment: OptionsAlignment.topStart,
138+
139+
// Defines the width to make the options as a multiple of the width
140+
// of the fieldView.
141+
//
142+
// Setting this to 1 makes the options view width matches the width
143+
// of the fieldView.
144+
//
145+
// Use null to remove this constraint.
146+
optionsWidthFactor: 1.0,
147+
148+
// Defines the duration of the debounce period for the
149+
// [TextEditingController].
150+
//
151+
// This is the time between the last character typed and the matching
152+
// is performed.
153+
debounceDuration: const Duration(milliseconds: 350),
154+
155+
// Defines the initial value to set in the internal
156+
// [TextEditingController].
157+
//
158+
// This value will be ignored if [TextEditingController] is provided.
159+
initialValue: const TextEditingValue(text: 'Hello'),
160+
161+
// Defines the [TextEditingController] that will be used for the
162+
// fieldView.
163+
//
164+
// If this parameter is provided, then [focusNode] must also be
165+
// provided.
166+
textEditingController: TextEditingController(text: 'Hello'),
167+
168+
// Defines the [FocusNode] that will be used for the fieldView.
169+
//
170+
// If this parameter is provided, then [textEditingController] must
171+
// also be provided.
172+
focusNode: FocusNode(),
173+
174+
// Defines the fieldView that will be used to input the text.
175+
//
176+
// By default, a [TextFormField] is used.
177+
fieldViewBuilder: (context, controller, focusNode) {
178+
return TextField(
179+
controller: controller,
180+
focusNode: focusNode,
181+
);
182+
},
183+
),
184+
```
27185

28-
TODO: Include short and useful examples for package users. Add longer examples
29-
to `/example` folder.
186+
### AutocompleteTrigger
30187

31188
```dart
32-
const like = 'sample';
189+
AutocompleteTrigger(
190+
// The trigger string/character that will be used to trigger the
191+
// autocomplete.
192+
trigger: '@',
193+
194+
// If true, the [trigger] should only be recognised at
195+
// the start of the input text.
196+
//
197+
// valid example: "@luke hello"
198+
// invalid example: "Hello @luke"
199+
triggerOnlyAtStart: false,
200+
201+
// If true, the [trigger] should only be recognised after
202+
// a space.
203+
//
204+
// valid example: "@luke", "Hello @luke"
205+
// invalid example: "Hello@luke"
206+
triggerOnlyAfterSpace: true,
207+
208+
// A minimum number of characters can be provided to only show
209+
// suggestions after the user has input enough characters.
210+
//
211+
// example:
212+
// "Hello @l" -> Shows zero suggestions.
213+
// "Hello @lu" -> Shows suggestions for @lu.
214+
minimumRequiredCharacters: 2,
215+
216+
// The options view builder is used to build the options view
217+
// that will be shown when the [trigger] is detected.
218+
optionsViewBuilder: (context, autocompleteQuery, controller) {
219+
return MentionAutocompleteOptions(
220+
query: autocompleteQuery.query,
221+
onMentionUserTap: (user) {
222+
// Accept the autocomplete option.
223+
final autocomplete = MultiTriggerAutocomplete.of(context);
224+
return autocomplete.acceptAutocompleteOption(user.id);
225+
},
226+
);
227+
},
228+
)
33229
```
34230

35-
## Additional information
231+
## 📃 License
36232

37-
TODO: Tell users more about the package: where to find more information, how to
38-
contribute to the package, how to file issues, what response they can expect
39-
from the package authors, and more.
233+
[MIT License](LICENSE)

‎asset/emoji_demo.gif

2.23 MB
Loading

‎asset/hashtag_demo.gif

2.25 MB
Loading

‎asset/mention_demo.gif

1.28 MB
Loading

‎asset/package_demo.gif

6.1 MB
Loading

‎pubspec.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name: multi_trigger_autocomplete
22
homepage: https://github.com/xsahil03x/multi_trigger_autocomplete
3-
description: Stream Chat official Flutter SDK. Build your own chat experience using Dart and Flutter.
4-
version: 0.0.1
3+
description: A simple widget to add trigger based autocomplete functionality to your app.
4+
version: 1.0.0
55
repository: https://github.com/xsahil03x/multi_trigger_autocomplete
66
issue_tracker: https://github.com/xsahil03x/multi_trigger_autocomplete/issues
77

0 commit comments

Comments
 (0)