Forem: Christos

Full-stack Dart with Flutter, Supabase and Dart Edge

Christos — Sat, 13 May 2023 09:03:55 +0000

Introduction

Supabase has recently had its 7th Launch Week, with lots of new features and functionality shipped by the Supabase team as well as the community.

One of the community highlights was Dart Edge for Supabase Edge Functions. Built by Invertase, Dart Edge allows you to write your edge functions in Dart. It supports Vercel, Cloudflare Workers, and now Supabase Edge Functions, which until recently only supported writing functions with TypeScript. However, it is still experimental!

Being able to write our edge functions with Dart is amazing news for Flutter developers. It allows us to write Dart for both the front-end and any back-end code we need, which also means we can share Dart code, such as the request/response models. And while Supabase's database functions can be quite powerful, an edge function can do additional things such as call third-party APIs and services, and even bypass RLS policies if necessary.

In this post, we will explore Dart Edge with Supabase Edge Functions. We will build a simple app with Dart on the full stack, using a Flutter app front-end and a Dart Edge function as our back-end. We'll keep things simple by starting with the classic Flutter counter app but using an edge function to get the current count and increment it.

Set up an edge function

First, we need both the Supabase CLI and edge CLI. For the edge CLI, simply run:

dart pub global activate edge

The Supabase CLI can be installed through NPM or either Homebrew or Scoop depending on your operating system, so check out the documentation here.

Now, let's set up a Dart Edge project:

edge new supabase_functions edge_functions
cd edge_functions
supabase init

edge_functions is the name of our project and the name of the newly created directory. We run supabase init to generate the Supabase config.

The newly generated edge_functions directory is a typical Dart project with a pubspec.yaml file with the required dependencies. It has a main.dart file with a simple response to get us started:

// edge_functions/lib/main.dart
void main() {
  SupabaseFunctions(fetch: (request) {
    return Response("Hello from Supabase Edge Functions!");
  });
}

To run the edge function locally, we need to build the function and run Supabase:

edge build supabase_functions
supabase start
supabase functions serve dart_edge --no-verify-jwt

We can also use the --dev flag when running edge build to recompile when we make any changes to the code.

By default, the edge function is expected to have a valid authorization header. We pass the --no-verify-jwt flag so we can run the function without one.

We can now access the local edge function at http://localhost:54321/functions/v1/dart_edge

To deploy the function, we can build it and then run the following command:

supabase functions deploy dart_edge

Connect to Supabase from the edge

The current edge function only returns some text in the response. In a real app, we would likely want to interact with our database, make some third-party service calls, or both.

dart pub add supabase
dart pub add edge_http_client

The supabase package has all we need to interact with the Supabase database, but we also need to use a special HTTP client.

We can now instantiate a Supabase client:

final supabase = SupabaseClient(
  Deno.env.get('SUPABASE_URL')!,
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!,
  httpClient: EdgeHttpClient(),
);

A couple of notes on the above snippet:

The Supabase credentials are already available by default in the environment variables.
The service role key bypasses Row Level Security, meaning we can access and edit all data of all users. Since this is for an edge function, it's fine, but we could also use the anon key (SUPABASE_ANON_KEY environment variable) if that's a concern.

We now have access to the Supabase database from our edge function. Let's modify the function's logic to do two things:

Return the counter's current value if we make a GET request.
Increment the counter by 1 if we make a POST request.

We'll first need to create the database table that will hold our increments. These SQL statements are added to the seed.sql file.

-- edge_functions/supabase/seed.sql
create table increments (
  id bigint generated by default as identity primary key,
  amount int default 0 not null
);

create function get_count()
returns numeric as $$
  select sum(amount) from increments;
$$ language sql;

We also create a SQL function that returns the current count by summing up all the increments.

Now let's update our edge function's main method:

// edge_functions/lib/model/counter_response.dart
class CounterResponse {
  final int count;

  CounterResponse(this.count);

  factory CounterResponse.fromJson(Map<String, dynamic> json) =>
      CounterResponse(json['count'] as int);

  Map<String, dynamic> get toJson => {'count': count};
}

// edge_functions/lib/main.dart
void main() {
  SupabaseFunctions(fetch: (request) async {
    final client = SupabaseClient(
      Deno.env.get('SUPABASE_URL')!,
      Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!,
      httpClient: EdgeHttpClient(),
    );

    if (request.method == 'POST') {
      await client.from('increments').insert({'amount': 1});
    }
    final count = await client.rpc('count').single() as int;
    final response = CounterResponse(count);
    return Response.json(response.toJson);
  });
}

If the request is a POST, we increment the count by 1. For all requests, we fetch the current count and return it in the response. To fetch the count, we're calling a SQL function within an edge function!

Call the function from Flutter

With the edge function ready to go, we will now create the Flutter counter app, and update it so that the count display and increment button work by calling the edge function.

flutter create app

We'll be calling the function with the http package, but we're also going to need to add the edge_functions package as a local dependency. This is so we can reuse the CounterResponse model.

Here are the current dependencies (pubspec.yaml) for the Flutter app:

dependencies:
  flutter:
    sdk: flutter
  counter_edge_functions:
    path:  '../edge_functions'
  http: ^0.13.5

At the moment of writing, there seems to be a dependency issue due to the path package, so I had to remove flutter_test as a dev dependency to get this to work. A nicer fix for this would be to move the model to a separate local package instead and have it as a dependency for both the edge function package and the Flutter app.

Let's also encapsulate the interactions with the edge function to a repository:

import 'dart:convert';

import 'package:counter_edge_functions/model/counter_response.dart';
import 'package:http/http.dart' as http;

class CounterRepository {
  static final _functionUrl =
      Uri.parse('http://localhost:54321/functions/v1/dart_edge');

  Future<CounterResponse> get count async {
    final response = await http.get(_functionUrl);
    final body =
        jsonDecode(utf8.decode(response.bodyBytes)) as Map<String, dynamic>;
    return CounterResponse.fromJson(body);
  }

  Future<CounterResponse> increment() async {
    final response = await http.post(_functionUrl);
    final body =
        jsonDecode(utf8.decode(response.bodyBytes)) as Map<String, dynamic>;
    return CounterResponse.fromJson(body);
  }
}

The final piece is to call the repository methods from our widgets. There are not that many changes compared to the generated counter app code from the template, but here is the final result:

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    final repository = CounterRepository();
    return MaterialApp(
      title: 'Edge Counter',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      // Fetch the initial count from the Edge Function.
      home: FutureBuilder<CounterResponse>(
        future: repository.count,
        builder: (context, snapshot) {
          if (snapshot.connectionState != ConnectionState.done) {
            return const SizedBox();
          }
          return MyHomePage(
            title: 'Edge Counter',
            initialCount: snapshot.data?.count ?? 0,
            onIncrement: repository.increment,
          );
        },
      ),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({
    super.key,
    required this.title,
    required this.initialCount,
    required this.onIncrement,
  });

  final String title;
  final int initialCount;
  final Future<CounterResponse> Function() onIncrement;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  late int _counter;

  // Increment through the Edge Function, and update with the latest count.
  Future<void> _incrementCounter() async {
    final response = await widget.onIncrement();
    setState(() {
      _counter = response.count;
    });
  }

  @override
  void initState() {
    super.initState();
    _counter = widget.initialCount;
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'Users have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

We wrap the home page in a FutureBuilder to start with the current counter value, and call the increment method on button click. The count persists across restarts, and if we were using a deployed function rather than a local one, we could even share the app with friends and have everyone increment it at the same time!

Wrapping up

In this post, we talked about the experimental Dart Edge, allowing us to write Dart on the full stack - by using Flutter and Supabase. We created a very simple edge function that interacts with our database, and an even simpler Flutter counter app that calls the edge function to increment the counter.

You can find the full source code here.

If you found this helpful and would like to be notified of future tutorials, please follow the blog or subscribe to the newsletter with your email at dartling.dev!

Building a ChatGPT client app with Flutter

Christos — Sat, 29 Apr 2023 13:37:17 +0000

Introduction

In this blog post, we will build a simple conversational interface to chat with OpenAI's ChatGPT through its API.

There has been a lot of hype with OpenAI and ChatGPT lately, especially with GPT-4 being released recently. A ton of use cases for such tools have been popping up, but the most popular way people have been using ChatGPT so far is through chat.openai.com. I've been using ChatGPT to brainstorm ideas, write some Flutter code snippets, and even write the outline for this blog post! Of course, its suggested outline was quite optimistic so I had to leave some sections out, but it still provided enough pointers for me to be able to get started right away.

The official chat experience at OpenAI's chat interface is not great, however. It's very limited, and the chat history is often not working properly. There are already people building client apps for ChatGPT with a better UI and user experience, such as TypingMind, built with web technologies.

As a Flutter developer, I can't help but think that Flutter is a great fit for a ChatGPT client app! With cross-platform capabilities and a rich set of UI components, Flutter is a perfect choice for such a project. We can write the code once, and we could publish our app on the web, iOS, Android, and also the desktop platforms: Windows, macOS and Linux.

The ChatGPT API

To use any of OpenAI's APIs, you'll need to sign up and get an API key. You can do this here. Please note that API usage can cost money and you will need to provide payment details. The gpt-3.5-turbo model specifically, which we will be using, is quite cheap and should not cost more than a few cents unless you use it a lot.

Specifically, we will be using the Chat API (chat completions), which supports two of OpenAI's models: gpt-3.5-turbo and gpt-4. We can find the full reference for the Chat API here, which involves performing a POST request at https://api.openai.com/v1/chat/completions.

At this point, we could use the http library to perform the request with the required data to the Chat API, and parse the response. However, thanks to the Dart and Flutter communities, there is already a package available on pub.dev: dart_openai. It will make the API request for us and return a parsed response, so we can simply grab the response text and display it in the app.

Here is what a method that accepts a user message and returns ChatGPT's response looks like:

Future<String> completeChat(String message) async {
  final chatCompletion = await OpenAI.instance.chat.create(
    model: 'gpt-3.5-turbo',
    messages: [
      OpenAIChatCompletionChoiceMessageModel(
        content: message,
        role: 'user',
      ),
    ],
  );
  return chatCompletion.choices.first.message.content;
}

Since this will be a conversation, we need to pass previous messages to the request, so that ChatGPT has the whole context of the conversation so far, and not just the user's last message.

class ChatMessage {
  ChatMessage(this.content, this.isUserMessage);

  final String content;
  final bool isUserMessage;
}

Future<String> completeChat(List<ChatMessage> messages) async {
  final chatCompletion = await OpenAI.instance.chat.create(
    model: 'gpt-3.5-turbo',
    messages: [
      ...previousMessages.map(
        (e) => OpenAIChatCompletionChoiceMessageModel(
          role: e.isUserMessage ? 'user' : 'assistant',
          content: e.content,
        ),
      ),
    ],
  );
  return chatCompletion.choices.first.message.content;
}

The above method accepts the user's last message and all previous messages in the conversation. Note that ChatGPT's responses are marked with the role assistant in the API request.

Let's put the final version of our completeChat method to a ChatApi class, to be used later.

// models/chat_message.dart
class ChatMessage {
  ChatMessage(this.content, this.isUserMessage);

  final String content;
  final bool isUserMessage;
}

// api/chat_api.dart
import 'package:chatgpt_client/models/chat_message.dart';
import 'package:chatgpt_client/secrets.dart';
import 'package:dart_openai/openai.dart';

class ChatApi {
  static const _model = 'gpt-3.5-turbo';

  ChatApi() {
    OpenAI.apiKey = openAiApiKey;
    OpenAI.organization = openAiOrg;
  }

  Future<String> completeChat(List<ChatMessage> messages) async {
    final chatCompletion = await OpenAI.instance.chat.create(
      model: _model,
      messages: messages
          .map((e) => OpenAIChatCompletionChoiceMessageModel(
                role: e.isUserMessage ? 'user' : 'assistant',
                content: e.content,
              ))
          .toList(),
    );
    return chatCompletion.choices.first.message.content;
  }
}

Note that in the constructor, we are setting the API key and organization ID. Without the API key, any request will fail. Organization ID is optional and can be provided in case you have multiple organizations set up with the OpenAI platform.

// secrets.dart
const openAiApiKey = 'YOUR_API_KEY';
const openAiOrg = 'YOUR_ORGANIZATION_ID';

The secrets file is included in .gitignore to avoid committing it to version control. In the project repository on GitHub, a secrets_example.dart file is provided with placeholder values.

A note on API keys

In this post, we are building a client app. An app like this one with the API key hard-coded should not be published. Since API usage can cost, you don't want to expose your API key.

If you want to publish such an app, you have two options:

Allow users to provide their own API key to start chatting. Users can provide their key through the app and you can securely store it in local storage, to be used in every API request.
Rather than calling the Chat API directly, call a server, or edge function which will then call the Chat API with your own token. This way, you won't expose your API key, can control the traffic, as well as have additional authorization and rate-limiting requirements. If you go with this approach, you might want to consider monetizing, as users who use the app a lot will cost you money!

The chat interface

With the Chat API ready to be used, it's time to build the UI. If you're starting from scratch, you can use flutter create to initialize a Flutter project:

flutter create my_chatgpt_client

The UI will be pretty standard and will contain two main widgets: the message composer, and the message bubble. The main screen will be a list of all messages in the chat (as message bubbles), with the message composer at the bottom where we can type in the messages.

Let's start with the message composer widget:

// widgets/message_composer.dart
import 'package:flutter/material.dart';

class MessageComposer extends StatelessWidget {
  MessageComposer({
    required this.onSubmitted,
    required this.awaitingResponse,
    super.key,
  });

  final TextEditingController _messageController = TextEditingController();

  final void Function(String) onSubmitted;
  final bool awaitingResponse;

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(12),
      color: Theme.of(context).colorScheme.secondaryContainer.withOpacity(0.05),
      child: SafeArea(
        child: Row(
          children: [
            Expanded(
              child: !awaitingResponse
                  ? TextField(
                      controller: _messageController,
                      onSubmitted: onSubmitted,
                      decoration: const InputDecoration(
                        hintText: 'Write your message here...',
                        border: InputBorder.none,
                      ),
                    )
                  : Row(
                      mainAxisAlignment: MainAxisAlignment.center,
                      children: const [
                        SizedBox(
                          height: 24,
                          width: 24,
                          child: CircularProgressIndicator(),
                        ),
                        Padding(
                          padding: EdgeInsets.all(16),
                          child: Text('Fetching response...'),
                        ),
                      ],
                    ),
            ),
            IconButton(
              onPressed: !awaitingResponse
                  ? () => onSubmitted(_messageController.text)
                  : null,
              icon: const Icon(Icons.send),
            ),
          ],
        ),
      ),
    );
  }
}

The message composer will call the onSubmitted method we pass to it when the text field is submitted (e.g. by pressing Enter), or when we tap on the send button on the right. With the awaitingResponse flag, we can hide the text field and disable the send button. We will set this flag to true while a message submission is in progress and we await the API's response.

The message bubble widget is a simple container, with a different background color and sender name depending on whether it's a user message or an AI-generated one:

// widgets/message_bubble.dart
import 'package:flutter/material.dart';

class MessageBubble extends StatelessWidget {
  const MessageBubble({
    required this.content,
    required this.isUserMessage,
    super.key,
  });

  final String content;
  final bool isUserMessage;

  @override
  Widget build(BuildContext context) {
    final themeData = Theme.of(context);
    return Container(
      margin: const EdgeInsets.all(8),
      decoration: BoxDecoration(
        color: isUserMessage
            ? themeData.colorScheme.primary.withOpacity(0.4)
            : themeData.colorScheme.secondary.withOpacity(0.4),
        borderRadius: const BorderRadius.all(Radius.circular(12)),
      ),
      child: Padding(
        padding: const EdgeInsets.all(12),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Row(
              children: [
                Text(
                  isUserMessage ? 'You' : 'AI',
                  style: const TextStyle(fontWeight: FontWeight.bold),
                ),
              ],
            ),
            const SizedBox(height: 8),
            Text(content),
          ],
        ),
      ),
    );
  }
}

We now have all the necessary smaller widgets, now let's put them all together on the main page.

Here is what the code for the main chat page looks like:

// chat_page.dart
import 'package:chatgpt_client/api/chat_api.dart';
import 'package:chatgpt_client/models/chat_message.dart';
import 'package:chatgpt_client/widgets/message_bubble.dart';
import 'package:chatgpt_client/widgets/message_composer.dart';
import 'package:flutter/material.dart';

class ChatPage extends StatefulWidget {
  const ChatPage({
    required this.chatApi,
    super.key,
  });

  final ChatApi chatApi;

  @override
  State<ChatPage> createState() => _ChatPageState();
}

class _ChatPageState extends State<ChatPage> {
  final _messages = <ChatMessage>[
    ChatMessage('Hello, how can I help?', false),
  ];
  var _awaitingResponse = false;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Chat')),
      body: Column(
        children: [
          Expanded(
            child: ListView(
              children: [
                ..._messages.map(
                  (msg) => MessageBubble(
                    content: msg.content,
                    isUserMessage: msg.isUserMessage,
                  ),
                ),
              ],
            ),
          ),
          MessageComposer(
            onSubmitted: _onSubmitted,
            awaitingResponse: _awaitingResponse,
          ),
        ],
      ),
    );
  }
}

This is a stateful widget that starts with the message "How can I help?", just so we don't start with an empty chat.

The final piece is the _onSubmitted method, called through the message composer when a message is submitted.

Future<void> _onSubmitted(String message) async {
  setState(() {
    _messages.add(ChatMessage(message, true));
    _awaitingResponse = true;
  });
  final response = await widget.chatApi.completeChat(_messages);
  setState(() {
    _messages.add(ChatMessage(response, false));
    _awaitingResponse = false;
  });
}

When a message is submitted, we add the message to the chat messages and set _awaitingResponse to true, wrapped in a setState call. This will show the user message in the conversation, and disable the message composer.

Next, we pass all messages to the Chat API and await the response. Once we have the response, we add it as a chat message in _messages and set _awaitingResponse back to false, wrapped in a second setState call.

And that's it for the conversation flow! Let's see it in action:

This is the code for the App and the main method:

import 'package:chatgpt_client/api/chat_api.dart';
import 'package:chatgpt_client/chat_page.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(ChatApp(chatApi: ChatApi()));
}

class ChatApp extends StatelessWidget {
  const ChatApp({required this.chatApi, super.key});

  final ChatApi chatApi;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'ChatGPT Client',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(
          seedColor: Colors.teal,
          secondary: Colors.lime,
        ),
      ),
      home: ChatPage(chatApi: chatApi),
    );
  }
}

Parsing markdown

In our previous conversation with ChatGPT, we ask the follow-up question "show me the code".

We get a decent amount of Flutter code in the response, but it's all in markdown! Let's use the markdown_widget package to solve this.

flutter pub add markdown_widget

In the MessageBubble widget, replace the Text widget containing the message content with a MarkdownWidget:

MarkdownWidget(
  data: content,
  shrinkWrap: true,
)

One hot reload later, and we can see that the code is now properly parsed. That was easy!

Error handling

What if we get an error response from OpenAI? While testing, I did run into a few 429 (Too Many Requests) exceptions. Such an error could happen if you are calling the API too often, but also if the OpenAI API is getting too many requests in general.

The least we can do is handle the error and display a useful message. Here's a revised _onSubmitted method:

Future<void> _onSubmitted(String message) async {
  setState(() {
    _messages.add(ChatMessage(message, true));
    _awaitingResponse = true;
  });
  try {
    final response = await widget.chatApi.completeChat(_messages);
    setState(() {
      _messages.add(ChatMessage(response, false));
      _awaitingResponse = false;
    });
  } catch (err) {
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('An error occurred. Please try again.')),
    );
    setState(() {
      _awaitingResponse = false;
    });
  }
}

Of course, this could be improved even further. We can provide an option to retry the response without needing to send a new message, but also automatically retry the request in ChatApi without showing an error.

Wrapping up

We now have a fully working chat app to chat with ChatGPT at any time, on any platform!

In this post, we showed how to build a basic chat app to have conversations with ChatGPT through OpenAI's chat API. We also added some additional features such as markdown parsing and error handling.

The functionality is quite basic, but there's a lot more we can do with such an app. We could have useful features such as being able to copy and/or share the responses. Additionally, we can use a local or cloud database to store the conversations so we can access them at any time.

You can find the source code here.

Are you interested in building a ChatGPT client, or building a Flutter app utilizing ChatGPT? Or would you be interested in any follow-up articles where we improve this app by adding more features such as conversation storage and organization? Let me know in the comments!

If you found this helpful and would like to be notified of future posts and tutorials, please subscribe to the Dartling blog!

How I built and published a Flutter app in 48 hours

Christos — Mon, 16 Jan 2023 20:53:51 +0000

Introduction

A couple of years ago, I built and published my first app built with Flutter, Timelog. It's a time tracking app which lets you track your time across different activities, and set daily/weekly/monthly goals per activity. I built this app mainly for myself, but I was quite happy to find out that a lot of other people have found it useful too.

Fast forward to the start of this year, and I was looking forward to building another app with Flutter. I decided to build Flow, a simple expense tracking app that would fit my needs, as I found the tons of expense tracking apps already out would either have clunky UIs or way too many features that I didn't need, yet still not flexible enough.

Firstly, I'd like to point out that no, this is not a guide to build and publish an app in production in a weekend. The title may be a little misleading (sorry!), but by 48 hours I mean 48 total hours of development of the app as well as the landing page, in addition to the Play Store listing (I haven't got to publishing this to the App Store yet). This process actually took me about 3 months in total, and I was mostly building this during the weekends and evenings in 1-3 hour chunks.

I actually used my first Flutter app, Timelog, to track how much time I spent building Flow, and that's how I noticed that by the time I had published Flow to the Play Store, I was at roughly 48 hours tracked in total. I also ended up looking at Timelog's source code to see how I did some things, and even copied some approaches and technologies used.

In this post, I will go over the process I took to build Flow, an expense tracking app with Flutter, in 48 hours of total development. We will start from the (a bit too short) planning phase, followed by the implementation, and then the final steps leading to publishing the app on the Play Store.

Planning

This phase was relatively short, and mostly consisted of thinking about what features I would want such an app to have, at least for a minimum viable product.

Features

Expense tracking

This was an expense tracking app, so of course it would need to support recording your expenses: an amount, a date, and a category. Users should be able to see a history of their expenses, as well as manage their categories.

Statistics

Of course, the reason you would track your expenses is to monitor your spending and see how much you spend and on what. One of the main features would be to display useful charts that would show you total amount spent per category, with options to filter categories and set specific time ranges.

For this, I used syncfusion_flutter_charts. It's very customizable and has every chart I could think of, or at least needed. I had also used the same library previously for Timelog, so this was an easy choice.

Labels

For Timelog, my first app, the stand-out feature which most of the existing time trackers did not have were goals you can set per activity. For example, I have a reading goal of 2 hours per week, and a blogging goal of 4 hours per month (though thanks to #4articles4weeks, I'm already well past over 4 this month!).

For Flow, the stand-out feature is the ability to assign labels on each expense. For example, you could have labels specific to locations, trips, or people. This way, you could track exactly how much you spend e.g. on a trip, without having to assign the generic "Travel" category to every expense.

Currencies

Users in different countries will need to track expenses for different currencies. The user should be able to pick their own currency, and this package made this very easy to implement. Supporting multiple currencies at the same time would make things more complicated, so this was left out and added to the backlog as a feature for the future.

Design

I'm not a designer, but thankfully, it's easy to build beautiful looking UIs with Flutter. I decided to simply use the Material widgets to make my life easier, as the Material look is decent enough for all platforms.

The main layout is just a Scaffold with a NavigationBar at the bottom and a FloatingActionButton to record expenses. There's also a lot of ListTile widgets used for the expense history, settings, and the category/label management pages, as well as icons and charts. The most complex widget that I built from scratch was the number picker, which you can input the expense amount with. It's really just a bunch of rows and columns, but the decimal button logic was a bit tricky.

Implementation

Data storage

For an expense tracking app, we need to store the user's expenses and categories. At least for the first version, we're just going to store the data locally on the user's device. For this, I went with Drift, which is built on top of sqflite. For less critical data such as the theme and user preferences, shared_preferences is used instead.

State management

I spent ages trying to figure out which state management approach to use for my first app, so thankfully this time it was easy. For state management, I used "vanilla" Flutter; a combination of FutureBuilders, StreamBuilders, ValueNotifier/ValueListenableBuilders, and even StatefulWidgets.

Drift, the persistence library supports exposing data not just as futures but also as streams, which emit new events every time the data changes. Most views showing data such as expenses, categories or labels simply use a StreamBuilder to display the data, and these are refreshed automatically every time something is added or changed.

Other views that require "complex" state such as the expense creation page, are made of small StatefulWidgets that communicate changes to the data through callback methods, and state changes that influence other widgets can do so through ValueNotifiers.

In total, so far, the app uses 12 StreamBuilders, 8 FutureBuilders, and 9 ValueListenableBuilders. No external libraries!

Architecture

Flow is a simple app so far. A lot of the business/data logic that deals with creating expenses, storing user settings and configuring notifications is isolated in specific Service and Repository classes. These classes are passed around to widgets through the use of a Services inherited widget, which holds the references to instances of any dependencies needed.

class Services extends InheritedWidget {
  final ExpenseRepository expenseRepository;
  final SettingsService settingsService;
  final NotificationService notificationService;
  final AnalyticsService analyticsService;
  final SubscriptionService subscriptionService;

  Services({
    Key? key,
    ...
    required Widget child,
  })  : ...
        super(key: key, child: child);

  static Services of(BuildContext context) {
    final Services? result =
        context.dependOnInheritedWidgetOfExactType<Services>();
    assert(result != null, 'No Services found in context');
    return result!;
  }

  @override
  bool updateShouldNotify(Services oldWidget) {
    return false;
  }
}

To avoid coupling widgets with business logic, some complex bigger widgets/views have their own ViewModel class, usually per page/screen. This view model has all the dependencies needed (services or repositories), and the view simply calls methods on this view model.

class NewExpenseViewModel {
  final ExpenseRepository _expenseRepository;
  final CategoryRepository _categoryRepository;
  final AnalyticsService _analyticsService;

  int amount;
  DateTime date;
  TimeOfDay? time;
  Category category;

  NewExpenseViewModel(
    this._expenseRepository,
    this._categoryRepository,
    this._analyticsService, {
    required this.amount,
    required this.category,
    this.time,
  }) : date = DateTime.now().startOfDay;

  Future<void> save() async {
    _analyticsService.track('new_expense');
    await _expenseRepository.create(
        amount, date, time, description, category.id, labels);
  }

  Future<List<Category>> get categories => _categoryRepository.all;
}

These views and view models are created by first getting the Services from the context in order to create it with any of its dependencies, like below:

Future<Expense?> openNewExpensePage(
    BuildContext context, int amount, Category category) {
  final services = Services.of(context);
  final viewModel = NewExpenseViewModel(
    services.expenseRepository,
    services.categoryRepository,
    services.analyticsService,
    amount: amount,
    category: category,
  );
  return Navigator.push<Expense>(
    context,
    MaterialPageRoute(
        builder: (_) => NewExpenseView(viewModel)),
  );
}

This is a basic architecture that's been working for me. It's quite simple and has no dependencies on external libraries, and view models can easily be tested in isolation. It does feel like a little bit of boilerplate at times, though, especially when trying to build something quickly, and especially in a team of one. I do occasionally "cheat" by accessing the services and their methods directly in widgets, though!

Local notifications

Flow has a simple daily notification to remind you to register your expenses. This is set when you first open the app and can be toggled on/off and its time can be changed. For this, I used the local_notifications package.

Theming

No app is complete without dark mode! In Flutter, it's so simple to implement that it was one of the first things I worked on. I also used flex_color_scheme with the Material 3 settings enabled to make my life a bit easier, and even have true black mode out-of-the-box in addition to dark mode.

Since Flow is meant to be a simple expense tracking app, I also made use of Material 3's dynamic color feature to change the app's theme/color based on the user's main theme/color on their device.

Monitoring

While monitoring of any kind is optional, it's something I'd recommend to always have, just to have an idea of how your app is used, or how it doesn't work!

Analytics

I find it useful to track metrics to measure how and how much the app is used and what features are used the most. Things like expenses created, new labels created, and which statistics/charts are viewed the most. This can help decide which features to focus on while working more on the app.

For Flow, I decided to go with Mixpanel, as it had an official Flutter package. However, I later realized that you can only have up to 5 reports on your dashboards on the free plan, which is far too little to get any useful insights. Because of this, my suggestion would be to go with something like Amplitude instead, which has a much more generous free tier.

Crash reporting

I went with Sentry for error/crash reporting, which also has good support for Flutter. It's nice to be able to see any errors thrown while other users are using your app, as your tests might not catch everything. And in my case, I was only mostly testing things manually (sorry, TDD folks!).

On-boarding

Another "nice-to-have" is an on-boarding flow. This is what is shown when a user first starts up the app. I used the smooth_page_indicator package as well as some images from unDraw to show a few pages explaining Flow's core functionality. On the last page, the user can also opt in or out of the analytics and crash reporting mentioned above.

A good follow-up for the introductory pages would be a tutorial, or tour, of the main functionality. For Flow, for example, the FAB that lets you add expenses could be highlighted with a tool-tip explaining that this is where you need to tap to start tracking expenses. Flow is currently not that complicated to require such a tutorial, though.

In-app purchases

I wanted to monetize the app from the beginning. Again an optional step, but it's nice to be able to validate if your app is actually good and unique enough for people to want to pay to use it more. I'm not a fan of ads at all, so I decided to implement a one-time "Flow Plus" purchase, which gives you access to more colors and icons for categories and labels, as well as unlimited labels.

For the implementation of in-app purchases, I used RevenueCat. When I was building Timelog, Flutter's official in_app_purchase plugin was not complete. This is how I found out about RevenueCat and its purchases_flutter package. RevenueCat has lots of extra features and functionality you might otherwise have to implement yourself, in addition to a generous free tier!

Necessary things

In order to publish the app on the stores, there are some small things I had to include, namely, terms of use and privacy policy pages. I had already bought a domain for the app, flowmoneytracker.com, so I created two pages with the necessary information there, making sure to include third party services used for monitoring. I also spent some time on a very basic landing page.

Since I implemented in-app purchases, I also needed to make sure a "Restore purchases" option is available. This is a requirement for iOS apps, and I made sure to add this in the settings page as soon as possible, as it's one of the reasons Timelog's initial App Store submission was rejected!

A few more things

I wasn't really in a rush to release Flow, which is why I spent some time to also implement some features that are not really necessary to have in a minimum viable product. Some of these I also wanted for myself and did not take too much time, so I went for them:

The option to change the start day of the week (for the weekly statistics)
A set of preset categories as well as pages to manage categories and labels
Backup and restore functionality (useful for me in case I broke things while testing on my device! I had already been tracking my expenses while developing the app, and didn't want to lose my data)
Sharing functionality that simply shares the landing page's URL, and a feedback option that opens up an email to Flow's support email. I used ImprovMX to forward support emails to a personal email account.

Production

Publishing

And so, after a little less than 48 hours divided across 1-3 hour sessions, Flow was ready for production. I spent some time making screenshots for the Play Store listing, and quickly wrote short and long descriptions. A couple of days later, Flow was approved, and live on the Play Store.

Once I gather some more feedback from the Android version and make some more improvements, I also want to publish Flow to the App Store. Maybe even on desktop platforms, but I would need to make some layout changes first so that it looks good on larger screens.

Future plans

There are too many features an expense tracker like Flow could eventually support: recurring expenses, income tracking, budgeting, multiple accounts, multiple currencies... The current plan is to keep things simple and see if the labels feature actually makes Flow stand out from the hundreds of expense tracking apps out there. I do need to first market it a little, as currently it's just quietly sitting in the Play Store and not very easy to find!

Wrapping up

I hope you found this post helpful! It covered a little bit of everything involving building Flutter apps, from designing and planning to implementing, with a little technical details on the architecture as well as packages and approaches used.

I've been using Flow for myself for a few months and find it quite useful, so this is already a win for me! It's been a great experience building and publishing my second Flutter app. Since publishing my first Flutter app two years ago, Flutter's developer experience has improved, making it easier to develop with Flutter, and I even got to re-use some past learning from the first app. Perhaps my third app could be published even quicker!

Cover image generated by OpenAI's DALL-E.

How to create a custom plugin in Flutter with Pigeon

Christos — Sun, 24 Jul 2022 19:11:35 +0000

Introduction

In this tutorial, we will create a Flutter plugin which targets the Android and iOS platforms using the Pigeon package.

With Flutter being a UI framework, communicating with the native platform is not something we always need or use. And usually when we do need to do so, there are tons of packages out there that already do this for specific use cases.

But there are cases when the functionality the native platform has to offer is not yet available in a public package on pub.dev. In these cases, it's up to us! We need to write some Dart code on the Flutter side to call the platform, as well as the native platform code to call the functionality we need (and that's once per platform your app supports!).

Native platform communication

Platform channels

One way to communicate with the native platform in Flutter is by using a MethodChannel. We covered how to build a plugin or call native platform code in Flutter using method channels in a previous post.

While using MethodChannel is relatively straightforward, it can actually be quite time-consuming; when calling methods through the MethodChannel, you can only pass arguments of simple types such as int, double, bool or String, as well as maps of list with such types as values. You can see the full data types support here. If you need to pass a complex object as an argument, you would need to have logic to parse this to, let's say, a map of string keys to their values. In addition, you need to do the same for any data that is returned from the native platform.

We could work around having to introduce parsing logic by using a package such as json_serializable to parse data to and from JSON to save ourselves some time. However, you'd need to make sure the native platforms are returning the data in the exact format you are expecting, and vice versa. Otherwise the parsing will fail.

Pigeon

Pigeon is a code generator package which generates all the code necessary to communicate between Flutter and any host platform. All you have to do is define the API. This is convenient, because you don't have to worry about any parsing logic, and the communication is guaranteed to be type-safe.

As of July 10th 2022, Pigeon only supports Android and iOS, and generates Java and Objective-C code (Swift is experimental) respectively. The generated code is still accessible to Kotlin or Swift. There is also experimental Windows support with C++.

Creating a plugin

In this post, we will create a simple plugin using Pigeon. What we will build will be identical to the (fake) app usage plugin we built previously, so we can compare the results.

The plugin is simple; it should return a list of all apps and their usage, as well as support the ability to set time limits on specific apps. We won't actually implement this functionality on the native side as it's outside the scope of this tutorial, but rather return dummy data from the native side instead.

The plugin template

To get started, we'll create a Flutter plugin using flutter create with the plugin template.

flutter create --org dev.dartling --template=plugin --platforms=android,ios app_usage_pigeon

This will generate the code for the plugin, as well as an example project that uses this plugin. By default, the generated Android code will be in Kotlin, and iOS in Swift, but you can specify either Java or Objective-C with the -a and -i flags respectively. (-a java and/or -i objc).

There is quite a bit of code included with the plugin template. We go into the Dart, Kotlin and Swift code into more detail in this post, if you're curious. For the context of this tutorial, it's enough to know the following:

On the Dart side, there are three classes:

AppUsagePlatform - the "interface"/API of the plugin, which implements PlatformInterface.
MethodChannelAppUsage - an implementation of AppUsagePlatform using method channels.
AppUsage - the class exposing the methods to be used by any apps which need to use our plugin.

The Kotlin code generated is AppUsagePlugin.kt, which uses method channels. It is defined in our pubspec.yaml as the plugin class for the Android platform, so we'll still be needing it, though we will make some changes to it later. The same applies to the Swift code, which includes SwiftAppUsagePlugin.swift as well as AppUsagePlugin.h and AppUsagePlugin.m.

In this tutorial, we will write an implementation of AppUsagePlatform which uses Pigeon rather than method channels. We can delete MethodChannelAppUsage as we won't be needing it.

Note: the new plugin template using PlatformInterface introduces quite a bit of code that you might not really need if you just want to call some native code in your app. If you wanted, you could still use Pigeon without creating a plugin or a separate package, but that's what we'll be doing in this tutorial.

Using Pigeon

Installing the `pigeon` package

Let's install the package:

flutter pub add --dev pigeon

Alternatively, add this to your pubspec.yaml:

dev_dependencies:
  pigeon: ^3.2.3

Defining the App Usage API

The way Pigeon works is pretty simple; we define our API in a Dart class outside the lib folder (as Pigeon is a dev dependency). The API class should be an abstract class with the @HostApi() decorator, and its methods should have the @async decorator.

Let's define our App Usage API in a new directory named pigeons:

// pigeons/app_usage_api.dart
import 'package:pigeon/pigeon.dart';

enum State { success, error }

class StateResult {
  final State state;
  final String message;

  StateResult(this.state, this.message);
}

class UsedApp {
  final String id;
  final String name;
  final int minutesUsed;

  UsedApp(this.id, this.name, this.minutesUsed);
}

@HostApi()
abstract class AppUsageApi {
  @async
  String? getPlatformVersion();

  @async
  List<UsedApp> getApps();

  @async
  StateResult setAppTimeLimit(String appId, int minutesUsed);
}

Caveats and limitations

Defining the API was relatively simple, but there are a few things to mention:

Futures

We do not need to specify the return values as Futures, but in the generated code they will be. So getPlatformVersion will actually return a Future<String?> in the generated Dart code.

No imports allowed

No imports other than package:pigeon/pigeon.dart are allowed. This means EVERY model class should be defined in this Pigeon API file.

Supported data types

As mentioned before, only simple JSON-like values are supported. This means we can't use useful Dart types such as DateTime or Duration. Which means we might still need additional mapping logic to convert the Pigeon model to the model we want to use within the app. For minutesUsed in UsedApp, we'll need to manually create a Duration out of the minutes, though it would be nice to have this as a Duration in the first place.

Enums aren't yet supported for primitive return types

We cannot return an enum from a method, but we can have an enum as a method parameter. We can still return enums, but only if we wrap them in a separate class, like below.

// Not valid, enums cannot be returned.
enum ResultState { success, error }

@HostApi()
abstract class AppUsageApi {
  @async
  ResultState getState();
}

// Valid, enums can be method parameters and fields of returned objects.
enum ResultState { success, error }

class ApiResult {
  final ResultState state;
  final String message;

  ApiResult(this.state, this.message);
}

@HostApi()
abstract class AppUsageApi {
  @async
  ApiResult getResult();

  @async
  void setState(ResultState state);
}

Generics are supported, but can only be used with nullable types

We can still define them as non-nullable in our HostApi definition, e.g. List<Something>, but the generated Dart class will have List<Something?> instead.

Generating the code

Running the generator

After defining the API, we can generate code using flutter pub run pigeon. This command requires quite a few arguments:

flutter pub run pigeon \
  --input pigeons/app_usage_api.dart \
  --dart_out lib/app_usage_api.dart \
  --java_package "dev.dartling.app_usage" \
  --java_out android/src/main/java/dev/dartling/app_usage/AppUsage.java \
  --experimental_swift_out ios/Classes/AppUsage.swift

We will store this in a pigeon.sh file, just so it's easy to find and run in the future.

We're going with Swift which has experimental support for now rather than Objective-C, but for Objective-C we can simply drop the experimental_swift_out argument in favor of these three:

  --objc_header_out ios/Classes/AppUsageApi.h \
  --objc_source_out ios/Classes/AppUsageApi.m \
  --objc_prefix FLT

Dart

The input argument should be the file we defined the API in, and dart_out should be in our lib folder, as it's the code we'll actually be using in our app.

Java

java_package is the full package name, in this case dev.dartling.app_usage and java_out is the path to the Java file that will be generated.

Note: Make sure the generated Java class name does NOT match the name of the Pigeon HostApi. In our case, the generated Java class will be AppUsage, and will include a nested public AppUsageApi interface, taken from the HostApi class name defined in Dart. If we used the same names (which is what I did initially!), compilation will fail due to duplicate names.

Note: if your plugin template uses Kotlin, like we did in this one, you will need to create the java/dev/dartling/app_usage directory manually under src/main, as only kotlin/dev/dartling/app_usage was generated as part of the plugin template.

Swift

experimental_swift_out is the path to the Swift file that will be generated.

Objective-C

The objc_header_out and objc_source_out arguments determine the generated files on the Objective-C side, and the objc_prefix is optional and determines the prefix of the generated class names.

Understanding the generated code

The code generated by Pigeon after running flutter pub run pigeon is not something we should really have to look at often. All we need to know is that the Java class will have an AppUsageApi interface which our implementation class should implement; this can be both in either Java or Kotlin. In Objective-C, there will be a FLTAppUsageApi protocol equivalent (notice the FLT prefix which is an argument when running the generator), and in Swift an AppUsageApi protocol.

Native platform implementation

Android

We have our interface, now all we need to do is have an implementation for it. To keep things simple, we will simply the existing AppUsagePlugin Kotlin class to implement AppUsageApi, in addition to the existing FlutterPlugin interface.

Here is the full class:

// AppUsagePlugin.kt
class AppUsagePlugin : FlutterPlugin, AppUsageApi {
    val usedApps: MutableList<UsedApp> = mutableListOf(
        usedApp("com.reddit.app", "Reddit", 75),
        usedApp("dev.hashnode.app", "Hashnode", 37),
        usedApp("link.timelog.app", "Timelog", 25),
    )

    override fun onAttachedToEngine(@NonNull flutterPluginBinding: FlutterPlugin.FlutterPluginBinding) {
        AppUsageApi.setup(flutterPluginBinding.binaryMessenger, this)
    }

    override fun getPlatformVersion(result: Result<String>?) {
        result?.success("Android ${android.os.Build.VERSION.RELEASE}")
    }

    override fun getApps(result: Result<MutableList<UsedApp>>?) {
        result?.success(usedApps);
    }

    override fun setAppTimeLimit(
        appId: String,
        durationInMinutes: Long,
        result: Result<TimeLimitResult>?
    ) {
        val stateResult = TimeLimitResult.Builder()
            .setState(ResultState.success)
            .setMessage("Timer of $durationInMinutes minutes set for app ID $appId")
            .build()
        result?.success(stateResult)
    }

    private fun usedApp(id: String, name: String, minutesUsed: Long): UsedApp {
        return UsedApp.Builder()
            .setId(id)
            .setName(name)
            .setMinutesUsed(minutesUsed)
            .build();
    }

    override fun onDetachedFromEngine(@NonNull binding: FlutterPlugin.FlutterPluginBinding) {
        AppUsageApi.setup(binding.binaryMessenger, null)
    }
}

The onAttachedToEngine and onDetachedFromEngine are from FlutterPlugin. Previously they set things up to work for the method channel implementation. Now, we are calling the AppUsageApi#setup method to get it to work with Pigeon's generated code.

The other three functions we override are from the AppUsageApi interface. These are actually void functions, and we "return" the results by making use of result, which was actually generated as nullable. To return, we simply use result?.success(...), and in case we want to throw an error, we can use result?.error(...) and pass a Throwable; this will be wrapped into a PlatformException on the Dart side.

iOS

Very similarly to Android, we will make the existing SwiftAppUsagePlugin implement the AppUsageApi protocol in addition to being a FlutterPlugin. Rather than result, we have completion which we call by passing the result as the argument. We also make some changes to register to use the static AppUsageApiSetup#setUp function to set things up with the generated file.

public class SwiftAppUsagePlugin: NSObject, FlutterPlugin, AppUsageApi {
    var usedApps = [
        UsedApp(id: "com.reddit.app", name: "Reddit", minutesUsed: 75),
        UsedApp(id: "dev.hashnode.app", name: "Hashnode", minutesUsed:37),
        UsedApp(id: "link.timelog.app", name: "Timelog", minutesUsed: 25)
    ]

    public static func register(with registrar: FlutterPluginRegistrar) {
        let messenger : FlutterBinaryMessenger = registrar.messenger()
        let api : AppUsageApi & NSObjectProtocol = SwiftAppUsagePlugin.init()
        AppUsageApiSetup.setUp(binaryMessenger: messenger, api: api)
    }

    func getPlatformVersion(completion: @escaping (String?) -> Void) {
        completion("iOS " + UIDevice.current.systemVersion)
    }

    func getApps(completion: @escaping ([UsedApp]) -> Void) {
        completion(usedApps)
    }

    func setAppTimeLimit(appId: String, durationInMinutes: Int32, completion: @escaping (TimeLimitResult) -> Void) {
        completion(TimeLimitResult(state: ResultState.success, message: "Timer of \(durationInMinutes) minutes set for app ID \(appId)"))
    }
}

Note: I've faced some weird issues with the iOS build sometimes not succeeding due to AppUsageApi not being found in the scope. If you run into the same issue, the quick hacky way is to copy everything in the generated AppUsage.swift into the existing SwiftAppUsagePlugin.swift file. Then it should work! If you figure out how/why this happens and how to fix it, please let me know in the comments!

Using the plugin

We now have everything in place. The native platform implementations are done, and the AppUsageApi Dart class can be used to communicate with the native platforms.

All we have to do is create an instance of AppUsageApi and invoke its method... but wait, we're building a plugin! We should not use AppUsageApi directly (though we could!). Remember the MethodChannelAppUsage Dart class we deleted a while ago? We need to introduce an alternative that will use Pigeon instead of method channels.

Firstly, let's add make sure all methods that are part of our Pigeon HostApi are also defined in our AppUsagePlatform.

abstract class AppUsagePlatform extends PlatformInterface {
  ...

  Future<String?> getPlatformVersion() {
    throw UnimplementedError('platformVersion() has not been implemented.');
  }

  Future<List<UsedApp>> get apps async {
    throw UnimplementedError('apps has not been implemented.');
  }

  Future<TimeLimitResult> setAppTimeLimit(String appId, Duration duration) async {
    throw UnimplementedError('setAppTimeLimit() has not been implemented.');
  }
}

Now, our AppUsagePlatform implementation with Pigeon is very simple. We're simply going to invoke the methods of AppUsageApi, which was generated by Pigeon.

// app_usage_pigeon.dart
/// An implementation of [AppUsagePlatform] that uses Pigeon.
class PigeonAppUsage extends AppUsagePlatform {
  final AppUsageApi _api = AppUsageApi();

  @override
  Future<String?> getPlatformVersion() {
    return _api.getPlatformVersion();
  }

  @override
  Future<List<UsedApp>> get apps {
    return _api
        .getApps()
        .then((apps) => apps.where((e) => e != null).map((e) => e!).toList());
  }

  @override
  Future<TimeLimitResult> setAppTimeLimit(String appId, Duration duration) async {
    return _api.setAppTimeLimit(appId, duration.inMinutes);
  }
}

Note that in apps we filter null values and use the ! operator, as AppUsageApi#getApps() returns List<UsedApp?>, due to Pigeon's current limitations.

Lastly, AppUsage, our main plugin class, should also be updated. All it does is delegate method calls to AppUsagePlatform.instance.

class AppUsage {
  Future<String?> getPlatformVersion() {
    return AppUsagePlatform.instance.getPlatformVersion();
  }

  Future<List<UsedApp>> get apps {
    return AppUsagePlatform.instance.apps;
  }

  Future<TimeLimitResult> setAppTimeLimit(String appId, Duration duration) {
    return AppUsagePlatform.instance.setAppTimeLimit(appId, duration);
  }
}

And let's not forget, that AppUsagePlatform.instance should now return an instance of PigeonAppUsage rather than MethodChannelAppUsage:

abstract class AppUsagePlatform extends PlatformInterface {
  ...

  static AppUsagePlatform _instance = PigeonAppUsage();

  /// The default instance of [AppUsagePlatform] to use.
  ///
  /// Defaults to [PigeonAppUsage].
  static AppUsagePlatform get instance => _instance;

  ...
}

I won't share snippets of the UI code and widgets, but you can take look at these here. Using the plugin in any app is simple; we initialize an instance of AppUsage and call its methods we need them.

Here is the final result:

Comparing Pigeon and method channels

We built an almost identical plugin and example app in a previous article, so we can compare Pigeon with using method channels.

Overall, Pigeon is definitely an improvement. We only have to define our API and models once; the generated Android/iOS will include these models for us.

We also don't have to worry about serializing data we want to pass to the platform side or deserialize data coming from the platform side, and the opposite for the platform side; we won't have to worry about deserializing data coming from the Dart side and serializing data we return to the Dart side.

Thanks to the two points above, we needed significantly less lines of code to write a plugin using Pigeon rather than method channels.

Wrapping up

In this tutorial, we introduced Pigeon as a way to simplify native platform communication, and created a custom Flutter plugin with Android and iOS implementations to call (fake) native functionality, using Pigeon rather than method channels.

You can find the full source code here.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email here.

Dynamic theme color with Material 3 (You) in Flutter

Christos — Sun, 10 Jul 2022 20:08:11 +0000

Introduction

In this blog post, we will enhance our app's theme to use dynamic colors taken from Material 3's OS-defined color scheme.

In Android 12, Material You, the third iteration of Material Design was introduced. One of the main features of Material 3 is Dynamic Color, which allows users to select their own color scheme for the whole OS, derived from the wallpaper.

This results in a set of primary, secondary and tertiary colors being consistent across the whole OS as well as built-in apps such as the clock, calculator, and even some Google apps such as Photos.

You may not always want implement this for your apps, especially if your app needs to follow specific brand guidelines (and if color is an important part of your brand). However, in some cases, supporting a dynamic color theme might make sense, depending on your app and brand.

In this post, we will enhance the default Flutter counter app with dynamic color, using the dynamic_color Flutter package provided by the Material team.

Using Material 3

For this tutorial, we will be working with the basic Flutter counter app example, but with one small change. We will change the provided theme from the below:

ThemeData(
    primarySwatch: Colors.blue,
)

To this:

ThemeData(
    colorScheme: ColorScheme.fromSwatch(primarySwatch: Colors.blue),
    useMaterial3: true,
)

We do this in order to enable Material 3 using the useMaterial3 flag. Not all widgets in Flutter are "Material 3-ready" as of yet, so we need to enable this explicitly.

We replace primarySwatch with colorScheme, but these actually do the same thing. However, colorScheme is now actually the preferred way to configure colors. We also do this because we will use colorScheme for the dynamic color.

We've also added three boxes showing the color scheme's primary, secondary and tertiary colors. This is so we can compare and see what happens to the color scheme once we've implemented dynamic color.

Here is how our app looks before and after this, if you're curious.

Using dynamic color

The `dynamic_color` package

The Material team has already created a package to help with this. It returns a Material color scheme based on a platform's implementation of dynamic color. This is actually not specific to just Material 3 and Android!

From the package's GitHub repo page, here is what you get from each platform:

Android (12 and up) - color from the wallpaper
Linux - GTK+ theme's @theme_selected_bg_color
macOS - app accent color
Windows - accent color or window/glass color

Let's install the package:

flutter pub add dynamic_color

Alternatively, add this to your pubspec.yaml:

dependencies:
  dynamic_color: ^1.4.0

The `DynamicColorBuilder` widget

Let's now make use of the dynamic_color package to actually use dynamic colors. We can do this with the DynamicColorBuilder, a builder widget that uses a plugin under the hood to fetch the dynamic color from the OS and returns a light and dark color scheme.

DynamicColorBuilder({
    Key? key,
    required this.builder,
})

DynamicColorBuilder accepts an optional key and requires a builder which should return whatever widget we want to enhance with dynamic colors. The builder widget's signature looks like this:

Widget Function(
    ColorScheme? lightDynamic,
    ColorScheme? darkDynamic,
)

We can return a widget, any widget, and the builder includes a light dynamic color scheme as well as a dark dynamic color scheme. Both color schemes are nullable; if the OS does not respond or the platform does not support dynamic color (like with older Android versions), it returns null.

Using dynamic color schemes

We now have the dynamic_color package installed, and know how the DynamicColorBuilder widget works. Let's use it to make use of the system's color scheme.

Here's what the build method of our root MyApp widget looks like now:

@override
Widget build(BuildContext context) {
  return DynamicColorBuilder(builder: (lightColorScheme, darkColorScheme) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: lightColorScheme ?? _defaultLightColorScheme,
        useMaterial3: true,
      ),
      darkTheme: ThemeData(
        colorScheme: darkColorScheme ?? _defaultDarkColorScheme,
        useMaterial3: true,
      ),
      themeMode: ThemeMode.dark,
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  });
}

We've wrapped the MaterialApp widget with DynamicColorBuilder. For the theme, we replaced the previous colorScheme with the light color scheme provided by the builder. We also provided a darkTheme in addition to theme, which uses the dark color scheme provided by the builder. Note that since both color schemes are nullable, we have default color schemes, which we've extracted to static constants.

static final _defaultLightColorScheme =
    ColorScheme.fromSwatch(primarySwatch: Colors.blue);

static final _defaultDarkColorScheme = ColorScheme.fromSwatch(
    primarySwatch: Colors.blue, brightness: Brightness.dark);

These are exactly what we had before, with additionally the dark color scheme which we define in exactly the same way, plus the dark brightness value.

And that's it! With just a trivial amount of lines of code added (less than 10 if you don't count the default color schemes), we have a theme with a color scheme which dynamically changes depending on your operating system's settings. Here's how it looks like now:

A small note if you're implementing this for your app. In debug mode, when the app loads for the first time you may quickly see the app load with the default color scheme for a split second before refreshing with the dynamic color scheme. Not to worry though, this won't be the case for your production app!

Wrapping up

In this tutorial, we showed how to implement dynamic color in themes in our Flutter app, to make use of the Material 3, or You, dynamic color feature available in Android 12.

You can find the full source code here.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email here.

How to create a custom plugin in Flutter to call native platform code

Christos — Mon, 04 Jul 2022 19:16:00 +0000

Introduction

In this tutorial, we will create a Flutter plugin which targets the Android and iOS platforms, and show how to invoke different methods from Dart, pass arguments of different types, and receive and parse results from the host platforms. The platform code won't actually call any real native APIs, but rather return some hard-coded data. But by the end of this tutorial, doing that part should hopefully be easy!

Flutter is mainly a UI framework, and so for a lot platform-specific functionality, we usually use plugins, typically created by the Dart and Flutter community, to achieve things such as getting the current battery level, or displaying local notifications. However, in some cases, there might not be a plugin already available, or the platform we are targeting might not be supported. In such cases, writing our own custom plugin (or contributing to an existing plugin), might be our only option.

Starting with the plugin template

To get started, we'll create a Flutter plugin using flutter create with the plugin template.

flutter create --org dev.dartling --template=plugin --platforms=android,ios app_usage

This will generate the code for the plugin, as well as an example project that uses this plugin. By default, the generated Android code will be in Kotlin, and iOS in Swift, but you can specify either Java or Objective-C with the -a and -i flags respectively. (-a java and/or -i objc).

Of course, you could target more platforms if you want. For this tutorial, we will only be targeting Android and iOS.

Next, let's take a look at the generated Dart, Kotlin and Swift code after running flutter create.

Dart code

This auto-generated plugin is an AppUsage Dart class with a MethodChannel, and a method which invokes a specific method name in this channel. This getPlatformVersion method is implemented in both Android and iOS to return the current platform version.

class AppUsage {
  static const MethodChannel _channel = MethodChannel('app_usage');

  static Future<String?> get platformVersion async {
    final String? version = await _channel.invokeMethod('getPlatformVersion');
    return version;
  }
}

The MethodChannel constructor accepts a channel name, which is the name of the channel on which communication between the Dart code and the host platform will happen. This name is typically the plugin name, and this is what the generated code uses, but some plugins usually use a combination of the application package/ID or domain. So for this example we could go for something like dev.dartling.app_usage or dartling.dev/app_usage.

Let's dig a little deeper into MethodChannel#invokeMethod:

 Future<T?> invokeMethod<T>(String method, [ dynamic arguments ])

We can specify which type we expect to be returned by the method channel, and the future's result can always be null. So in the platformVersion getter above, we could be more explicit and use _channel.invokeMethod<String>('getPlatformVersion') instead.

Kotlin code (Android)

// AppUsagePlugin.kt
class AppUsagePlugin : FlutterPlugin, MethodCallHandler {
    private lateinit var channel: MethodChannel

    override fun onAttachedToEngine(@NonNull flutterPluginBinding: FlutterPlugin.FlutterPluginBinding) {
        channel = MethodChannel(flutterPluginBinding.binaryMessenger, "app_usage")
        channel.setMethodCallHandler(this)
    }

    override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
        if (call.method == "getPlatformVersion") {
            result.success("Android ${android.os.Build.VERSION.RELEASE}")
        } else {
            result.notImplemented()
        }
    }

    override fun onDetachedFromEngine(@NonNull binding: FlutterPlugin.FlutterPluginBinding) {
        channel.setMethodCallHandler(null)
    }
}

The onAttachedToEngine and onDetachedFromEngine methods are pretty standard and we won't have to touch them at all. One note about onAttachedToEngine, is the MethodChannel constructor which also accepts a channel name. This name should match whatever we pass in the constructor on the Flutter side of things, so if you decide to go with a different name, make sure you change it in the constructors of all platforms.

The onMethodCall method is where the bulk of the logic happens, and will happen, when we add more functionality to our plugin. This method accepts two parameters. The first, the MethodCall, contains the data we pass from the invokeMethod invocation in Dart. So, MethodCall#method will return the method name (String), and MethodCall#arguments contains any arguments we pass along with the invocation. arguments is an Object, and can be used in different ways, but more on that later.

The Result can be used to return data or errors to Dart. This must always be used, otherwise the Future will never complete, and the invocation would hang indefinitely. With result, we can use the success(Object) method to return any object, error(String errorCode, String errorMessage, Object errorDetails) to return errors, and notImplemented() if the method we are invoking is not implemented (this is what happens in the else block above).

Swift code (iOS)

// SwiftAppUsagePlugin.swift
public class SwiftAppUsagePlugin: NSObject, FlutterPlugin {
  public static func register(with registrar: FlutterPluginRegistrar) {
    let channel = FlutterMethodChannel(name: "app_usage", binaryMessenger: registrar.messenger())
    let instance = SwiftAppUsagePlugin()
    registrar.addMethodCallDelegate(instance, channel: channel)
  }

  public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
    result("iOS " + UIDevice.current.systemVersion)
  }
}

Note that in the generated Swift code, there are no checks for the getPlatformVersion method name. Let's make some changes to the handle method, to keep things consistent across the two platforms.

public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
if (call.method == "getPlatformVersion") {
    result("iOS " + UIDevice.current.systemVersion)
} else {
    result(FlutterMethodNotImplemented)
}

Similarly to Android/Kotlin, FlutterMethodCall has a method string and dynamic arguments. But FlutterResult is a bit different. For a "successful" return, you can just pass any value in result(...). If the method is not implemented, just pass FlutterMethodNotImplemented, as shown above. And for errors, pass FlutterError.init(code: "ERROR_CODE", message: "error message", details: nil).

Returning complex objects

Now that we've seen how the code looks across Dart and our target platforms, let's implement some new functionality. Let's say that our App Usage plugin should return a list of the used apps, showing how much time we spend on each app.

// app_usage.dart
static Future<List<UsedApp>> get usedApps async {
  final List<dynamic>? usedApps =
      await _channel.invokeListMethod<dynamic>('getUsedApps');
  return usedApps?.map(UsedApp.fromJson).toList() ?? [];
}

// models.dart
class UsedApp {
  final String id;
  final String name;
  final Duration timeUsed;

  UsedApp(this.id, this.name, this.timeUsed);

  static UsedApp fromJson(dynamic json) {
    return UsedApp(
      json['id'] as String,
      json['name'] as String,
      Duration(minutes: json['minutesUsed'] as int),
    );
  }
}

Notice that we actually expect a List<dynamic> rather than List<UsedApp> when we invoke a method from the channel, and map these to UsedApp using the fromJson method. This is because we cannot just cast complex objects, though this will work fine for simple types such as int, double, bool and String. Calling _channel.invokeMethod<UsedApp>(...) will result to this error:

The following _CastError was thrown building MyApp(dirty, state: _MyAppState#8bcb2):
type '_InternalLinkedHashMap<Object?, Object?>' is not a subtype of type 'UsedApp' in type cast

Also notice that we used the convenience invokeListMethod<T>, since we are expecting a list of items to be returned. The above method is equivalent to _channel.invokeMethod<List<dynamic>>(...). There is also the invokeMapMethod<K, V> if we are expecting a map.

Now, let's implement getUsedApps on the Android and iOS platforms. If we don't, and try to invoke this method from the example app (or any app), we will see this error:

Unhandled Exception: MissingPluginException(No implementation found for method getUsedApps on channel app_usage)

For Android, we have to update our onMethodCall function in AppUsagePlugin. We replace the if statement with a when, to make things a bit simpler.

// AppUsagePlugin.kt
class AppUsagePlugin : FlutterPlugin, MethodCallHandler {
    private var appUsageApi = AppUsageApi()

    override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
        when (call.method) {
            "getPlatformVersion" -> result.success("Android ${android.os.Build.VERSION.RELEASE}")
            "getUsedApps" -> result.success(appUsageApi.usedApps.stream().map { it.toJson() }
                .toList())
            else -> result.notImplemented()
        }
    }
}

When invoking getUsedApps, we simply use the AppUsageApi to return the used apps, map them to a list of JSON objects (actually just a map of string to a value), and return them with result.

This is what AppUsageApi looks like, if you're curious:

// AppUsageApi.kt
data class UsedApp(val id: String, val name: String, val minutesUsed: Int) {
    fun toJson(): Map<String, Any> {
        return mapOf("id" to id, "name" to name, "minutesUsed" to minutesUsed)
    }
}

class AppUsageApi {
    val usedApps: List<UsedApp> = listOf(
        UsedApp("com.reddit.app", "Reddit", 75),
        UsedApp("dev.hashnode.app", "Hashnode", 37),
        UsedApp("link.timelog.app", "Timelog", 25),
    )
}

Just a data class and some hard-coded values. We could have made this simpler and just returned a Map<String, Any> straight from here, but realistically, an API would return its own data classes/models.

Similarly, for iOS, we need to update the handle function in SwiftAppUsagePlugin.

// AppUsageApi
struct UsedApp {
    var id: String
    var name: String
    var minutesUsed: Int

    func toJson() -> [String: Any] {
        return [
            "id": id,
            "name": name,
            "minutesUsed": minutesUsed
        ]
    }
}

class AppUsageApi {
    var usedApps = [
        UsedApp(id: "com.reddit.app", name: "Reddit", minutesUsed: 75),
        UsedApp(id: "dev.hashnode.app", name: "Hashnode", minutesUsed: 37),
        UsedApp(id: "link.timelog.app", name: "Timelog", minutesUsed: 25)
    ]
}

// SwiftAppUsagePlugin.swift
public class SwiftAppUsagePlugin: NSObject, FlutterPlugin {
  private var appUsageApi = AppUsageApi()

  public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
    switch (call.method) {
        case "getPlatformVersion":
            result("iOS " + UIDevice.current.systemVersion)
        case "getUsedApps":
            result(appUsageApi.usedApps.map { $0.toJson() })
        default:
            result(FlutterMethodNotImplemented)
    }
  }
}

I will not be sharing many snippets from the example app and usages of the AppUsage functions, just to keep the tutorial shorter, but you can take a look at the source code here. But the actual usage of the plugin is quite simple. We are simply calling the static methods of AppUsage to get data from the host platform, and display it. But in case you're curious to see the method in action, this is how the example app looks like:

Passing arguments

So far, we've shown how to receive data from the host platform. Now what if we want to pass data instead? Let's introduce a new method to our App Usage API.

// app_usage.dart
static Future<String> setAppTimeLimit(String appId, Duration duration) async {
  final String? result = await _channel.invokeMethod('setAppTimeLimit', {
    'id': appId,
    'durationInMinutes': duration.inMinutes,
  });
  return result ?? 'Could not set timer.';
}

The difference with the previous method is that we're now also passing parameters to invokeMethod, which is an optional field. While the type of parameters is dynamic, and so could be anything, it's recommended to use a map.

Since our implementation won't actually set any app time limits, it would still be nice to confirm that the host platform has properly received the passed parameters, in our case id and minutes. So to keep things simple, we just want to return a string containing a confirmation that the time limit was set for the given app ID and duration.

Here's the Android/Kotlin implementation:

// AppUsageApi.kt
fun setTimeLimit(id: String, durationInMinutes: Int): String {
    return "Timer of $durationInMinutes minutes set for app ID $id";
}

// AppUsagePlugin.kt
override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
    when (call.method) {
        ...
        "setAppTimeLimit" -> result.success(
            appUsageApi.setTimeLimit(
                call.argument<String>("id")!!,
                call.argument<Int>("durationInMinutes")!!
            )
        )
        else -> result.notImplemented()
    }
}

We get the arguments from the passed parameters using MethodCall#argument, and specify the type we expect the argument to have. This method only works if the parameters passed are either a map or a JSONObject. The method returns an optional result we could be null, hence the !! operator. If the argument for that key in the map is missing or has a different type, an exception is thrown.

Alternatively, we could return the whole map by using:

call.arguments()

We can also check if the argument exists by using:

call.hasArgument("id") // true
call.hasArgument("appId") // false

Next, the iOS/Swift code:

// AppUsageApi
func setTimeLimit(id: String, durationInMinutes: Int) -> String {
    return "Timer of \(durationInMinutes) minutes set for app ID \(id)"
}

// SwiftAppUsagePlugin.swift
public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
  switch (call.method) {
      ...
      case "setAppTimeLimit":
          let arguments = call.arguments as! [String: Any]
          let id = arguments["id"] as! String
          let durationInMinutes = arguments["durationInMinutes"] as! Int
          result(appUsageApi.setTimeLimit(id: id, durationInMinutes: durationInMinutes))
      default:
          result(FlutterMethodNotImplemented)
  }
}

Very similar, but unlike Kotlin, there are no convenience methods to get an argument by its key. Instead, we need to cast call.arguments to a map of String to Any, and then cast each argument to the type we expect it in. Both the arguments and any values in the map can be null, which is why we need the ! operator when casting.

And that's it for the platform implementations! In the example app, I've added an icon button which calls this method and displays snackbar with the result string.

// EXAMPLE APP: main.dart
IconButton(
  icon: const Icon(Icons.timer_outlined),
  onPressed: () async {
    // TODO: Set duration manually.
    final String result = await AppUsage.setAppTimeLimit(
        app.id, const Duration(minutes: 30));
    ScaffoldMessenger.of(context)
        .showSnackBar(SnackBar(content: Text(result)));
  },
)

Error handling

We've now learned how to read data returned from the host platform, and pass data to the host platform. For the last part, we'll return an error from the platform side and catch it.

For this example, we'll just be doing this on the Android side. Let's improve the implementation for setAppTimeLimit.

override fun onMethodCall(@NonNull call: MethodCall, @NonNull result: Result) {
    when (call.method) {
        ...
        "setAppTimeLimit" -> {
            if (!call.hasArgument("id") || !call.hasArgument("durationInMinutes")) {
                result.error(
                    "BAD_REQUEST",
                    "Missing 'id' or 'durationInMinutes' argument",
                    Exception("Something went wrong")
                )
            }
            result.success(
                appUsageApi.setTimeLimit(
                    call.argument<String>("id")!!,
                    call.argument<Int>("durationInMinutes")!!
                )
            )
        }
        else -> result.notImplemented()
    }

If either the id or durationInMinutes arguments are missing from the method call, we'll throw a more helpful exception. Otherwise, we'd just get a null pointer exception when calling call.argument<T>("key")!!.

This results in a PlatformException being thrown from invokeMethod on the Flutter side. To handle it, we could do the following.

static Future<String> setAppTimeLimit(String appId, Duration duration) async {
  try {
    final String? result = await _channel.invokeMethod('setAppTimeLimit', {
      'appId': appId,
      'durationInMinutes': duration.inMinutes,
    });
    return result ?? 'Could not set timer.';
  } on PlatformException catch (ex) {
    return ex.message ?? 'Unexpected error';
  }
}

In the snippet above we replaced the id argument with appId, which will lead to a platform exception.

Alternatives

One not-so-nice aspect of host platform to Flutter communication with MethodChannel is the serialization/deserialization part. When passing many arguments, we need to pass them in a map, and accessing them, casting them, and checking if they exist is not very nice. Same for parsing data returned from the method calls; for this tutorial we needed to map the UsedApp list to a JSON-like map from the Kotlin/Swift code, and then implement a method to create a UsedApp from the returned list on the Flutter side. This can be time-consuming, but also error-prone (all our fields/keys are hard-coded strings and have to be kept in sync across 3 different languages!).

Enter Pigeon, an alternative to MethodChannel for Flutter to host platform communication. It is a code generator tool which aims to make this type-safe, easier and faster. With Pigeon, you just have to define the communication interface, and code generation takes care of everything else. In this post, we explore using Pigeon as an alternative to method channels and build the exact same functionality as with this tutorial. If you're curious, check it out and see how it compares!

Wrapping up

In this tutorial, we created a custom Flutter plugin with both Android and iOS implementations to call (fake) native functionality. We showed how to send and retrieve data from the host platforms, as well as throw errors and handle them.

You can find the full source code here.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email here.

Swipe actions in Flutter with the Dismissible widget

Christos — Tue, 21 Jun 2022 20:28:29 +0000

Introduction

Swipe actions, or swipe gestures, are something that's very common in mobile apps. In its most common form, the "swipe to dismiss" pattern is something you might have seen in email apps, for example, where you swipe left to delete an email. Some apps now even let you customize the action happening when you swipe left or right (hence swipe actions), and you don't necessarily have to dismiss something either; an example would be the "swipe to reply" pattern implemented in some messaging apps.

In this post, we will go over how to implement swipe actions in Flutter using the Dismissible widget. We will implement a "swipe to delete" action for a (very) simple messaging app, with a confirmation dialog, as well as a "swipe to star (favorite)" action.

In case you're still unsure about what a "swipe action" looks, here's what we'll be building in this post:

At the end, if actions for swiping left or right are not enough for you, we will show how to easily implement multiple "slide" actions with the flutter_slidable package.

The `Dismissible` widget

We can make any widget "dismissible" by wrapping it with the Dismissible widget:

Dismissible(
  key: UniqueKey(),
  child: const ListTile(
    leading: Icon(Icons.flutter_dash),
    title: Text('Dash'),
    subtitle: Text('Hello!'),
  ),
),

At a minimum, this widget requires a child, which can be any widget we want to dismiss/swipe/slide, as well as a key. With the above code snippet, what we have is a regular ListTile widget which disappears when swiped in any horizontal direction.

Directions

By default, a dismissible widget can be swiped left or right. But we can customize this.

Dismissible(
  key: UniqueKey(),
  direction: DismissDirection.endToStart,
  onDismissed: (DismissDirection direction) {
    log('Dismissed with direction $direction');
  },
  child: ...
),

With endToStart, our widget can only be swiped from its end to the start. In our case, this is a swipe to the left. However, this is either right-to-left or left-to-right depending on the reading direction of the Flutter app's locale. English is read from left to right, so endToStart is right to left.

Below are the possible DismissDirection values:

endToStart - Can be swiped left (or right depending on reading direction).
startToEnd - Can be swiped right (or left depending on reading direction).
horizontal - Can be swiped both left and right.
up - Can be swiped up.
down - Can be swiped down.
vertical - Can be swiped both up and down.
none - Cannot be swiped, or dismissed.

The none value might seem a bit redundant, as you could just not wrap a widget with the Dismissible widget at all. But there might be cases where you have a list of dismissible widgets, and might want to dynamically choose whether a specific item in the list can be dismissed or not. In that case, you could use none.

The onDismissed callback is called after a widget is swiped and dismissed. It is called with the direction it was dismissed in. If your widget should only be swiped in one direction, you might not use this, but if you use the horizontal or vertical directions, you could check in which direction the widget was dismissed if you want to react differently for each direction.

Swipe, but don't dismiss

The "swipe to dismiss" part has been quite easy so far, it already works! But what if you don't want to dismiss? The confirmDismiss callback parameter is called before the widget is dismissed, and returns a Future<bool>. If false is returned, the widget is not dismissed.

This helps if, for example, you want to a confirm a dismissal or deletion; you could show a dialog so that the user can confirm their action. Or maybe your swipe action might never dismiss the widget at all; in that case you'd just always return false.

Implementing swipe actions

Now that we have a basic Dismissible widget working, let's implement some swipe actions for our messaging app. When swiping left, we want to delete a message. When swiping right, we want to "star"/favorite the message.

Swipe to delete

Here's our widget so far:

Dismissible(
  key: UniqueKey(),
  direction: DismissDirection.endToStart,
  onDismissed: (DismissDirection direction) {
    log('Dismissed with direction $direction');
    // Your deletion logic goes here.
  },
  child: const ListTile(
    leading: Icon(Icons.flutter_dash),
    title: Text('Dash'),
    subtitle: Text('Hello!'),
  ),
),

This is really all we need for the "swipe to delete" action. The widget is dismissed as soon as we finish swiping, so for a basic demo this is enough. In a real app, you might have to add some additional logic in the onDismissed callback, for example to actually delete the message from your database.

Confirm dismissal/deletion

A problem with "destructive" swipe actions such as "swipe to delete" is that a user could easily swipe something left accidentally. For our deletion swipe action, we can make use of the confirmDismiss callback to ask the user if they really want to delete their message.

Dismissible(
  key: UniqueKey(),
  direction: DismissDirection.endToStart,
  onDismissed: (DismissDirection direction) {
    log('Dismissed with direction $direction');
    // Your deletion logic goes here.
  },
  confirmDismiss: (DismissDirection direction) async {
    final confirmed = await showDialog<bool>(
      context: context,
      builder: (context) {
        return AlertDialog(
          title: const Text('Are you sure you want to delete?'),
          actions: [
            TextButton(
              onPressed: () => Navigator.pop(context, false),
              child: const Text('No'),
            ),
            TextButton(
              onPressed: () => Navigator.pop(context, true),
              child: const Text('Yes'),
            )
          ],
        );
      },
    );
    log('Deletion confirmed: $confirmed');
    return confirmed;
  },
  child: const ListTile(
    leading: Icon(Icons.flutter_dash),
    title: Text('Dash'),
    subtitle: Text('Hello!'),
  ),
),

A bit lengthier than before, but if we extract the AlertDialog part to a method or widget, the code is not very complicated.

Background

Right now, it's not clear that swiping will actually delete the message, even if we do show a confirmation dialog. We can specify a background parameter, which is of course a widget, and show a colored background with an icon.

Dismissible(
  key: UniqueKey(),
  direction: DismissDirection.endToStart,
  ...
  background: const ColoredBox(
    color: Colors.red,
    child: Align(
      alignment: Alignment.centerRight,
      child: Padding(
        padding: EdgeInsets.all(16.0),
        child: Icon(Icons.delete, color: Colors.white),
      ),
    ),
  ),
  child: const ListTile(
    leading: Icon(Icons.flutter_dash),
    title: Text('Dash'),
    subtitle: Text('Hello!'),
  ),
),

Here's how the deletion flow looks below, with the confirmation dialog.

Swipe to star

Now, here's where it gets a little trickier! For the "swipe to star" action, we don't want to dismiss the widget after swiping to the right, but we also want to behave differently depending on the swipe direction.

First, we change the direction of our Dismissible widget to horizontal, as we want to swipe both left as well as right. Second, both our onDismissed and confirmDismiss callback functions need to be updated.

For both functions, our deletion logic should only be called if the direction is endToStart. If not, we can assume it's startToEnd and include our starring logic.

Dismissible(
  key: UniqueKey(),
  direction: DismissDirection.horizontal,
  onDismissed: (DismissDirection direction) {
    log('Dismissed with direction $direction');
    if (direction == DismissDirection.endToStart) {
      // Your deletion logic goes here.
    }
  },
  confirmDismiss: (DismissDirection direction) async {
    if (direction == DismissDirection.endToStart) {
      final confirmed = await _confirmDeletion(context);
      log('Deletion confirmed: $confirmed');
      return confirmed;
    } else {
      log('Starring');
      // The widget is never dismissed in this case. Your star logic goes here.
      setState(() {
        _isStarred = !_isStarred;
      });
      return false;
    }
  },
  background: const ColoredBox(
    color: Colors.red,
    child: Align(
      alignment: Alignment.centerRight,
      child: Padding(
        padding: EdgeInsets.all(16.0),
        child: Icon(Icons.delete, color: Colors.white),
      ),
    ),
  ),
  child: ListTile(
    leading: const Icon(Icons.flutter_dash),
    title: const Text('Dash'),
    subtitle: const Text('Hello!'),
    trailing: Icon(_isStarred ? Icons.star : Icons.star_outline),
  ),
),

We've updated the message widget to show a filled star if it's starred, or an outlined star if not, and keep track of this with a simple boolean field in the state, just to keep things simple.

One thing to note here is that since we never want to dismiss the widget when we star a message, we always return false in confirmDismiss. Because of this, the onDismissed callback is never called, so our starring logic should be called in confirmDismiss, if the direction is what we expect.

Secondary background

There's one thing left; the background! We now show the red background with the trash icon when swiping both left and right. For starring, we would like to show an orange background with a star icon, and since we swipe right, the icon should be on the left. The Dismissible widget makes it very easy to have a separate background depending on the swipe direction.

For this case, we're going to have both a background and a secondaryBackground.

Dismissible(
  ...
  background: const ColoredBox(
    color: Colors.orange,
    child: Align(
      alignment: Alignment.centerLeft,
      child: Padding(
        padding: EdgeInsets.all(16.0),
        child: Icon(Icons.star, color: Colors.white),
      ),
    ),
  ),
  secondaryBackground: const ColoredBox(
    color: Colors.red,
    child: Align(
      alignment: Alignment.centerRight,
      child: Padding(
        padding: EdgeInsets.all(16.0),
        child: Icon(Icons.delete, color: Colors.white),
      ),
    ),
  ),
  child: ListTile(...),
),

Notice that the red deletion background is now actually the secondaryBackground, and the new orange background as the background, because of the directions.

Here is the "swipe to star" action implementation in action:

And that is all for the swipe-able message list tile! You can check out the full widget and app code in the source code here.

More on the `Dismissible` widget

We've gone over a lot of what the Dismissible widget can do, but its constructor accepts a few more optional arguments which we could make use of.

VoidCallback onResize - A callback function called (multiple times) just before the widget is dismissed, while being resized (contracted). Note: it's actually the background you see being contracted.
Duration? resizeDuration - The duration of the resizing/contracting that happens before the widget is dismissed. If you set this to a long enough duration, you can see the background widget slowly being "squeezed up" and disappearing. Set this to null and the background widget doesn't resize; it just stays there.
Map<DismissDirection, double> dismissThresholds - This is a useful one. It's a map of directions to a "threshold" (defaults to 0.4), which means that you have to drag a widget at least 40% in a given direction to actually perform the dismissal and the callbacks to be called. So you could raise or reduce the "sensitivity" of your swipe-able widgets.
Duration movementDuration - Not to be confused with resizeDuration, this is the duration of the widget sliding back to its place in case dismissal was not confirmed, or if you've already swiped past the threshold and the widget keeps moving on its own.
DismissUpdateCallback? onUpdate - Is called while the widget is being dragged. The details include the direction as well as whether the threshold has been reached. A use case for this, mentioned in the documentation, is that you could dynamically change the background of the dismissible widget as soon as the threshold is reached, rather than always displaying it.

Slide actions with `flutter_slidable`

We can now implement swipe-able widgets with different actions depending on the direction. If you want to do even more actions with a swipe, you can try out the flutter_slidable package. On swiping/sliding, the background reveals multiple actions that can be done.

We won't go into the implementation details here; the pub.dev page is already quite helpful! But here is what these "slide actions" would look like using the package:

Wrapping up

In this tutorial, we showed how to implement swipe actions (or gestures) to swipe to delete or star a message.

We also dug a little deeper into the Dismissible widget and what it can do (but of course the documentation also goes a good job explaining this!).

You can find the full source code here.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email here.

Displaying a loading overlay or progress HUD in Flutter

Christos — Thu, 19 May 2022 18:13:53 +0000

Introduction

Sometimes, in an app, you want to perform an asynchronous operation and want to prevent the user from tapping/using the app while this operation is in progress. A simple example would be when you create a new item/to-do in your to-do list app. After tapping on "save" or an equivalent button, the save operation would very likely be asynchronous; it might involve storing data to local storage, performing a network request, or both. This is usually a very quick operation, taking less than a second. But sometimes it could take a bit longer. During that time, you don't want users accidentally tapping the save button twice, or changing inputs.

The simplest solution to this would be to display a loading overlay while the operation is in progress. To do this, we're going to need a widget! And in this tutorial, we will do just that.

Defining a loading overlay, or progress HUD

To make sure we're on the same page, this is what the end result will be like:

Just a circular progress indicator with a semi-opaque dark background, covering the current screen and preventing any user input. This is typically called an overlay or a heads-up-display (HUD).

Re-inventing the wheel

Before we get started, you might not be interested in writing a custom solution for this and would rather use a package for this. If this is the case, there are tens of packages to do just this. Just search for "loading overlay", "loader overlay", or "progress hud" on pub.dev. I haven't used any personally, but loader_overlay looks well maintained and has a nice API.

At the same time, this is almost trivial to implement, so I'd encourage you to just use your own solution (or copy this one!), and simply adjust it to work for you. Introducing an entirely new package to only do this might be a bit too much.

Building the overlay in 2 steps

In this tutorial, we will build the loading overlay widget in 3 steps, building on top of the example Flutter counter app. In the first step, we'll simply make the overlay work on the main screen of the app, without any re-usable code. In the second step, we'll extract our overlay code to a new widget that we can re-use anywhere.

If you're just here for the code, just go ahead and skip to step #2, or see the code in the repository here.

Step #1: Using a `Stack`

In this tutorial we'll be working with the example Flutter app. If you want to follow along, you can create this with the following command:

flutter create <app_name>

The loading overlay widget is actually very simple; it is just the current screen/view/widget, wrapped in a Stack, with the semi-opaque overlay and a centered circular progress indicator at the top of the stack.

@override
Widget build(BuildContext context) {
  return Stack(
    children: [
      Scaffold(
        ...
      ),
      const Opacity(
        opacity: 0.8,
        child: ModalBarrier(dismissible: false, color: Colors.black),
      ),
      const Center(
        child: CircularProgressIndicator(),
      ),
    ],
  );
}

With the change above, we now have a permanent loading overlay in front of the Scaffold. Let's introduce a new state variable, _isLoading, and only show the Opacity and Center widgets if its value is true.

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;
  bool _isLoading = false;

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        Scaffold(
          ...
        ),
        if (_isLoading)
          const Opacity(
            opacity: 0.8,
            child: ModalBarrier(dismissible: false, color: Colors.black),
          ),
        if (_isLoading)
          const Center(
            child: CircularProgressIndicator(),
          ),
      ],
    );
  }
}

Let's make a small tweak to the _incrementCounter method to test this. When the method is called, we set _isLoading to true, wait 3 seconds, and then set it back to false and increment the counter.

void _incrementCounter() async {
  setState(() {
    _isLoading = true;
  });
  await Future.delayed(const Duration(seconds: 3));
  setState(() {
    _counter++;
    _isLoading = false;
  });
}

And that's it! Easy, right? Now, this loading overlay code is mixed up with the other view logic, and if we have to push a new view on top of this one (Navigator.push(context, ...)), we'd need to implement this all over again.

Step #2: Extracting the `LoadingOverlay` widget

// loading_overlay.dart
class LoadingOverlay extends StatefulWidget {
  const LoadingOverlay({Key? key, required this.child}) : super(key: key);

  final Widget child;

  static _LoadingOverlayState of(BuildContext context) {
    return context.findAncestorStateOfType<_LoadingOverlayState>()!;
  }

  @override
  State<LoadingOverlay> createState() => _LoadingOverlayState();
}

class _LoadingOverlayState extends State<LoadingOverlay> {
  bool _isLoading = false;

  void show() {
    setState(() {
      _isLoading = true;
    });
  }

  void hide() {
    setState(() {
      _isLoading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        widget.child,
        if (_isLoading)
          const Opacity(
            opacity: 0.8,
            child: ModalBarrier(dismissible: false, color: Colors.black),
          ),
        if (_isLoading)
          const Center(
            child: CircularProgressIndicator(),
          ),
      ],
    );
  }
}

Notice the LoadingOverlay.of() function, which actually returns _LoadingOverlayState. In the state we expose two public functions, show and hide, which respectively show and hide the loading overlay.

The context.findAncestorStateOfType<T>() function returns any ancestor matching this state class, which can be null if there is no such ancestor. In this example, we can simply assume there will always be one and use !. Or, we could assert it is not null before returning it, throwing an error with a useful message.

Now, in order for _LoadingOverlayState to be an "ancestor" in our app's widget tree, we need to wrap our main view with the LoadingOverlay widget, by making the following changes:

// MyApp
@override
Widget build(BuildContext context) {
  return MaterialApp(
    title: 'Flutter Demo',
    theme: ThemeData(
      primarySwatch: Colors.blue,
    ),
    home: const LoadingOverlay(
      child: MyHomePage(title: 'Loading Overlay'),
    ),
  );
}

Note that we reverted the changes initially made in _MyHomePageState, as the Stack and overlay widgets have now been moved to the LoadingOverlay widget.

By simply passing MyHomePage as a child in LoadingOverlay, we can toggle the loading overlay at any point within the MyHomePage widget or any of its child widgets by calling LoadingOverlay.of(context).

To see our changes in action, let's change the _incrementCounter method again.

void _incrementCounter() async {
  LoadingOverlay.of(context).show();
  await Future.delayed(const Duration(seconds: 3));
  setState(() {
    _counter++;
  });
  LoadingOverlay.of(context).hide();
}

We now have a reusable LoadingOverlay widget that we can use any time we want to toggle such an overlay. No external packages needed, and all in a stateless widget of less than 50 lines of code.

Note that if we push a new view/widget on top of this one, the context there will not have a LoadingOverlay ancestor. So we'd need to wrap any newly pushed views with another LoadingOverlay.

Navigator.push(
    context,
    MaterialPageRoute(
        builder: (_) => const LoadingOverlay(child: NewPage())));

And that's it for the main part of this tutorial. Next, we will make some small improvements to the LoadingOverlay widget and make it more customizable. After that, in the following step, we will make the widget stateless rather than stateful. If you're not interested, feel free to skip ahead to the end of the post.

Improvement #1: Tweaks

In some cases, the operations you show the loading overlay for might take less than a second, or even half a second. In such cases, you might still want to show an overlay to block user interactions, but not the spinner/circular progress indicator.

We can make a small tweak to our LoadingOverlay widget to delay the circular progress indicator by a duration of our choice, by using a FutureBuilder.

class LoadingOverlay extends StatefulWidget {
  const LoadingOverlay({
    Key? key,
    required this.child,
    this.delay = const Duration(milliseconds: 500),
  }) : super(key: key);

  final Widget child;
  final Duration delay;

  ...
}

// _LoadingOverlayState
...
Center(
  child: FutureBuilder(
    future: Future.delayed(widget.delay),
    builder: (context, snapshot) {
      return snapshot.connectionState == ConnectionState.done
          ? const CircularProgressIndicator()
          : const SizedBox();
    },
  ),
),
...

The delay parameter is optional and defaults to 500 milliseconds.

Another change we can do is blur the background when we show the overlay. This can be done, of course, with another widget; BackdropFilter and ImageFilter.blur.

BackdropFilter(
  filter: ImageFilter.blur(sigmaX: 4.0, sigmaY: 4.0),
  child: const Opacity(
    opacity: 0.8,
    child: ModalBarrier(dismissible: false, color: Colors.black),
  ),
),

Another potential tweak would be to show something else rather than a CircularProgressIndicator. If you want this to vary depending on what you use it for, it could just be an additional Widget parameter that you can simply pass when you create a LoadingOverlay. Or it could even be optional and default to CircularProgressIndicator.

Improvement #2: Going stateless

I'm a big fan of stateless widgets, and try to avoid stateful widgets when I can. For this loading overlay widget, the only state we need to manage and change is a boolean value that determines whether the overlay is shown or not. Rather than with a stateful widget, we could achieve this by using a ValueNotifier and a ValueListenableBuilder.

class LoadingOverlayAlt extends StatelessWidget {
  LoadingOverlayAlt({Key? key, required this.child})
      : _isLoadingNotifier = ValueNotifier(false),
        super(key: key);

  final ValueNotifier<bool> _isLoadingNotifier;
  final Widget child;

  static LoadingOverlayAlt of(BuildContext context) {
    return context.findAncestorWidgetOfExactType<LoadingOverlayAlt>()!;
  }

  void show() {
    _isLoadingNotifier.value = true;
  }

  void hide() {
    _isLoadingNotifier.value = false;
  }

  @override
  Widget build(BuildContext context) {
    return ValueListenableBuilder<bool>(
      valueListenable: _isLoadingNotifier,
      child: child,
      builder: (context, isLoading, child) {
        return Stack(
          children: [
            child!,
            if (isLoading)
              const Opacity(
                opacity: 0.8,
                child: ModalBarrier(dismissible: false, color: Colors.black),
              ),
            if (isLoading)
              const Center(
                child: CircularProgressIndicator(),
              ),
          ],
        );
      },
    );
  }
}

We simply initialize the value notifier with a default false value, and expose methods that update its value. The ValueListenableBuilder will be rebuilt every time the notifier's value changes, so we end up with the same result as doing a setState with a stateful widget.

Note that we now use context.findAncestorWidgetOfExactType<T>() instead of context.findAncestorStateOfType<T>(), as the widget is now stateless, and the show and hide methods are part of this stateless widget.

Surprisingly (for me, at least!), switching from a stateful to a stateless widget does not really decrease the lines of code in the widget by a lot. And since we initialize the ValueNotifier in the constructor, the constructor can no longer be constant. So in the end, this might be less of an improvement but more of a matter of preference.

Wrapping up

In this tutorial, we created a loading overlay widget and implemented functionality to easily display and hide it, without external packages and less than 70 lines of code. Without the spinner delay and blur filter tweaks, this is even less, at around 50 lines.

You can find the full source code here.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email here.

Implementing True Black dark theme mode in Flutter

Christos — Tue, 25 Jan 2022 19:57:00 +0000

Introduction

If you've been using Flutter for a while, you already know theming with Flutter is very easy, and switching between light and dark mode is available out-of-the-box, something which can be a pain to implement with other frameworks if you don't build your app with this in mind.

But what if light and dark mode is not enough for you? What if you want to implement a "true black", "true dark", "lights out" or "OLED dark mode", or whatever the proper name for this extra mode is...?

This is not trivial to do, but if you really wanted, you could configure ThemeData to have darker colors and use the "true" black color (Color(0xFF000000), or Colors.black in the material library). Theming in Flutter is easy, after all!

But there's a simpler, even easier way to implement this mode. Enter flex_color_scheme.

The `flex_color_scheme` package

flex_color_scheme is a package that allows you to easily build color scheme based Flutter themes. It has lots of beautiful built-in themes available, but you can also easily create your own by specifying a primary color and an optional secondary color. With this package, enabling "true black" mode is as simple as setting a value to true.

Installing the package

Run this in your terminal to install the package:

flutter pub add flex_color_scheme

Or just add the dependency in pubspec.yaml:

dependencies:
  flex_color_scheme: ^4.1.1

As of the time of writing of this post, the current version is 4.1.1.

Using the package

Now, let's set up a theme with flex_color_scheme. For this tutorial, I'll be using the default Flutter counter starter app.

Let's apply a new theme by updating the main build method:

@override
Widget build(BuildContext context) {
  return MaterialApp(
    title: 'Theming Tutorial',
    theme: FlexThemeData.light(scheme: FlexScheme.hippieBlue),
    darkTheme: FlexThemeData.dark(scheme: FlexScheme.hippieBlue),
    themeMode: ThemeMode.dark,
    home: const MyHomePage(),
  );
}

I'm a fan of the built-in Hippie Blue scheme, so I'll be using that one. FlexThemeData provides convenience extensions to return a ThemeData object given a scheme or colors.

You can specify your own colors which will override the scheme colors by using the FlexSchemeColor#of constructor and specifying a primary and an optional secondary color. The default scheme is FlexScheme.material.

FlexThemeData.light(colors: FlexSchemeColor.from(primary: Colors.blue, secondary: Colors.green))

Below is what our app looks like right now. Strangely, there is no blue in "hippie blue" dark mode! This is because, though the app bar is actually blue (primary color) in light mode, it's black in dark mode, as per the Material guidelines.

True black mode

Switching from dark mode to true black mode is easy. Simply set the darkIsTrueBlack in your flex theme data to true.

darkTheme: FlexThemeData.dark(
  scheme: FlexScheme.hippieBlue,
  darkIsTrueBlack: true,
),

Save your change, watch your app hot-reload, and... ta-da! Dark mode is now true black. On OLED screens, this can also preserve battery.

What does this flag actually do? It sets the scaffold background to black, as well as making other surfaces 8% darker.

Note: the darkIsTrueBlack flag is only available in FlexThemeData#dark. There is a lightIsTrueWhite equivalent in FlexThemeData#light, but is not as useful. Similarly to the dark flag, it sets the scaffold background to white, and other surfaces 8% lighter.

Supporting both dark and true black mode

So far, we've shown how to easily set up "true black" mode in our Flutter app. If that's all you're here for, feel free to skip this and jump to the conclusion!

But what if you'd like to support both "regular" dark mode, as well as "true black"? If your app has plenty of users, surely there will be preferences for both. Some users might find "true black" too dark, while others will want to take advantage of their device's OLED screen and use true black.

To support theme changing in the app, it's time to manage some state!

Switching between light and dark theme mode

Before adding this third theme option, we should note that there is an additional theme mode: ThemeMode.system. This will use the user's system theme: it may be light or dark. To get started, let's implement the option to switch between these 3 theme modes (light, dark, and system) in our app.

To implement this, I will use a ValueNotifier, along with a ValueListenableBuilder, just to keep things simple. You could instead do this with e.g. a ThemeController with the ChangeNotifier mixin, which could additionally store the user's selection to local storage (e.g. shared_preferences). Or, you could use a state management package of your choice. But this is outside the scope of this tutorial!

This is what our root widget looks like now:

void main() {
  // This could be loaded from storage e.g. with `shared_preferences`
  const themeMode = ThemeMode.system;
  runApp(MyApp(theme: themeMode));
}

class MyApp extends StatelessWidget {
  MyApp({Key? key, required ThemeMode theme})
      : _themeNotifier = ValueNotifier(theme),
        super(key: key);

  final ValueNotifier<ThemeMode> _themeNotifier;

  @override
  Widget build(BuildContext context) {
    return ValueListenableBuilder<ThemeMode>(
      valueListenable: _themeNotifier,
      child: MyHomePage(onThemeUpdate: onThemeUpdate),
      builder: (context, theme, child) {
        return MaterialApp(
          title: 'Theming Tutorial',
          theme: FlexThemeData.light(scheme: FlexScheme.hippieBlue),
          darkTheme: FlexThemeData.dark(
            scheme: FlexScheme.hippieBlue,
            darkIsTrueBlack: true,
          ),
          themeMode: theme,
          home: child,
        );
      },
    );
  }

  void onThemeUpdate(ThemeMode themeMode) {
    _themeNotifier.value = themeMode;
  }
}

We wrapped our MaterialApp with a ValueListenableBuilder. The value listenable of this builder is a ValueNotifier, initialized with the theme mode we passed when creating the root widget.

Every time we want to change the theme, we will change the value of _themeNotifier, which will trigger the builder and rebuild our MaterialApp widget.

Notice that we're now passing the function that will change the notifier's value down to the home page widget. Whenever we want to change the theme, we can use this function.

To change the theme, let's add a new action in the app bar.

return Scaffold(
  appBar: AppBar(
    title: Text(widget.title),
    actions: [
      IconButton(
        onPressed: _selectTheme,
        icon: const Icon(Icons.brightness_4_outlined),
      )
    ],
  ),
  ...
);

Future<void> _selectTheme() async {
  final theme = await _showThemePicker();
  if (theme != null) {
    widget.onThemeUpdate(theme);
  }
}

Future<ThemeMode?> _showThemePicker() {
  return showModalBottomSheet<ThemeMode>(
    context: context,
    builder: (context) {
      return SafeArea(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            ListTile(
              title: const Text('Light'),
              leading: const Icon(Icons.brightness_7_outlined),
              onTap: () {
                Navigator.pop(context, ThemeMode.light);
              },
            ),
            ListTile(
              title: const Text('Dark'),
              leading: const Icon(Icons.brightness_2_outlined),
              onTap: () {
                Navigator.pop(context, ThemeMode.dark);
              },
            ),
            ListTile(
              title: const Text('System'),
              leading: const Icon(Icons.settings_outlined),
              onTap: () {
                Navigator.pop(context, ThemeMode.system);
              },
            ),
          ],
        ),
      );
    },
  );
}

Lots of duplicate code, but I'll leave the refactoring up to you if you plan to use the same approach to theme changing!

When we tap on the "brightness" icon in the app bar, we are shown a modal bottom sheet with our 3 choices. By tapping on any of the themes, we call our function which updates the value of the ValueNotifier. This causes the app to rebuild, and we can see the theme changing.

Note 1: showModalBottomSheet can always also return null, for example when the user taps outside the modal or presses the back button. If it does, we don't do anything.

Note 2: We use SafeArea to wrap the body of the modal. This avoids intrusions by the operating system. For example, since this is a bottom sheet, a phone's notch could be hiding its contents, but wrapping the bottom sheet in a SafeArea widget will give it sufficient padding to avoid this (but only if there is a notch!).

Switching between light, dark, and true black mode

Now, to support a fourth option, true black mode, we can't keep using ThemeMode. Let's introduce a new ThemeOption enum.

enum ThemeOption { light, dark, system, trueBlack }

extension ThemeOptionUtils on ThemeOption {
  ThemeMode get themeMode {
    switch (this) {
      case ThemeOption.light:
        return ThemeMode.light;
      case ThemeOption.dark:
      case ThemeOption.trueBlack:
        return ThemeMode.dark;
      case ThemeOption.system:
        return ThemeMode.system;
    }
  }
}

ThemeOption.trueBlack will still map to ThemeMode.dark, but we'll get to this in a bit.

Let's also extract all the themes to a separate class, just to keep things simpler.

// app_theme.dart
class AppTheme {
  static const _scheme = FlexScheme.hippieBlue;

  static final light = FlexThemeData.light(scheme: _scheme);
  static final dark = FlexThemeData.dark(scheme: _scheme);
  static final trueBlack =
      FlexThemeData.dark(scheme: _scheme, darkIsTrueBlack: true);
}

Now, all that's left is to simply switch our value notifier from ThemeMode to ThemeOption. This is quite an easy change so I won't share the whole code as it's identical to the snippets share previously, but you can check the source code out on GitHub.

The only additional changes were the extra "true black" option in the theme picker, as well as the way the theme in MaterialApp is determined.

// _MyHomePageState#_showThemePicker
...
ListTile(
  title: const Text('True black'),
  leading: const Icon(Icons.brightness_1_outlined),
  onTap: () {
    Navigator.pop(context, ThemeOption.trueBlack);
  },
),
...

// MyApp
@override
Widget build(BuildContext context) {
  return ValueListenableBuilder<ThemeOption>(
    valueListenable: _themeNotifier,
    child: MyHomePage(onThemeUpdate: onThemeUpdate),
    builder: (context, themeOption, child) {
      return MaterialApp(
        title: 'Theming Tutorial',
        theme: AppTheme.light,
        darkTheme: themeOption == ThemeOption.trueBlack
            ? AppTheme.trueBlack
            : AppTheme.dark,
        themeMode: themeOption.themeMode,
        home: child,
      );
    },
  );
}

Very similar to what we had before, except now that the value listenable's value is of type ThemeOption, we need to map the option to ThemeMode to pass it as a MaterialApp argument. And the main change, to support true black mode, is to check whether the option is trueBlack, and if it is, use the appropriate darkTheme. And that's it! We can now choose between 4 different options.

Wrapping up

In this tutorial, we showed how to easily enable true black mode in a Flutter app with the flex_color_scheme package.

We also showed how to support both dark and true black modes (in addition to light mode, of course!) in the same app.

You can find the full source code here.

I am typically against introducing a new dependency just to introduce a small new feature. However, there is much more to flex_color_scheme than true black mode! I encourage you to take a look at the example, and dig deeper into the package.

If you found this helpful and would like to be notified of any future tutorials, please sign up with your email here.

Going full-stack with Flutter and Supabase - Part 2: Database

Christos — Mon, 24 May 2021 20:23:47 +0000

Introduction

In the previous part of this tutorial series, we went over what Supabase is, and started building a simple notes app with Supabase. So far, we got authentication working.

In this part, we will go over Supabase's Database offering. We will create a table to hold all the users' notes, and display them in the app, as well as let users create, edit and delete notes.

Code snippets for both widgets and services will be shared along the tutorial, but you can find the full source code here.

Postgres and Supabase

Supabase is built on top of Postgres, a relational database. Some basic knowledge of relational databases and SQL would help, but is not required, as Supabase makes it easy to view the database, its tables, and run queries through its admin interface.

We'll be making use of the SQL editor on Supabase's admin interface to run the SQL queries to create the tables we need.

Supabase also provides a nice "table editor" which lets you create tables without needing to write SQL. However, for the tutorial, it's actually easier to share SQL queries to run directly from the SQL editor. If you'll be working with Supabase, I'd recommend getting familiar with SQL anyway.

With the Supabase client, we can access the database with two ways:

RESTful API - This uses PostgREST behind the scenes, which is a thin API layer on top of Postgres, which allows you to write your queries straight from the client side of the code (our Flutter app). This is what we'll be using in this tutorial.
Realtime API - You can also listen to database changes over WebSockets with Supabase's Realtime server. We won't be using this in this tutorial.

Tables

A table is a collection of structured data that lives in the Postgres database. When using Supabase's authentication, when a user signs up, the user data is stored as a row in a users table. Each row has several columns, containing information such as email, creation date, etc. Note that the users table managed by Supabase is off-limits and cannot be accessed from the client. If we want to store additional user data, we'd need to create a new, separate table.

A table column has a type restriction: it can be a number, text, or something else. Once we create a table, this is not straight-foward to change, so we should think of our data model carefully first. But we can always add more columns later!

Each table has a column that is a primary key, a unique identifier which we can use to update or fetch specific rows from the table.

There are lots of useful resources on SQL, Postgres and relational databases out there if you're not familiar/comfortable with the concepts, but this tutorial should be easy to follow either way.

Data types

Postgres supports several data types, but we'll mostly be using integer and varchar/text. Once we create a table with columns of these data types, this schema is enforced and we cannot, for example, insert a string value in an integer column.

Another notable data type is Postgres' jsonb, which allows you to store JSON strings containing multiple fields of your data in a column. This is very flexible and useful if we're not sure how our data is going to look like in the beginning. You could start with a jsonb column and eventually move to something more structured. However, while it's more flexible, there's also no enforced schema on the data stored inside the column, so if you know what data you'll be storing in advance, it's recommended to just use multiple columns for each field.

One good use case of the jsonb data type would be if you're migrating from a non-relational database (e.g. Firebase) to Supabase. You could map all your documents to a row containing an ID (the primary key), and a jsonb column containing all the document data in JSON.

Part 2: Database

Creating our first database

The first table we'll be needing for this note app, is a notes table! For starters, our notes will have a title, optional content, and creation and modification timestamps. Since we're building a Flutter app, let's start with the Dart model first.

// models/note.dart
class Note {
  final int id;
  final String title;
  final String? content;
  final DateTime createTime;
  final DateTime modifyTime;

  Note(this.id, this.title, this.content, this.createTime, this.modifyTime);
}

We also need an id field so we can edit and delete notes.

Now that we have the model, let's create a table in Supabase. From the admin interface, select your project, and then the SQL editor tab. On the top left you should see a "New query" option. We can pass raw SQL queries in this editor and run them against our database. We'll do this for creating tables, and can also do this when having to quickly check out some data, or run some migrations.

Let's run the following query to create the notes table.

create table notes (
  id bigserial primary key,
  title text not null,
  content text,
  create_time timestamptz default now() not null,
  modify_time timestamptz default now() not null,
  user_id uuid references auth.users (id) default auth.uid() not null
);

Our first table is ready! In the Database tab, you can now see the notes table in the public schema.

The id field is a bigserial, which is a bigint that is generated automatically if left blank, and the values are incremented automatically. The timestamp fields default to the current time.

Every field is required except content, which is optional. The user_id field is not part of our model, but we need this on the database side as we'll need this field so we can return the correct data when fetching notes for a specific user.

The user_id column has a foreign key constraint and it references auth.users (id). This means each note created needs to have a user_id field that matches an id field in the users table in the auth schema in our database. If the user ID provided does not match an existing user, we won't be able to insert this note to our database.

The user_id value defaults to auth.uid(), which is a special function in Postgres, provided by Supabase, that returns the current user by extracting it from the JSON web token (discussed in the previous part about authentication).

The auth schema is used by Supabase for authentication. All tables we create for the notes app will be created in a separate public schema.

Note that we could omit the (id) in the SQL query above, as if there is no column specified as reference the primary key of that table is used, which in our case is id.

Fetching data

Now we want to fetch the notes of the currently signed in user to display in the app. We can do this directly from the Supabase client, which uses PostgREST behind the scenes.

Let's create a NotesService which will use the Supabase client to fetch the notes, and map them to our Note model.

Here is our updated Services inherited widget which will also now contain the NotesService so we can retrieve it from any widgets that need it.

class Services extends InheritedWidget {
  final AuthService authService;
  final NotesService notesService;

  Services._({
    required this.authService,
    required this.notesService,
    required Widget child,
  }) : super(child: child);

  factory Services({required Widget child}) {
    final client = SupabaseClient(supabaseUrl, supabaseKey);
    final authService = AuthService(client.auth);
    final notesService = NotesService(client);
    return Services._(
      authService: authService,
      notesService: notesService,
      child: child,
    );
  }

  @override
  bool updateShouldNotify(InheritedWidget oldWidget) {
    return false;
  }

  static Services of(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<Services>()!;
  }
}

And here is the NotesService:

class NotesService {
  static const notes = 'notes';

  final SupabaseClient _client;

  NotesService(this._client);

  Future<List<Note>> getNotes() async {
    final response = await _client.from(notes).select().execute();
    if (response.error == null) {
      final results = response.data as List<dynamic>;
      return results.map((e) => toNote(e)).toList();
    }
    log('Error fetching notes: ${response.error!.message}');
    return [];
  }

  Note toNote(Map<String, dynamic> result) {
    return Note(
      result['id'],
      result['title'],
      result['content'],
      DateTime.parse(result['create_time']),
      DateTime.parse(result['modify_time']),
    );
  }
}

By using select(), we return all columns of the notes table in the results. Since we actually don't need the user_id field, we can select only the fields we actually need.

Future<List<Note>> getNotes() async {
  final response = await _client
      .from(notes)
      .select('id, title, content, create_time, modify_time')
      .execute();
  if (response.error == null) {
    final results = response.data as List<dynamic>;
    return results.map((e) => toNote(e)).toList();
  }
  log('Error fetching notes: ${response.error!.message}');
  return [];
}

This query selects all notes, for all users. It would make sense for our query to have a where clause with the condition that the user_id field of the note matches the one of the currently signed in user. However, this query is run from the client, NOT the server. Which means, potentially, one could accidentally (or not) fetch notes of other users. This is one of the drawbacks of not having a back-end server, as all the data is available to all users by default. This is a huge issue, but the solution is actually pretty simple. Enter Policies.

Policies

Policies are a a PostgreSQL feature that allows you to define row level security policies for tables. This means, that even with the ability to run any query for a table, no rows will be visible or updatable unless the policy allows it.

To understand this better, let's create a policy:

create policy "Users can only view their own notes"
on notes
for select
using (auth.uid() = user_id);

This is a SQL query, which you can run from Supabase's admin interface. Now let's dig into the query. We're creating a policy with a useful description, on the notes table. This policy is for select statements. The condition for this policy, is that auth.uid() is the same as the user_id field of a note. As mentioned before, auth.uid() always returns the currently signed in user's ID.

This means, that even if we no longer filter on the user ID to fetch the notes for a user, only the notes of the current user will be returned. It's basically an automatic where clause! That's quite powerful, since if you set up your policies right, you don't have to worry about accidentally exposing data to the wrong users, or users updating or deleting data that is not their own.

Now, we've restricted users from selecting other users' notes, but what about other commands? There is still insert, update, and delete. But we can also use all for a policy, which will apply it to all commands.

create policy "Users can only view and update their own notes"
on notes
for all
using (auth.uid() = user_id)

That should do it! With this policy, we no longer need the previous one, as it's already covered by all.

Displaying notes

Now that our getNotes() function returns all notes for the current user, let's update our NotesPage widget to display them.

Just for testing, if you're curious if this is working as intended, we can add a note manually through a SQL query. Feel free to skip this part though, since next up we'll add functionality to actually create new notes.

To create a note manually, let's get our user's ID from the database with the following query.

select id from auth.users;

And let's insert a note for this user.

insert into notes values (1, 'My note', 'Note content', now(), now(), '2cb4a80a-3c75-4d80-86b0-d76a094cf915')

You could also add a note without needing SQL through the table editor.

Here is the updated NotesPage widget:

class NotesPage extends StatefulWidget {
  const NotesPage();

  @override
  _NotesPageState createState() => _NotesPageState();
}

class _NotesPageState extends State<NotesPage> {
  Future<void> _signOut() async {
    final success = await Services.of(context).authService.signOut();
    if (success) {
      Navigator.pushReplacement(
          context, MaterialPageRoute(builder: (_) => HomePage()));
    } else {
      ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('There was an issue logging out.')));
    }
  }

  Future<void> _addNote() async {
    // TODO
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Supanotes'),
        actions: [_logOutButton(context)],
      ),
      body: ListView(
        children: [
          FutureBuilder<List<Note>>(
            future: Services.of(context).notesService.getNotes(),
            builder: (context, snapshot) {
              final notes = (snapshot.data ?? [])
                ..sort((x, y) =>
                    y.modifyTime.difference(x.modifyTime).inMilliseconds);
              return Column(
                children: notes.map(_toNoteWidget).toList(),
              );
            },
          ),
        ],
      ),
      floatingActionButton: FloatingActionButton.extended(
        label: Text('Add note'),
        icon: Icon(Icons.add),
        onPressed: _addNote,
      ),
    );
  }

  Widget _logOutButton(BuildContext context) {
    return IconButton(
      onPressed: _signOut,
      icon: Icon(Icons.logout),
    );
  }

  Widget _toNoteWidget(Note note) {
    return ListTile(
      title: Text(note.title),
      subtitle: Text(note.content ?? ''),
    );
  }
}

We use a FutureBuilder to load the notes from the NotesService, and display the notes in a column. The notes are sorted by modify time (latest one first). We also changed the sign out button to be an action in the AppBar instead of a button in the page.

This was previously a stateless widget, but has been converted to a stateful widget for convenience; we will use setState after creating or changing notes to refresh the page.

If your notes page looks like in the screenshot below, you did everything correctly! Next, we're going to implement the logic to add a new note, which will be done through the FAB button that currently doesn't do anything.

Creating notes

Now, let's create the NotePage, where we'll be able to create a new note.

class NotePage extends StatefulWidget {
  const NotePage();

  @override
  _NotePageState createState() => _NotePageState();
}

class _NotePageState extends State<NotePage> {
  final _titleController = TextEditingController();
  final _contentController = TextEditingController();

  Future<void> _saveNote_() async {
    if (_titleController.text.isEmpty) {
      _showSnackBar('Title cannot be empty.');
    }
    final note = await Services.of(context)
        .notesService
        .createNote(_titleController.text, _contentController.text);
    if (note != null) {
      Navigator.pop(context, note);
    } else {
      _showSnackBar('Something went wrong.');
    }
  }

  void _showSnackBar(String text) {
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(text)));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('New note'),
      ),
      body: Column(
        children: <Widget>[
          Padding(
            padding: const EdgeInsets.all(8.0),
            child: TextField(
              controller: _titleController,
              decoration: InputDecoration(hintText: 'Title'),
            ),
          ),
          Padding(
            padding: const EdgeInsets.all(8.0),
            child: TextField(
              controller: _contentController,
              decoration: InputDecoration(hintText: 'Content'),
            ),
          ),
        ],
      ),
      floatingActionButton: FloatingActionButton.extended(
        onPressed: _saveNote,
        icon: Icon(Icons.save),
        label: Text('Save'),
      ),
    );
  }

  @override
  void dispose() {
    _titleController.dispose();
    _contentController.dispose();
    super.dispose();
  }
}

This page widget is simple. Two text fields, one for the title and one for the content. Pressing the FAB button saves the note to the database. When saving, we check that the title is not empty, and show a simple snackbar otherwise.

One thing to note is that since creating the note might take a while, we don't want the users to accidentally tab the "Add note" button twice and create duplicate notes. So we should introduce some mechanism to disable the button until we get the result from the notes service, but that's outside of the scope of this tutorial.

Here is the createNote function in NotesService:

// NotesService
Future<Note?> createNote(String title, String? content) async {
  final response = await _client
      .from(notes)
      .insert({'title': title, 'content': content}).execute();
  if (response.error == null) {
    final results = response.data as List<dynamic>;
    return toNote(results[0]);
  }
  log('Error creating note: ${response.error!.message}');
  return null;
}

Since most values are generated by default, with the exception of the title and content, all we need to pass to our insert query is these two fields. The response contains a list of all inserted records, which in our case is just the one note, which we return in this function, if there were no issues.

Now let's go back to the NotesPage and implement the _addNote_ function.

// NotesPage
Future<void> _addNote() async {
  final note = await Navigator.push<Note?>(
    context,
    MaterialPageRoute(builder: (context) => NotePage()),
  );
  if (note != null) {
    setState(() {});
  }
}

If a note is returned from the NotePage, we use setState to force the widget to reload, fetching all notes from the database again. We could optimize this part by maybe saving the notes in the widget's state, and rather than loading all notes from the database again, simply appending the new note. But let's keep it this way for simplicity!

Editing notes

In order to edit notes, let's change the NotePage a bit to support both creating and editing notes. We can pass an optional note to this widget, and if present, we can display its contents in the text fields, and call a function to edit the note rather than create a new one. Here's the updated constructor for NotePage widget:

class NotePage extends StatefulWidget {
  final Note? note;

  const NotePage({this.note});

  @override
  _NotePageState createState() => _NotePageState();
}

In the state widget, we override the initState method to populate the text fields with the note title and content if a note was passed in the constructor. The _saveNote function is updated to either create a new note, or update it. We also set the AppBar title accordingly.

// _NotePageState
@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(
      title: Text(widget.note != null ? 'Edit note' : 'New note'),
    ),
    ...
  );
}

@override
void initState() {
  super.initState();
  if (widget.note != null) {
    _titleController.text = widget.note!.title;
    _contentController.text = widget.note!.content ?? '';
  }
}

Future<void> _saveNote() async {
  final title = _titleController.text;
  final content = _contentController.text;
  if (title.isEmpty) {
    _showSnackBar('Title cannot be empty.');
    return;
  }
  final note = await _createOrUpdateNote(title, content);
  if (note != null) {
    Navigator.pop(context, note);
  } else {
    _showSnackBar('Something went wrong.');
  }
}

Future<Note?> _createOrUpdateNote(String title, String content) {
  final notesService = Services.of(context).notesService;
  if (widget.note != null) {
    return notesService.updateNote(widget.note!.id, title, content);
  } else {
    return notesService.createNote(title, content);
  }
}

And here is the service function to update the note:

// NotesService
Future<Note?> updateNote(int id, String title, String? content) async {
  final response = await _client
      .from(notes)
      .update({'title': title, 'content': content, 'modify_time': 'now()'})
      .eq('id', id)
      .execute();
  if (response.error == null) {
    final results = response.data as List<dynamic>;
    return toNote(results[0]);
  }
  log('Error editing note: ${response.error!.message}');
  return null;
}

The above function updates the title, content, and modify time fields for the note with the above ID. Because of the policy we set up before, the update will only happen if the note with the given ID was created by the current user. Passing now() in the modify time field will set the current time.

Now, let's make it so that if you tap on any note, the edit page will show up:

// NotesPage
Future<void> _editNote(Note note) async {
  final updatedNote = await Navigator.push<Note?>(
    context,
    MaterialPageRoute(builder: (context) => NotePage(note: note)),
  );
  if (updatedNote != null) {
    setState(() {});
  }
}

Widget _toNoteWidget(Note note) {
  return ListTile(
    title: Text(note.title),
    subtitle: Text(note.content ?? ''),
    onTap: () => _editNote(note),
  );
}

Very similarly to the creating notes implementation, if the NotePage is popped with a note, it means the note was updated, so we can rebuild the widget to display the changes.

When tapping on a note, you should now see this:

Deleting notes

So far, we can create new notes, and edit them. The next, and final step for this tutorial, is to delete them!

We'll wrap the note widgets in a Dismissible and call the delete function in the confirmDismiss function. If deletion is successful, we call setState on dismissal to rebuild the widget.

// NotesPage
Widget _toNoteWidget(Note note) {
  return Dismissible(
    key: ValueKey(note.id),
    direction: DismissDirection.endToStart,
    confirmDismiss: (_) =>
        Services.of(context).notesService.deleteNote(note.id),
    onDismissed: (_) => setState(() {}),
    background: Container(
      padding: const EdgeInsets.all(16.0),
      color: Theme.of(context).errorColor,
      alignment: Alignment.centerRight,
      child: Icon(Icons.delete),
    ),
    child: ListTile(
      title: Text(note.title),
      subtitle: Text(note.content ?? ''),
      onTap: () => _editNote(note),
    ),
  );
}

// NotesService
Future<bool> deleteNote(int id) async {
  final response = await _client.from(notes).delete().eq('id', id).execute();
  if (response.error == null) {
    return true;
  }
  log('Error deleting note: ${response.error!.message}');
  return false;
}

And that's it!

Wrapping up

In this part of the tutorial, we showed how to create a table in Supabase, and how to create, read, update and delete records from our Flutter app using the Supabase client. We also discussed policies, a powerful feature by Postgres that makes sure data from the database is secured and cannot be accessed by the wrong users through the Supabase client.

Next up, we'll dive into Supabase's Storage offering. We'll make use of this feature by implementing the functionality to attach files to notes. To do this, we will also introduce a simple one-to-many relationship between the notes table and a new attachments table.

If you'd like to be notified when the next part of this series is published, and for any future tutorials, please sign up with your email here.

Going full-stack with Flutter and Supabase - Part 1: Authentication

Christos — Fri, 14 May 2021 13:02:02 +0000

Introduction

In this tutorial series, we will build a simple notes app, powered by Supabase. Supabase is a product similar to Firebase, which provides services such as authentication and a database, as well as a client which allows you to authenticate and query the database directly from your Flutter app. By combining Flutter with Supabase, you could build production-ready* apps without having to write or maintain a back-end server.

This series will consist of three parts, each one going over a specific service by Supabase. First, we'll start with Authentication, which will allow users to sign in the app. Then, we'll move on to the Database, where we'll create a simple schema for our notes app, and allow users to create and view their notes. Last, we'll check out Storage, which we'll make use of by allowing users to attach files to their notes.

This tutorial assumes you already have some experience with Flutter (if not, go here to get started!). Code snippets will be shared as we go along, but you can also check out the full source code at the repository linked at the end of this post.

* Note that Supabase is still in public beta phase. However, it's still an exciting service, and now is a good time to experiment with it!

What is Supabase?

Supabase calls itself an open source alternative to Firebase. It offers several things: a relational database which you can access directly from the client, built-in user authentication so you can manage users and permissions, as well as storage so you can store large files. Functions are also in the works, which will allow you to run your own code without needing a server.

Why not Firebase?

While Supabase is considered an alternative, it's also very different. As always, there is no one right choice, and the best service to use depends on your use case. But Supabase has two stand-out features that Firebase does not have, which a lot of developers might prefer.

Relational database: Supabase is built on top of PostgreSQL, a powerful relational database that has been around for over 30 years. Firebase's Firestore and Realtime Database offerings are non-relational, so the choice between Supabase and Firebase might be as easy as relational vs non-relational, though there's more to it than that. Firebase is not open source, and has not been around as long as Postgres.
It's all open source: Supabase is built on top of other popular open-source packages, such as PostgREST for accessing your database directly from the client, and GoTrue for user authentication. All that, along with a nice admin interface so you can manage everything. If you wanted, you could host and manage these services on your own. If PostgREST does not fit your use case, you could host a server that will communicate with your Postgres database directly. And if you ever decide that Supabase is not for you, you could always migrate all your data somewhere else. At the end of the day, it's all in a Postgres database.

Getting Started

Setting up Supabase

Getting started with Supabase is simple, so we won't go into much detail about its setup. Just head to the Supabase website and create a project.

You can spend some time to get familiar with the admin interface, but we won't be needing it a lot for this first part. All we will need is your Supabase project's URL and API key, which you can find your project's API settings.

In auth settings, you can also have some options to change your site URL, which is included in emails sent by Supabase when a user signs up (which you can disable), as well as customize the email templates sent for password resets, magic links(!), and invitations.

You can also set up and run Supabase locally for local development by following the guide here.

Creating a new Flutter app

Now that we've got Supabase all set up, it's time to start building the app. Let's create a new Flutter app. Since this is a notes app built on Supabase, I'll be calling it Supanotes!

flutter create supanotes

Note: if null safety was not already enabled by default, you can do this by running the command below.

cd supanotes
dart migrate --apply-changes

We'll be making use of Dart's null safety features, but it for whatever reason you don't want to enable it for your app, you should still be able to follow along.

Part 1: Authentication

Now, let's make a very simple login page. Here is the UI code so far:

class SupanotesApp extends StatelessWidget {
  static const supabaseGreen = Color.fromRGBO(101, 217, 165, 1.0);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Supanotes',
      theme: ThemeData(
        brightness: Brightness.dark,
        primarySwatch: toMaterialColor(supabaseGreen),
      ),
      home: HomePage(),
    );
  }
}

class HomePage extends StatefulWidget {
  const HomePage();

  @override
  _HomePageState createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final _emailController = TextEditingController();
  final _passwordController = TextEditingController();

  void _signUp() {
    // Sign up logic will go here
  }

  void _signIn() {
    // Sign in logic will go here
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).primaryColor,
        title: Text('Supanotes'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Padding(
              padding: const EdgeInsets.all(8.0),
              child: TextField(
                controller: _emailController,
                keyboardType: TextInputType.emailAddress,
                decoration: InputDecoration(hintText: 'Email'),
              ),
            ),
            Padding(
              padding: const EdgeInsets.all(8.0),
              child: TextField(
                controller: _passwordController_,
                obscureText: true,
                decoration: InputDecoration(hintText: 'Password'),
              ),
            ),
            ElevatedButton.icon(
              onPressed: _signIn,
              icon: Icon(Icons.login),
              label: Text('Sign in'),
            ),
            ElevatedButton.icon(
              onPressed: _signUp,
              icon: Icon(Icons.app_registration),
              label: Text('Sign up'),
            ),
          ],
        ),
      ),
    );
  }

  @override
  void dispose() {
    _emailController.dispose();
    _passwordController.dispose();
    super.dispose();
  }
}

The toMaterialColor function is taken from this post here (thanks Filip!).

Adding the Supabase package

Let's implement the logic for sign in and sign up. First, we add the supabase package to our app.

flutter pub add supabase

Next, we'll create an AuthService that will handle anything auth related. In order to pass this service to any widget that needs it, we'll create an InheritedWidget that will hold all services we might need.

class Services extends InheritedWidget {
  final AuthService authService;

  Services._({
    required this.authService,
    required Widget child,
  }) : super(child: child);

  factory Services({required Widget child}) {
    final client = SupabaseClient(supabaseUrl, supabaseUrl);
    final authService = AuthService(client.auth);
    return Services._(authService: authService, child: child);
  }

  @override
  bool updateShouldNotify(InheritedWidget oldWidget) {
    return false;
  }

  static Services of(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<Services>()!;
  }
}

In this InheritedWidget, we initialize the Supabase client, and create the AuthService. To initialise the SupabaseClient, simply pass the URL and API keys from the API settings on the Supabase admin interface.

The GoTrue client

Supabase uses GoTrue for authentication. client.auth returns the GoTrue client, which is all the AuthService will need.

class AuthService {
  final GoTrueClient _client;

  AuthService(this._client);

  Future<bool> signUp(String email, String password) {
    // sign up logic goes here
  }

  Future<bool> signIn(String email, String password) {
    // sign in logic goes here
  }

  Future<bool> signOut() {
    // sign out logic goes here
  }
}

All three functions will return true if the response was successful, otherwise false.

Let's start with the signUp function:

// AuthService
Future<bool> signUp(String email, String password) async {
  final response = await _client.signUp(email, password);
  if (response.error == null) {
    log('Sign up was successful for user ID: ${response.user!.id}');
    return true;
  }
  log('Sign up error: ${response.error!.message}');
  return false;
}

This function will accept the email and password which we will pass from the text field widgets, and create a user. The client will return a GotrueSessionResponse, which will contain an error if something goes wrong, or a User and Session object.

We don't currently need to do anything with the User and Session objects, though it contains useful information we could make use of, such as the user's ID, last sign in date, and email confirmation date. However, these will always be accessible through GoTrueClient#currentUser and GoTrueClient#currentSession so we can grab them from the client when we need them.

Below are also the signIn and signOut functions, which are very similar to signUp.

// AuthService
Future<bool> signIn(String email, String password) async {
  final response = await _client.signIn(email: email, password: password);
  if (response.error == null) {
    log('Sign in was successful for user ID: ${response.user!.id}');
    return true;
  }
  log('Sign in error: ${response.error!.message}');
  return false;
}

Future<bool> signOut() async {
  final response = await _client.signOut();
  if (response.error == null) {
    return true;
  }
  log('Log out error: ${response.error!.message}');
  return false;
}

Now, let's call these AuthService functions in HomePage. Since the service is part of the Services InheritedWidget, we can freely access it through Services.of(context).authService. But to do that, we should first wrap MaterialApp with the Services widget. Our top level app widget should look like this:

class SupanotesApp extends StatelessWidget {
  static const supabaseGreen = Color.fromRGBO(101, 217, 165, 1.0);

  const SupanotesApp();

  @override
  Widget build(BuildContext context) {
    return Services(
      child: MaterialApp(
        title: 'Supanotes',
        theme: ThemeData(
          brightness: Brightness.dark,
          primarySwatch: toMaterialColor(supabaseGreen),
        ),
        home: HomePage(),
      ),
    );
  }
}

Now, we can call AuthService functions from any widget. Let's start with the logic for sign up.

// HomePage
void _signUp() async {
  final success = await Services.of(context)
      .authService
      .signUp(_emailController.text, _passwordController.text);
  if (success) {
    await Navigator.pushReplacement(
        context, MaterialPageRoute(builder: (_) => NotesPage()));
  } else {
    ScaffoldMessenger.of(context)
        .showSnackBar(SnackBar(content: Text('Something went wrong.')));
  }
}

If the response was successful, we navigate to a new page, the NotesPage, where we will display the user's notes. We call pushReplacement rather than push, since we don't want the user pressing back and ending up in the home page by mistake.

If the response fails, we just show a generic snack bar. This could display more useful information, based on the actual error.

The function for signing in is pretty much the same. We can reuse some of the code for both functions, and our code now looks like this:

// HomePage
void _signUp() async {
  final success = await Services.of(context)
      .authService
      .signUp(_emailController.text, _passwordController.text);
  await _handleResponse(success);
}

void _signIn() async {
  final success = await Services.of(context)
      .authService
      .signIn(_emailController.text, _passwordController.text);
  await _handleResponse(success);
}

Future<void> _handleResponse(bool success) async {
  if (success) {
    await Navigator.pushReplacement(
        context, MaterialPageRoute(builder: (_) => NotesPage()));
  } else {
    ScaffoldMessenger.of(context)
        .showSnackBar(SnackBar(content: Text('Something went wrong.')));
  }
}

Now let's build the NotesPage. For now, it'll just be an empty page, with a button to sign out. Here's the full code:

class NotesPage extends StatelessWidget {
  const NotesPage();

  Future<void> _signOut(BuildContext context) async {
    final success = await Services.of(context).authService.signOut();
    if (success) {
      Navigator.pushReplacement(
          context, MaterialPageRoute(builder: (_) => HomePage()));
    } else {
      ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('There was an issue logging out.')));
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Supanotes'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Padding(
              padding: const EdgeInsets.all(8.0),
              child: Text('Your notes will show up here.'),
            ),
            ElevatedButton.icon(
              onPressed: () async {
                await _signOut(context);
              },
              icon: Icon(Icons.login),
              label: Text('Sign out'),
            ),
          ],
        ),
      ),
    );
  }
}

And that's it! We now have a proper authentication system set up for our Supanotes app. Now any requests to the Supabase client will include the signed in user info as well, so we can continue with the next part: creating and listing notes.

GoTrue and JSON Web Tokens

GoTrue uses JSON Web Tokens (JWT) for authentication. On a successful sign in/sign up, the response contains an access token, and a refresh token. The access token is included in every request to Supabase. When decoded, this token contains the user's unique ID, and this is how Supabase knows which user is performing the request. Access tokens are short-lived, and expire by default every one hour (you can configure this through the admin interface, but only do this if you have a good reason). You can read more about JWT here.

The access token is only valid for a short time, and we definitely don't want the user having to sign in every one hour. This is what the refresh token is for. The refresh token is valid for longer than an hour, and can be used to request new tokens. Let's take a look at some of the source code of the GoTrueClient:

void _saveSession(Session session) {
  currentSession = session;
  currentUser = session.user;
  final tokenExpirySeconds = session.expiresIn;

  if (autoRefreshToken && tokenExpirySeconds != null) {
    if (_refreshTokenTimer != null) _refreshTokenTimer!.cancel();

    final timerDuration = Duration(seconds: tokenExpirySeconds - 60);
    _refreshTokenTimer = Timer(timerDuration, () {
      _callRefreshToken();
    });
  }
}

If autoRefreshToken is set to true, a timer is set to automatically "refresh" the tokens by using the refresh token, one minute before the access token expires. autoRefreshToken is true by default, and can be changed through an optional parameter in the GoTrueClient constructor.

Now, what happens if the user exits the app? We lose access to both tokens, and have no way of requesting new tokens either, so the user would have to sign in again.

Keeping users signed in

To keep users signed in even after re-opening the app, we need to somehow request new tokens. GoTrueClient has a recoverSession function, which uses the refresh token mentioned before to request new tokens.

In order to recover the session, we need to persist the session data of a successful sign in. In this example, we'll use the shared_preferences package, but you might also want to use something like flutter_secure_storage if there are security concerns. Data stored in shared preferences is only accessible by the app which stored them, but this is not the case for rooted devices.

flutter pub add shared_preferences

Conveniently, the Session object in the GoTrueResponse contains a function to get the JSON string to persist. So all we have to do is store this string in SharedPreferences, and fetch it when we want to recover the session. Here's the updated signUp and signIn functions:

// AuthService
static const supabaseSessionKey = 'supabase_session';

Future<bool> signUp(String email, String password) async {
  final response = await _client.signUp(email, password);
  if (response.error == null) {
    log('Sign up was successful for user ID: ${response.user!.id}');
    _persistSession(response.data!);
    return true;
  }
  log('Sign up error: ${response.error!.message}');
  return false;
}

Future<bool> signIn(String email, String password) async {
  final response = await _client.signIn(email: email, password: password);
  if (response.error == null) {
    log('Sign in was successful for user ID: ${response.user!.id}');
    _persistSession(response.data!);
    return true;
  }
  log('Sign in error: ${response.error!.message}');
  return false;
}

Future<void> _persistSession(Session session) async {
  final prefs = await SharedPreferences.getInstance();
  log('Persisting session string');
  await prefs.setString(supabaseSessionKey, session.persistSessionString);
}

Note that it might make sense to initialize SharedPreferences once and pass it to any services that might need it, but let's keep it like this for simplicity.

Okay, so we have all we need to recover the session after the user exists the app. What now? In order to decide which page widget to show (HomePage if user is not signed in, NotesPage otherwise), we can check if there is a persisted session string, and attempt to recover the session with GoTrueClient#recoverSession. If there's no session string stored, or if recovering the session fails, then we can show the HomePage. If recovering the session works, then the user is successfully signed in! We can go straight to the NotesPage.

Let's introduce a new function in AuthService, that will attempt to recover the session.

// AuthService
Future<bool> recoverSession() async {
  final prefs = await SharedPreferences.getInstance();
  if (prefs.containsKey(supabaseSessionKey)) {
    log('Found persisted session string, attempting to recover session');
    final jsonStr = prefs.getString(supabaseSessionKey)!;
    final response = await _client.recoverSession(jsonStr);
    if (response.error == null) {
      log('Session successfully recovered for user ID: ${response.user!.id}');
      _persistSession(response.data!);
      return true;
    }
  }
  return false;
}

Next, let's call this function to decide which page to show first. Here's the updated build function of the root SupanotesApp widget:

@override
Widget build(BuildContext context) {
  return Services(
    child: MaterialApp(
      title: 'Supanotes',
      theme: ThemeData(
        brightness: Brightness.dark,
        primarySwatch: toMaterialColor(supabaseGreen),
      ),
      home: Builder(
        builder: (context) {
          return FutureBuilder<bool>(
            future: Services.of(context).authService.recoverSession(),
            builder: (context, snapshot) {
              final sessionRecovered = snapshot.data ?? false;
              return sessionRecovered ? NotesPage() : HomePage();
            },
          );
        },
      ),
    ),
  );
}

Note that we are wrapping the FutureBuilder with a Builder, as the Services object will not be available in the context of SupanotesApp.

And that's it! If you now try to perform a hot restart, or exit and re-open the app, you'll see that you'll still be signed in! If the refresh token has expired, the recoverSession function will attempt to refresh the tokens, otherwise it will resume with the persisted session.

The GoTrueClient is not a big class, so I'd recommend taking a better look at the source code if you're interested in seeing how it all works behind the scenes.

There is one more thing we need to do. When a user signs out, we should clear this persisted session string. Otherwise, if a user signs out and then re-opens the app, they could be signed back in!

Here's the updated signOut function:

Future<bool> signOut() async {
  final response = await _client.signOut();
  if (response.error == null) {
    log('Successfully logged out; clearing session string');
    final prefs = await SharedPreferences.getInstance();
    prefs.remove(supabaseSessionKey);
    return true;
  }
  log('Log out error: ${response.error!.message}');
  return false;
}

More auth features

Supabase authentication also supports third party logins, but we won't show an example of how to use this functionality in this post. These OAuth providers are supported:

Google
GitHub
GitLab
Azure
Facebook
BitBucket
Apple
Twitter

There is also support for magic links! If you call the GoTrueClient#signIn function without a password, this will send the user an email with a one-time login link. Both third party logins and magic links could be good potential blog posts, so watch this space!

Wrapping up

That's all for the first part of this tutorial series on Supabase with Flutter, focusing on Authentication. You can find the full code on GitHub. I hope you found it helpful, and would love it if you could share some feedback in the comments! In the next part, we will take a look at Supabase's Database offering.

If you'd like to be notified when the next part of this series is published, and for any future tutorials, please sign up with your email here.

Forem: Christos

Full-stack Dart with Flutter, Supabase and Dart Edge

Introduction

Set up an edge function

Connect to Supabase from the edge

Call the function from Flutter

Wrapping up

Building a ChatGPT client app with Flutter

Introduction

The ChatGPT API

A note on API keys

The chat interface

Parsing markdown

Error handling

Wrapping up

How I built and published a Flutter app in 48 hours

Introduction

Planning

Features

Expense tracking

Statistics

Labels

Currencies

Design

Implementation

Data storage

State management

Architecture

Local notifications

Theming

Monitoring

Analytics

Crash reporting

On-boarding

In-app purchases

Necessary things

A few more things

Production

Publishing

Future plans

Wrapping up

How to create a custom plugin in Flutter with Pigeon

Introduction

Native platform communication

Platform channels

Pigeon

Creating a plugin

The plugin template

Using Pigeon

Installing the pigeon package

Defining the App Usage API

Caveats and limitations

Futures

No imports allowed

Supported data types

Enums aren't yet supported for primitive return types

Generics are supported, but can only be used with nullable types

Generating the code

Running the generator

Dart

Java

Swift

Objective-C

Understanding the generated code

Native platform implementation

Android

iOS

Using the plugin

Comparing Pigeon and method channels

Wrapping up

Dynamic theme color with Material 3 (You) in Flutter

Introduction

Using Material 3

Using dynamic color

The dynamic_color package

The DynamicColorBuilder widget

Using dynamic color schemes

Wrapping up

How to create a custom plugin in Flutter to call native platform code

Introduction

Installing the `pigeon` package

The `dynamic_color` package

The `DynamicColorBuilder` widget

The `Dismissible` widget

More on the `Dismissible` widget

Slide actions with `flutter_slidable`

Step #1: Using a `Stack`

Step #2: Extracting the `LoadingOverlay` widget

The `flex_color_scheme` package