How to Create Home Screen Widgets in Flutter with HomeWidget and Back4App

31min
Introduction
Home screen widgets allow users to access real-time information from your app directly on their device's home screen without opening the app. With Flutter, creating these widgets requires some platform-specific code. However, the home_widget package bridges this gap by enabling data exchange between your Flutter app and the home screen widgets using Dart code.
In this tutorial, you will learn how to create a home screen widget in Flutter using the home_widget package and integrate it with Back4App—a backend-as-a-service powered by Parse Server. By the end of this tutorial, you will have a Flutter app that displays data from Back4App in a home screen widget.
Prerequisites
To complete this tutorial, you will need:
Flutter SDK installed on your machine. You can follow the official Flutter installation guide for your operating system.
Basic knowledge of Flutter and Dart. If you're new to Flutter, consider reviewing the Flutter documentation to familiarize yourself with the basics.
An IDE or text editor such as Visual Studio Code or Android Studio.
A Back4App account. Sign up for a free account at Back4App.
Parse Server SDK for Flutter added to your project. You can learn how to set it up by following the Back4App Flutter SDK Guide.
Platform-specific setup for Android and iOS home screen widgets.
Step 1 – Setting Up the Flutter Project
1.1. Create a New Flutter Project
Open your terminal and run:
Bash
flutter create home_widget_app
flutter create home_widget_app
﻿
Navigate to the project directory:
Bash
cd home_widget_app
cd home_widget_app
﻿
1.2. Add Dependencies
Open pubspec.yaml and add the following dependencies:
YAML
dependencies:
  flutter:
    sdk: flutter
  home_widget: ^0.2.4
  parse_server_sdk_flutter: ^4.0.1
dependencies:
  flutter:
    sdk: flutter
  home_widget: ^0.2.4
  parse_server_sdk_flutter: ^4.0.1
﻿
Run flutter pub get to install the packages.
Step 2 – Setting Up Back4App
2.1. Create a New Back4App Application
Log in to your Back4App dashboard.
Click on "Create new App".
Enter a name for your application, e.g., "HomeWidgetApp", and click "Create".
2.2. Set Up the Data Model
In your application dashboard, navigate to the "Database" section.
Click on "Create a class".
In the modal:
Select "Custom".
Enter "Message" as the class name.
Click "Create class".
2.3. Add Columns to the Class
In the "Message" class, click on "+" to add a new column.
Add the following columns:
title: Type String
content: Type String
Add some sample data to the "Message" class. For example:
2.4. Obtain Application Credentials
Navigate to App Settings > Security & Keys.
Note down your Application ID and Client Key.
Step 3 – Initializing Parse in Your Flutter App
Open lib/main.dart and modify it as follows:
Dart
import 'package:flutter/material.dart';
import 'package:parse_server_sdk_flutter/parse_server_sdk.dart';
import 'package:home_widget/home_widget.dart';
import 'dart:async';
import 'home_page.dart'; // You'll create this file next

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  const keyApplicationId = 'YOUR_APPLICATION_ID';
  const keyClientKey = 'YOUR_CLIENT_KEY';
  const keyParseServerUrl = 'https://parseapi.back4app.com';

  await Parse().initialize(
    keyApplicationId,
    keyParseServerUrl,
    clientKey: keyClientKey,
    debug: true,
  );

  runApp(MyApp());
}
import 'package:flutter/material.dart';
import 'package:parse_server_sdk_flutter/parse_server_sdk.dart';
import 'package:home_widget/home_widget.dart';
import 'dart:async';
import 'home_page.dart'; // You'll create this file next

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  const keyApplicationId = 'YOUR_APPLICATION_ID';
  const keyClientKey = 'YOUR_CLIENT_KEY';
  const keyParseServerUrl = 'https://parseapi.back4app.com';

  await Parse().initialize(
    keyApplicationId,
    keyParseServerUrl,
    clientKey: keyClientKey,
    debug: true,
  );

  runApp(MyApp());
}
﻿
Replace 'YOUR_APPLICATION_ID' and 'YOUR_CLIENT_KEY' with your actual Back4App credentials.
Step 4 – Fetching Data from Back4App
Create a new file lib/home_page.dart:
Dart
import 'package:flutter/material.dart';
import 'package:parse_server_sdk_flutter/parse_server_sdk.dart';
import 'package:home_widget/home_widget.dart';
import 'dart:async';

class HomePage extends StatefulWidget {
  @override
  _HomePageState createState() => _HomePageState();
}

class Message {
  final String title;
  final String content;

  Message(this.title, this.content);
}

class _HomePageState extends State<HomePage> {
  Message? message;

  @override
  void initState() {
    super.initState();
    fetchMessage();
  }

  Future<void> fetchMessage() async {
    final QueryBuilder<ParseObject> query =
        QueryBuilder<ParseObject>(ParseObject('Message'));

    final ParseResponse apiResponse = await query.query();

    if (apiResponse.success && apiResponse.results != null) {
      final data = apiResponse.results!.first;
      final title = data.get<String>('title') ?? '';
      final content = data.get<String>('content') ?? '';
      setState(() {
        message = Message(title, content);
      });
      updateHomeWidget(title, content);
    } else {
      print('Error fetching data: ${apiResponse.error?.message}');
    }
  }

  Future<void> updateHomeWidget(String title, String content) async {
    await HomeWidget.saveWidgetData<String>('title', title);
    await HomeWidget.saveWidgetData<String>('content', content);
    await HomeWidget.updateWidget(
        name: 'HomeWidgetProvider', // Name of your HomeWidgetProvider
        iOSName: 'HomeWidget');     // Used in iOS
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Home Widget App'),
      ),
      body: Center(
        child: message == null
            ? CircularProgressIndicator()
            : Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  Text(
                    message!.title,
                    style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
                  ),
                  SizedBox(height: 10),
                  Text(
                    message!.content,
                    style: TextStyle(fontSize: 18),
                  ),
                  SizedBox(height: 20),
                  ElevatedButton(
                    onPressed: fetchMessage,
                    child: Text('Refresh Message'),
                  ),
                ],
              ),
      ),
    );
  }
}
import 'package:flutter/material.dart';
import 'package:parse_server_sdk_flutter/parse_server_sdk.dart';
import 'package:home_widget/home_widget.dart';
import 'dart:async';

class HomePage extends StatefulWidget {
  @override
  _HomePageState createState() => _HomePageState();
}

class Message {
  final String title;
  final String content;

  Message(this.title, this.content);
}

class _HomePageState extends State<HomePage> {
  Message? message;

  @override
  void initState() {
    super.initState();
    fetchMessage();
  }

  Future<void> fetchMessage() async {
    final QueryBuilder<ParseObject> query =
        QueryBuilder<ParseObject>(ParseObject('Message'));

    final ParseResponse apiResponse = await query.query();

    if (apiResponse.success && apiResponse.results != null) {
      final data = apiResponse.results!.first;
      final title = data.get<String>('title') ?? '';
      final content = data.get<String>('content') ?? '';
      setState(() {
        message = Message(title, content);
      });
      updateHomeWidget(title, content);
    } else {
      print('Error fetching data: ${apiResponse.error?.message}');
    }
  }

  Future<void> updateHomeWidget(String title, String content) async {
    await HomeWidget.saveWidgetData<String>('title', title);
    await HomeWidget.saveWidgetData<String>('content', content);
    await HomeWidget.updateWidget(
        name: 'HomeWidgetProvider', // Name of your HomeWidgetProvider
        iOSName: 'HomeWidget');     // Used in iOS
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Home Widget App'),
      ),
      body: Center(
        child: message == null
            ? CircularProgressIndicator()
            : Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  Text(
                    message!.title,
                    style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
                  ),
                  SizedBox(height: 10),
                  Text(
                    message!.content,
                    style: TextStyle(fontSize: 18),
                  ),
                  SizedBox(height: 20),
                  ElevatedButton(
                    onPressed: fetchMessage,
                    child: Text('Refresh Message'),
                  ),
                ],
              ),
      ),
    );
  }
}
﻿
Explanation
Message Class: A simple model class to hold the message data.
fetchMessage(): Fetches data from the Message class in Back4App and updates the message variable.
updateHomeWidget(): Saves the fetched data to the home screen widget using HomeWidget.saveWidgetData and triggers an update using HomeWidget.updateWidget.
build(): Displays the message data and a button to refresh the message.
Step 5 – Setting Up the Home Screen Widget
5.1. Android Setup
5.1.1. Create the Widget Layout
Create a new XML layout file in android/app/src/main/res/layout/ named home_widget.xml:
XML
<!-- android/app/src/main/res/layout/home_widget.xml -->
<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    
    <TextView
        android:id="@+id/widget_title"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Title"
        android:textSize="18sp"
        android:layout_gravity="center_horizontal|top"
        android:paddingTop="16dp"/>

    <TextView
        android:id="@+id/widget_content"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Content"
        android:textSize="14sp"
        android:layout_gravity="center"
        android:paddingTop="8dp"/>

</FrameLayout>
<!-- android/app/src/main/res/layout/home_widget.xml -->
<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    
    <TextView
        android:id="@+id/widget_title"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Title"
        android:textSize="18sp"
        android:layout_gravity="center_horizontal|top"
        android:paddingTop="16dp"/>

    <TextView
        android:id="@+id/widget_content"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Content"
        android:textSize="14sp"
        android:layout_gravity="center"
        android:paddingTop="8dp"/>

</FrameLayout>
﻿
5.1.2. Create the Widget Provider
Create a new Java class in android/app/src/main/java/your/package/name/ named HomeWidgetProvider.java:
Java
// android/app/src/main/java/your/package/name/HomeWidgetProvider.java
package your.package.name;

import android.appwidget.AppWidgetManager;
import android.appwidget.AppWidgetProvider;
import android.content.Context;

public class HomeWidgetProvider extends AppWidgetProvider {
    @Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // The HomeWidget package handles the update
    }
}
// android/app/src/main/java/your/package/name/HomeWidgetProvider.java
package your.package.name;

import android.appwidget.AppWidgetManager;
import android.appwidget.AppWidgetProvider;
import android.content.Context;

public class HomeWidgetProvider extends AppWidgetProvider {
    @Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // The HomeWidget package handles the update
    }
}
﻿
Replace your.package.name with your actual package name.
5.1.3. Update Android Manifest
Add the widget provider to your AndroidManifest.xml:
XML
<!-- Add inside the <application> tag -->
<receiver android:name=".HomeWidgetProvider">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE"/>
    </intent-filter>

    <meta-data android:name="android.appwidget.provider"
        android:resource="@xml/home_widget_info"/>
</receiver>
<!-- Add inside the <application> tag -->
<receiver android:name=".HomeWidgetProvider">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE"/>
    </intent-filter>

    <meta-data android:name="android.appwidget.provider"
        android:resource="@xml/home_widget_info"/>
</receiver>
﻿
5.1.4. Create Widget Info XML
Create a new XML file in android/app/src/main/res/xml/ named home_widget_info.xml:
XML
<!-- android/app/src/main/res/xml/home_widget_info.xml -->
<?xml version="1.0" encoding="utf-8"?>
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/home_widget"
    android:minWidth="180dp"
    android:minHeight="110dp"
    android:updatePeriodMillis="0"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen">
</appwidget-provider>
<!-- android/app/src/main/res/xml/home_widget_info.xml -->
<?xml version="1.0" encoding="utf-8"?>
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/home_widget"
    android:minWidth="180dp"
    android:minHeight="110dp"
    android:updatePeriodMillis="0"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen">
</appwidget-provider>
﻿
5.2. iOS Setup
5.2.1. Create a Widget Extension
Open your Flutter project in Xcode by opening ios/Runner.xcworkspace.
Click File > New > Target.
Choose Widget Extension and click Next.
Enter HomeWidget as the product name and ensure Include Configuration Intent is unchecked.
Click Finish and Activate the scheme.
5.2.2. Update the Widget Code
In the HomeWidget extension, open HomeWidget.swift and modify it:
Swift
import WidgetKit
import SwiftUI

struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> SimpleEntry {
        SimpleEntry(date: Date(), title: "Title", content: "Content")
    }

    func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> ()) {
        let entry = SimpleEntry(date: Date(), title: "Title", content: "Content")
        completion(entry)
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<Entry>) -> ()) {
        var entries: [SimpleEntry] = []

        let sharedDefaults = UserDefaults(suiteName: "YOUR_GROUP_ID")
        let title = sharedDefaults?.string(forKey: "title") ?? "Title"
        let content = sharedDefaults?.string(forKey: "content") ?? "Content"

        let entryDate = Date()
        let entry = SimpleEntry(date: entryDate, title: title, content: content)
        entries.append(entry)

        let timeline = Timeline(entries: entries, policy: .never)
        completion(timeline)
    }
}

struct SimpleEntry: TimelineEntry {
    let date: Date
    let title: String
    let content: String
}

struct HomeWidgetEntryView : View {
    var entry: Provider.Entry

    var body: some View {
        VStack {
            Text(entry.title)
                .font(.headline)
            Text(entry.content)
                .font(.body)
        }
    }
}

@main
struct HomeWidget: Widget {
    let kind: String = "HomeWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: Provider()) { entry in
            HomeWidgetEntryView(entry: entry)
        }
        .configurationDisplayName("Home Widget")
        .description("This is a home screen widget.")
    }
}
import WidgetKit
import SwiftUI

struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> SimpleEntry {
        SimpleEntry(date: Date(), title: "Title", content: "Content")
    }

    func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> ()) {
        let entry = SimpleEntry(date: Date(), title: "Title", content: "Content")
        completion(entry)
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<Entry>) -> ()) {
        var entries: [SimpleEntry] = []

        let sharedDefaults = UserDefaults(suiteName: "YOUR_GROUP_ID")
        let title = sharedDefaults?.string(forKey: "title") ?? "Title"
        let content = sharedDefaults?.string(forKey: "content") ?? "Content"

        let entryDate = Date()
        let entry = SimpleEntry(date: entryDate, title: title, content: content)
        entries.append(entry)

        let timeline = Timeline(entries: entries, policy: .never)
        completion(timeline)
    }
}

struct SimpleEntry: TimelineEntry {
    let date: Date
    let title: String
    let content: String
}

struct HomeWidgetEntryView : View {
    var entry: Provider.Entry

    var body: some View {
        VStack {
            Text(entry.title)
                .font(.headline)
            Text(entry.content)
                .font(.body)
        }
    }
}

@main
struct HomeWidget: Widget {
    let kind: String = "HomeWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: Provider()) { entry in
            HomeWidgetEntryView(entry: entry)
        }
        .configurationDisplayName("Home Widget")
        .description("This is a home screen widget.")
    }
}
﻿
Replace YOUR_GROUP_ID with your App Group identifier (e.g., group.com.example.homeWidgetApp).
5.2.3. Set Up App Groups
In Xcode, select your project and go to Signing & Capabilities.
Add "App Groups" to both your main app target and the widget extension.
Create a new App Group (e.g., group.com.example.homeWidgetApp).
Ensure both targets have the same App Group enabled.
5.3. Update Flutter Code for Platform-Specific Configurations
In your updateHomeWidget() method in home_page.dart, update the widget names:
Dart
await HomeWidget.updateWidget(
    name: 'HomeWidgetProvider', // For Android, the class name of your AppWidgetProvider
    iOSName: 'HomeWidget',      // For iOS, the name of your Widget Extension
);
await HomeWidget.updateWidget(
    name: 'HomeWidgetProvider', // For Android, the class name of your AppWidgetProvider
    iOSName: 'HomeWidget',      // For iOS, the name of your Widget Extension
);
﻿
Step 6 – Running the App and Testing the Widget
6.1. Run the App
In your terminal, run:
Bash
flutter run
flutter run
﻿
6.2. Add the Widget to Your Home Screen
Android
Long-press on the home screen and select "Widgets".
Find your app in the widget list.
Drag and drop the widget onto your home screen.
iOS
Enter jiggle mode by long-pressing on the home screen.
Tap the "+" button in the top-left corner.
Search for your widget by name.
Add the widget to your home screen.
6.3. Test Data Updates
Tap the "Refresh Message" button in your app to fetch new data from Back4App.
The widget on your home screen should update with the new data.
Conclusion
In this tutorial, you learned how to create a home screen widget in Flutter using the home_widget package and integrated it with Back4App to display dynamic data. This allows you to provide users with up-to-date information right on their home screens, enhancing engagement and user experience.
Next Steps
Dynamic Data: Implement real-time data updates using Back4App's Live Queries.
Interactivity: Add click actions to your widget to open specific pages in your app.
Customization: Style your widget to match your app's theme and design.
Additional Resources
﻿Back4App Documentation﻿
﻿home_widget Package on pub.dev﻿
﻿Parse SDK for Flutter Guide﻿
﻿Flutter Official Documentation﻿
Happy Coding!
Updated 14 Sep 2024
Did this page help you?
Complete Guide to Third-Party Authentication in Flutter with Parse on Back4App
How to Implement Keyboard Shortcuts in Flutter with CallbackShortcuts and Back4App