Merge pull request #77 from CharlesMangwa/main

Implement internationalization `PapercupsIntl()` + some fixes

CHANGELOG.md

@@ -36,11 +36,11 @@ These releases are maintenance related, addressing some issues found on pub.dev
 ## [2.0.0] - 16/02/2021.
 
 # 🎉 2.0 has landed!
-This release brings major changes to how this package works. Most importantly, it is now completely native, ensuring speed and performace along with more customisability. This will also enable new features such as chat message notifications, in-app overlays, local message retention and many others, make sure to leave suggestions [here](https://github.com/papercups-io/papercups_flutter) for what to build next.
+This release brings major changes to how this package works. Most importantly, it is now completely native, ensuring speed and performance along with more customisability. This will also enable new features such as chat message notifications, in-app overlays, local message retention and many others, make sure to leave suggestions [here](https://github.com/papercups-io/papercups_flutter) for what to build next.
 
 ### New Features
 * Native Dart implementation!
-* Full themeing control w/gradients.
+* Full theming control w/gradients.
 * Full Internationalization control - every part can be set to any language.
 * Dark mode
 * Added elevation option to message box
@@ -71,7 +71,7 @@ Thanks to [@Fiyiin](https://github.com/Fiyiin) for helping me out building this
 
 ## [0.2.2] - 30/11/2020.
 
-* ⚡️ Performance imporvements to `genIframeUrl`
+* ⚡️ Performance improvements to `genIframeUrl`
 * ✨ Added `toMap()` and `toJsonString()` to the classes, better URI generation.
 
 ## [0.2.1] - 26/11/2020.
@@ -85,7 +85,7 @@ Thanks to [@Fiyiin](https://github.com/Fiyiin) for helping me out building this
 
 ### Enhancements
 * 📝 Improved docs with higher coverage and syntax highlighting (Thanks to @Immortalin).
-* ⚡️ Web widget is now constant. Better preformance.
+* ⚡️ Web widget is now constant. Better performance.
 * ✨ Update example to show new features.
 
 ## [0.1.4] - 23/11/2020.
@@ -94,7 +94,7 @@ Thanks to [@Fiyiin](https://github.com/Fiyiin) for helping me out building this
 
 ## [0.1.3] - 23/11/2020.
 
-* 🐛 Add platfromView stub, should fix platfrom id and pub score
+* 🐛 Add platformView stub, should fix platform id and pub score
 
 ## [0.1.2] - 22/11/2020.
 

README.md

@@ -21,50 +21,68 @@ Integration with your app requires just a few lines of code, add the following w
 import 'package:papercups_flutter/papercups_flutter.dart';
 
 PaperCupsWidget(
-  props: Props(
+ props: Props(
  accountId: "xxxxxxxx-xxxxxxx-xxxx-xxxxxx", //Your account id goes here.
-  ),
+ ),
 ),
  
 ```
 That should get you up and running in just a few seconds ⚡️.
 
 ## Configuration
 
-### Available PaperCupsWidget arguments
+### Available `PaperCupsWidget` arguments
 | Parameter | Type | Value | Default |
 | :--- | :--- | :----- | :------ |
-| **`props`** | `Props` | **Required**, here is where all of the config for the chat is contained.| N/A |
 | **`dateLocale`** | `String` |Locale for the date, use the locales from the `intl` package.| `"en-US"` |
-| **`timeagoLocale`** | `dynamic` | Check https://github.com/andresaraujo/timeago.dart/tree/master/timeago/lib/src/messages for the available classes.| N/A |
-| **`sendingText`** | `String` | Text to show while message is sending.| `Sending...` |
-| **`sentText`** | `String` | Text to show when the messgae is sent.| `Sent` |
 | **`floatingSendMessage`** | `bool` | Wether to have the message box floating.| `false` |
+| **`props`** | `Props` | **Required**, here is where all of the config for the chat is contained.| N/A |
+| **`timeagoLocale`** | `dynamic` | Check [`timeago` messages](https://github.com/andresaraujo/timeago.dart/tree/master/timeago/lib/src/messages) for the available classes.| N/A |
 
 
-### Available Props paramaters
+### Available `Props` parameters
 | Prop | Type | Value | Default |
 | :--- | :--- | :----- | :------ |
-| **`accountId`** | `string` | **Required**, your Papercups account token | N/A |
-| **`title`** | `string` | The title in the header of your chat widget | Welcome! |
-| **`subtitle`** | `string` | The subtitle in the header of your chat widget | How can we help you? |
-| **`newMessagePlaceholder`** | `string` | The placeholder text in the new message input | Start typing... |
-| **`primaryColor`** | `Color` | The theme color of your chat widget | `Theme.of(context).primaryColor` without alpha |
-| **`primaryGradient`** | `Gradient` | Gradient to specify, should be used instead of primaryColor, DO NOT USE BOTH. | N/A |
-| **`greeting`** | `string` | An optional initial message to greet your customers with | N/A |
+| **`accountId`** | `String` | **Required**, your Papercups account token | N/A |
+| **`baseUrl`** | `String` | The base URL of your API if you're self-hosting Papercups. Ensure you do not include the protocol (https) of a trailing dash (/) | app.papercups.io |
 | **`customer`** | `CustomerMetadata` | Identifying information for the customer, including `name`, `email`, `external_id`, and `metadata` (for any custom fields) | N/A |
-| **`baseUrl`** | `string` | The base URL of your API if you're self-hosting Papercups. Ensure you do not include the protocol (https) of a trailing dash (/) | app.papercups.io |
+| **`primaryColor`** | `Color` | The theme color of your chat widget | `Theme.of(context).primaryColor` without alpha |
+| **`primaryGradient`** | `Gradient` | Gradient to specify, should be used instead of primaryColor, **DO NOT USE BOTH** | N/A |
 | **`requireEmailUpfront`** | `boolean` | If you want to require unidentified customers to provide their email before they can message you | `false` |
-| **`companyName`** | `String` | Company name to show on greeting | `"Bot"` |
-| **`enterEmailPlaceholer`** | `String` | This is the placeholder text in the email input section | `"Enter your email"` |
+| **`translations`** | `PapercupsIntl` | If you want to override the default `EN` translations displayed by the widget | `PapercupsIntl()` |
 
-### Available CustomerMetaData paramaters
+### Available `CustomerMetaData` parameters
 | Parameters | Type | Value | Default |
 | :--- | :--- | :----- | :------ |
-| **`email`** | `string` | The customer's email| N/A |
-| **`externalId`** | `string` | The customer's external ID | N/A |
-| **`name`** | `string` | The customer's name | N/A |
-| **`otherMetadata`** | `Map<String, String>` | Extra metadata to pass such as OS info. | N/A |
+| **`email`** | `String` | The customer's email| N/A |
+| **`externalId`** | `String` | The customer's external ID | N/A |
+| **`name`** | `String` | The customer's name | N/A |
+| **`otherMetadata`** | `Map<String, String>` | Extra metadata to pass such as OS info | N/A |
+
+### Available `PapercupsIntl` parameters
+| Parameters | Type | Value | Default |
+| :--- | :--- | :----- | :------ |
+| **`attachmentNamePlaceholder`** | `String` | Text displayed when an attachment doesn't have a file name | `"No Name"` |
+| **`attachmentUploadErrorText`** | `String` | Error message displayed when an attachment could not be uploaded | `"Failed to upload attachment"` |
+| **`attachmentUploadedText`** | `String` | Text displayed when an attachment has been uploaded | `"Attachment uploaded"` |
+| **`attachmentUploadingText`** | `String` | Text displayed when an attachment is been uploaded | `"Uploading..."` |
+| **`companyName`** | `String` | Company name to show on greeting | `"Bot"` |
+| **`enterEmailPlaceholder`** | `String` | This is the placeholder text in the email input section | `"Enter your email"` |
+| **`fileText`** | `String` | Text displayed on the tile where the user decides to upload a file | `"File"` |
+| **`greeting`** | `String` | An optional initial message to greet your customers with | N/A |
+| **`historyFetchErrorText`** | `String` | Error message displayed when the customer history couldn't be fetched | `"There was an issue retrieving your details. Please try again!` |
+| **`imageText`** | `String` | Text displayed on the tile where the user decides to upload an image | `"Image` |
+| **`loadingText`** | `String` | Text displayed when the chat is loading | `"Loading..."` |
+| **`newMessagePlaceholder`** | `String` | The placeholder text in the new message input | `"Start typing..."` |
+| **`noConnectionText`** | `String` | The placeholder text in the new message input | `"No Connection"` |
+| **`retryButtonLabel`** | `String` | Label used in the retry button when the chat history couldn't be fetched | `"Retry"` |
+| **`sendingText`** | `String` | Text to show while message is sending | `"Sending..."` |
+| **`sentText`** | `String` | Text to show when the message is sent | `"Sent"` |
+| **`subtitle`** | `String` | The subtitle in the header of your chat widget | `"How can we help you?"` |
+| **`textCopiedText`** | `String` | Text displayed when a text has been copied after long press on a chat bubble | `"Text copied to clipboard"` |
+| **`title`** | `String` | The title in the header of your chat widget | `"Welcome!"` |
+| **`uploadedText`** | `String` | Text displayed after the percentage value of an attachment being uploaded | `"uploaded"` |
+
 
 ## Supporters
 [![Stargazers repo roster for @papercups-io/papercups_flutter](https://reporoster.com/stars/papercups-io/papercups_flutter)](https://github.com/papercups-io/papercups_flutter/stargazers) [![Forkers repo roster for @papercups-io/papercups_flutter](https://reporoster.com/forks/papercups-io/papercups_flutter)](https://github.com/papercups-io/papercups_flutter/network/members)

example/lib/main.dart

@@ -307,11 +307,13 @@ class _MyHomePageState extends State<MyHomePage> {
  },
  props: Props(
  accountId: "843d8a14-8cbc-43c7-9dc9-3445d427ac4e",
- title: titleController.text,
+ translations: PapercupsIntl(
+ title: titleController.text,
+ subtitle: subtitleController.text,
+ greeting:
+ "Hello, have any questions or feedback? Let me know below!",
+ ),
  primaryColor: color,
- greeting:
- "Hello, have any questions or feedback? Let me know below!",
- subtitle: subtitleController.text,
  customer: CustomerMetadata(
  email: "[email protected]",
  externalId: "123",

lib/models/classes.dart

@@ -4,7 +4,7 @@ import 'package:flutter/material.dart';
 
 /// Customer Metadata, this contains the customer's information.
 class CustomerMetadata {
- //Decalration of variables.
+ //Declaration of variables.
 
  /// This is the name of your user.
  String? name;
@@ -40,22 +40,113 @@ class CustomerMetadata {
  }
 }
 
-/// This contains all the possible configurations for the chat widget.
-class Props {
- //Decalration of variables.
+/// This class contains all the text that can be displayed by the widget.
+class PapercupsIntl {
+ /// Company name to show on greeting.
+ final String companyName;
 
  /// This is the top section of the widget, normally a welcome text.
- String title;
+ final String title;
+
+ /// This is a smaller piece of text under the title.
+ final String subtitle;
+
+ /// This is the first message sent by you during the conversation.
+ final String? greeting;
+
+ /// Text to show while message is sending.
+ ///
+ /// Default is `"Sending..."`
+ final String sendingText;
+
+ /// Text to show when the message is sent
+ ///
+ /// Default is `"Sent"` (time will be added after).
+ final String sentText;
+
+ /// This is the placeholder text in the input section.
+ final String newMessagePlaceholder;
+
+ /// This is the placeholder text in the email input section.
+ final String enterEmailPlaceholder;
+
+ /// Error message displayed when the customer history couldn't be fetched.
+ final String historyFetchErrorText;
+
+ /// Error message displayed when an attachment could not be uploaded.
+ final String attachmentUploadErrorText;
+
+ /// Text displayed when an attachment has been uploaded.
+ final String attachmentUploadedText;
+
+ /// Text displayed when an attachment is been uploaded.
+ final String attachmentUploadingText;
+
+ /// Text displayed after the percentage value of an attachment being uploaded.
+ final String uploadedText;
+
+ /// Text displayed when a text has been copied after long press on a chat bubble.
+ final String textCopiedText;
+
+ /// Text displayed when the chat is loading.
+ final String loadingText;
+
+ /// Text displayed when an attachment doesn't have a file name.
+ final String attachmentNamePlaceholder;
+
+ /// Text displayed when there's no Internet connection.
+ final String noConnectionText;
+
+ /// Label used in the retry button when the chat history couldn't be fetched.
+ final String retryButtonLabel;
+
+ /// Text displayed on the tile where the user decides to upload a file.
+ final String fileText;
+
+ /// Text displayed on the tile where the user decides to upload an image.
+ final String imageText;
+
+ /// This text will be shown if the showAgentAvailability is true and you are online.
+ //String agentAvailableText;
+
+ /// This text will be shown if the showAgentAvailability is true and you are offline.
+ //String agentUnavailableText;
+
+ const PapercupsIntl({
+ this.historyFetchErrorText =
+ "There was an issue retrieving your details. Please try again!",
+ this.attachmentUploadErrorText = 'Failed to upload attachment',
+ // this.agentUnavailableText = "We're away at the moment.",
+ this.attachmentUploadedText = 'Attachment uploaded',
+ this.textCopiedText = "Text copied to clipboard",
+ this.attachmentUploadingText = 'Uploading...',
+ this.enterEmailPlaceholder = "Enter your email",
+ // this.agentAvailableText = "We're available.",
+ this.newMessagePlaceholder = "Start typing...",
+ this.noConnectionText = "No Connection",
+ this.attachmentNamePlaceholder = "No Name",
+ this.subtitle = "How can we help you?",
+ this.loadingText = "Loading...",
+ this.uploadedText = "uploaded",
+ this.retryButtonLabel = "Retry",
+ this.sendingText = "Sending...",
+ this.imageText = 'Image',
+ this.companyName = "Bot",
+ this.fileText = 'File',
+ this.sentText = "Sent",
+ this.title = "Welcome!",
+ this.greeting,
+ });
+}
 
+/// This contains all the possible configurations for the chat widget.
+class Props {
  /// This is the top widget text style
  TextStyle titleStyle;
 
  /// This is the top widget title alignment
  TextAlign titleAlign;
 
- /// This is a smaller piece of text under the title.
- String subtitle;
-
  /// This is the subtitle TextStyle
  TextStyle? subtitleStyle;
 
@@ -65,70 +156,50 @@ class Props {
  /// Gradient to specify, should be used instead of primaryColor, DO NOT USE BOTH.
  Gradient? primaryGradient;
 
- /// Required to create the wig¡dget, identifies the account.
+ /// Required to create the widget, identifies the account.
  String accountId;
 
  /// If you are self-hosting papercups, this base URL should be changed.
  String baseUrl;
 
- /// This is the first message sent by you during the conversation.
- String? greeting;
-
  /// This is the data that you will see on your dashboard such as the email or the name of the person.
  CustomerMetadata? customer;
 
- /// This is the placeholder text in the input section.
- String newMessagePlaceholder;
-
- /// This is the placeholder text in the email input section.
- String enterEmailPlaceholer;
-
  /// This is the close button in the header section.
  Widget closeIcon;
 
- /// This text will be shown if the showAgentAvailability is true and you are online.
- //String agentAvailableText;
-
- /// This text will be shown if the showAgentAvailability is true and you are offline.
- //String agentUnavailableText;
-
  /// This allows you to choose if you want to show your status.
  //bool showAgentAvailability;
 
- /// This Will allow you to require an emial to chat. Not recommended for an app.
+ /// This Will allow you to require an email to chat. Not recommended for an app.
  bool requireEmailUpfront;
 
  /// Whether to allow scrolling.
  bool scrollEnabled;
 
- /// Company name to show on greeting
- String companyName;
-
- /// header Padding
+ /// Header padding.
  EdgeInsetsGeometry headerPadding;
 
- /// header Height
+ /// Header height.
  double? headerHeight;
 
- /// message send icon for the chat section.
+ /// Message send icon for the chat section.
  Widget? sendIcon;
 
- //Class definition.
+ /// This contains all the texts that can be displayed by the widget.
+ PapercupsIntl translations;
+
+ // Class definition.
  Props({
  required this.accountId,
- //this.agentAvailableText,
- //this.agentUnavailableText,
  this.baseUrl = "app.papercups.io",
+ this.translations = const PapercupsIntl(),
  this.customer,
  this.closeIcon = const Icon(Icons.close_rounded),
- this.greeting,
- this.newMessagePlaceholder = "Start typing...",
  this.primaryColor,
  this.requireEmailUpfront = false,
  this.scrollEnabled = true,
  //this.showAgentAvailability = false,
- this.subtitle = "How can we help you?",
- this.title = "Welcome!",
  this.titleStyle = const TextStyle(
  color: Colors.white,
  fontSize: 21,
@@ -143,9 +214,7 @@ class Props {
  left: 20,
  bottom: 12,
  ),
- this.companyName = "Bot",
  this.primaryGradient,
- this.enterEmailPlaceholer = "Enter your email",
  this.sendIcon,
  });
 }

lib/models/models.dart

@@ -1,4 +1,4 @@
-// Where all models are exported, more comformatble and comapct.
+// Where all models are exported, more comfortable and compact.
 export 'classes.dart';
 export 'conversation.dart';
 export 'customer.dart';

lib/models/user.dart

@@ -15,8 +15,8 @@ class User {
  /// The role of the agent.
  String? role;
 
- /// The name of the agent. May be null.
- String? fullName;
+ /// The display name of the agent. May be null.
+ String? displayName;
 
  /// The profile photo of the agent, must be a valid URL or null.
  String? profilePhotoUrl;
@@ -27,7 +27,7 @@ class User {
  this.email,
  this.id,
  this.role,
- this.fullName,
+ this.displayName,
  this.profilePhotoUrl,
  });
 }