Merge pull request #585 from GetStream/text-message-guide

docs(doc): Added guide
2021-07-29 14:56:30 +02:00
parent abe985c31e ffb7c91c81
commit 4fa05919f7
2 changed files with 158 additions and 0 deletions
@@ -0,0 +1,158 @@
 ---
 id: customize_text_messages
 sidebar_position: 6
 title: Customize Text Messages
 ---
 Customizing Text Messages
 ### Introduction
 Every application provides a unique look and feel to their own messaging interface including and not
 limited to fonts, colors, and shapes.
 This guide details how to customize message text in the `MessageListView` / `MessageWidget` in the
 Stream Chat Flutter UI SDK.
 :::note
 This guide is specifically for the `MessageListView` but if you intend to display a `MessageWidget`
 separately, follow the same process without the `.copyWith` and use the default constructor instead.
 :::
 ### Basics of customizing a `MessageWidget`
 First, add a `MessageListView` in the appropriate place where you intend to display messages from a
 channel.
 ```dart
 MessageListView(
    ...
 )
 ```
 Now, we use the `messageBuilder` parameter to build a custom message. The builder function also provides
 the default implementation of the `MessageWidget` so that we can change certain aspects of the widget
 without redoing all of the default parameters.
 :::note
 In earlier versions of the SDK, some `MessageWidget` parameters were exposed directly through the `MessageListView`,
 however, this quickly becomes hard to maintain as more parameters and customizations are added to the
 `MessageWidget`. Newer version utilise a cleaner interface to change the parameters by supplying a
 default message implementation as aforementioned.
 :::
 ```dart
 MessageListView(
    ...
    messageBuilder: (context, messageDetails, messageList, defaultWidget) {
        return defaultWidget;
    },
 )
 ```
 We use `.copyWith()` to customize the widget:
 ```dart
 MessageListView(
    ...
    messageBuilder: (context, messageDetails, messageList, defaultWidget) {
        return defaultWidget.copyWith(
            ...
        );
    },
 )
 ```
 ### Customizing text
 If you intend to simply change the theme for the text, you need not recreate the whole widget. The
 `MessageWidget` has a `messageTheme` parameter that allows you to pass the theme for most aspects
 of the message.
 ```dart
 MessageListView(
    ...
    messageBuilder: (context, messageDetails, messageList, defaultWidget) {
        return defaultWidget.copyWith(
            messageTheme: MessageTheme(
                ...
                messageText: TextStyle(),
            ),
        );
    },
 )
 ```
 If you want to replace the entire text widget in the `MessageWidget`, you can use the `textBuilder`
 parameter which provides a builder for creating a widget to substitute the default text.parameter
 ```dart
 MessageListView(
    ...
    messageBuilder: (context, messageDetails, messageList, defaultWidget) {
        return defaultWidget.copyWith(
            textBuilder: (context, message) {
                return Text(message.text);
            },
        );
    },
 )
 ```
 ### Adding Hashtags
 To add elements like hashtags, we can override the `textBuilder` in the MessageWidget:
 ```dart
 MessageListView(
    ...
    messageBuilder: (context, messageDetails, messageList, defaultWidget) {
        return defaultWidget.copyWith(
            textBuilder: (context, message) {
                final text = _replaceHashtags(message.text).replaceAll('\n', '\\\n');
                final messageTheme = StreamChatTheme.of(context).ownMessageTheme;
                return MarkdownBody(
                    data: text,
                    onTapLink: (
                        String link,
                        String href,
                        String title,
                        ) {
                      // Do something with tapped hashtag
                    },
                    styleSheet: MarkdownStyleSheet.fromTheme(
                      Theme.of(context).copyWith(
                        textTheme: Theme.of(context).textTheme.apply(
                          bodyColor: messageTheme.messageText.color,
                          decoration: messageTheme.messageText.decoration,
                          decorationColor: messageTheme.messageText.decorationColor,
                          decorationStyle: messageTheme.messageText.decorationStyle,
                          fontFamily: messageTheme.messageText.fontFamily,
                        ),
                      ),
                    ).copyWith(
                      a: messageTheme.messageLinks,
                      p: messageTheme.messageText,
                    ),
                );
            },
        );
    },
 )
 String _replaceHashtags(String text) {
  RegExp exp = new RegExp(r"\B#\w\w+");
  exp.allMatches(text).forEach((match){
    text = text.replaceAll(
        '${match.group(0)}', '[${match.group(0)}](${match.group(0).replaceAll(' ', '')})');
  });
  return text;
 }
 ```
 We can replace the hashtags using RegEx and add links for the MarkdownBody which is done here in the
 `_replaceHashtags()` function.
 Inside the textBuilder, we use the `flutter_markdown` package to build our hashtags as links.
 ![](../assets/hashtag_example.jpg)