Soar Quest

A framework to build applications faster. Built on Flutter and Firebase.

Introduction

Soar Quest is designed to help you get straight to providing value to your users. Therefore, it abstracts many concerns that one would traditionally have when it comes to developing applications. Nevertheless, the developer still has full access to the full power of Flutter.

The framework provides the following set of functionality and components:

• Application builder. i.e., SQApp
• Authentication system, with profile screen and sign in screen
• Databases. Collections (Tables) and Docs (Items/Rows)
• Screens to display collections and docs
• Actions to perform on data
• User settings
• File storage system

The functionality is described briefly in the following sections.

Motivation

This project is driven by a belief that the current software engineering processes are too inefficient. A guiding principle is that new code should be added only to provide new value to the app's user. This would entail less code to create apps, less effort, and faster development. Many design decisions here are inspired by No-code tools, due to the efficiency they provide for creators.

Installing

Add the following line to your dependencies in pubspec.yaml.

soar_quest: ^0.6.0

The depndencies section will look something like:

dependencies:
  flutter:
    sdk: flutter
  soar_quest: ^0.6.0
  firebase_core:

Android Setup

To compile your app in Android, update your minSdkVersion (see snippet below), and enable multiDex. Additionally, set your compileSdkVersion to 33 (or higher). You can find the settings in android\app\build.gradle.

android {
  compileSdkVersion 33
  defaultConfig {
    minSdkVersion 21
    multiDexEnabled true
  }
}                                                              

QR Code Scanning Setup

See instructions here.

SQApp

The root of your application uses SQApp.

The framework uses many Firebase components under the hood. Therefore, SQApp has a parameter for the Firebase configuration of your project. You can find out how to configure Firebase for your project using the flutterfire configure command from here.

The following code can get you started with your first Soar Quest app.

import 'package:flutter/material.dart';
import 'package:soar_quest/soar_quest.dart';

import 'firebase_options.dart';

void main() async {
  await SQApp.init("My Cool App",
      firebaseOptions: DefaultFirebaseOptions.currentPlatform);

  SQApp.run([
    Screen("Hello World"),
    Screen("Second Screen"),
  ]);
}

SQAuth

The authentication system requires the minimal configuration on your side.

Note: the authentication system only support Firebase Auth. Therefore, Firebase should be configured.

If you add an empty drawer (side menu) to the app, a profile screen will automatically appear there.

SQApp.run([
    Screen("Hello World"),
    Screen("Second Screen"),
], drawer: SQDrawer([]));

Alternatively, if you would like to include the profile screen in the bottom navigation bar, use the SQProfileScreen screen.

SQApp.run([
    Screen("Hello World"),
    SQProfileScreen(),
]);

The profile screen handles all the authentication workflows. If the user is not logged in, they will be prompted to sign in.

Other included features:

• Email verification
• Changing password (forgot passowrd)
• Editing username
• Profile fields (user data)

User Data (Fields)

To include custom user data fields, populate the userDocFields parameter when creating the SQApp.

await SQApp.init("My Cool App",
      userDocFields: [SQStringField("Telegram Handle")],
      firebaseOptions: DefaultFirebaseOptions.currentPlatform);

User Settings

Local data used to configure the application. Example: dark mode vs light mode. The Settings screen appears automatically in the drawer (if you include a drawer).

await UserSettings.setSettings([ SQBoolField("Enable feature X") ]);

SQApp.run([
  CollectionScreen(collection: testCollection),
], drawer: SQDrawer([]) );

Data: Collections, Docs, and Fields

Compared to Google Sheets. Collections are sheets. Docs are rows. Fields are column cells.

Compared to SQL. Collections are Tables. Docs are rows (entries). Fields are data values.

Each collection has a set of fields describing the data the docs of the collection would have.

SQCollection

There are several collections provided by SQ. The difference if the location of storage. The behave the same.

• FirestoreCollection
• LocalCollection
• InMemoryCollection

CollectionSlice

CollectionSlice method to filter docs from a collection. Treated by other components of SQ as an SQCollection.

CollectionSlice slice =
      CollectionSlice(testCollection, filter: ValueFilter("Status", "Done"));

SQApp.run([CollectionScreen(collection: slice)]);

DocCondition

SQDoc

Each piece of information in your app is contained in a doc. Docs have fields that contain values.

Fields

Fields represent the data values (or types) that your docs could contain. Soar Quest provides numerous fields. Some of them include:

• SQStringField. Text.
• SQBoolField. True/False. Yes/No.
• SQIntField. Integer numbers.
• SQDoubleField. Floating point (fractional) numbers.
• SQRefField. A value that points to another doc (in a collection).
• SQInverseRefsField. An automatically generated list of docs referring/pointing to this doc.
• SQTimestampField. Date (day/month/year).
• SQTimeOfDayField. Time of day (hour/minutes).
• SQFileField. Storing files.
• SQImageField. Storing images.

Screens

Screens include by default the AppBar and bottom NavBar.

Screens could be extended and customized. The following piece of code shows how to create a custom screen. Add your custom implementation inside the screenBody method.

class MyCustomScreen extends Screen {
  const MyCustomScreen(String title, {Key? key}) : super(title, key: key);

  @override
  State<MyCustomScreen> createState() => _MyCustomScreenState();
}

class _MyCustomScreenState extends ScreenState<MyCustomScreen> {
  @override
  Widget screenBody(BuildContext context) {
    // TODO: implement screenBody
    return super.screenBody(context);
  }
}

Collection Screens

Prebuild screens that displays the docs of a collection.

• CollectionScreen. The default list of docs screen.
• GalleryScreen. A grid (2 per row) screen.
• TableScreen. Displays doc fields and values in table format.

SQApp.run(
  [
    CollectionScreen(collection: testCollection),
    GalleryScreen(collection: testCollection),
    TableScreen(collection: testCollection),
  ],
);

Use the following code to create a custom CollectionScreen.

class MyCustomCollectionScreen extends CollectionScreen {
  MyCustomCollectionScreen({super.title, required super.collection, super.key});

  @override
  State<MyCustomCollectionScreen> createState() => _MyCustomCollectionScreenState();
}

class _MyCustomCollectionScreenState extends CollectionScreenState<MyCustomCollectionScreen> {
  @override
  Widget screenBody(BuildContext context) {
    // TODO: implement screenBody for MyCustomCollectionScreen
    return super.screenBody(context);
  }
}

DocScreen

A screen that displays the fields of a single document.

Use the following code to create a custom DocScreen.

class MyCustomDocScreen extends DocScreen {
  MyCustomDocScreen(super.doc,{super.key});

  @override
  State<MyCustomDocScreen> createState() => _MyCustomDocScreenState();
}

class _MyCustomDocScreenState extends DocScreenState<MyCustomDocScreen> {
  @override
  Widget screenBody(BuildContext context) {
    // TODO: implement screenBody for MyCustomDocScreen
    return super.screenBody(context);
  }
}

FormScreen

The FormScreen is the screen where you edit the data (fields) of an SQDoc. You would not need to interact with the FormScreen directly, unless you want to customize the form.

SQAction

Actions on (or from) data (docs). Actions are assigned when creating a SQCollection.

The following examples are the most common examples of actions provided by default:

• SetFieldsAction
• GoScreenAction
• CreateDocAction
• OpenUrlAction
• CustomAction

The following are a few examples of how to set actions for a collection.

late SQCollection simpleCollection;
simpleCollection = FirestoreCollection(id: "Simple Collection", fields: [
  SQStringField("Name"),
  SQBoolField("Magic"),
  SQStringField("Status", value: "To-Do"),
  SQIntField("Points"),
], actions: [
  SetFieldsAction("Mark as Done",
      getFields: (doc) => {
            "Status": "Done",
            "Points": (doc.value<int>("Points") ?? 0) + 1,
          }),
  CreateDocAction("Create Magic Doc",
      getCollection: () => simpleCollection,
      initialFields: (doc) => [
            SQStringField("Name", value: "Magic Doc"),
            SQBoolField("Magic", value: true),
            SQIntField("Points", value: 99),
          ]),
  CustomAction("Do Maths", customExecute: (doc, context) async {
    int x = doc.value<int>("Points") ?? 0;
    int y = x + 5;
    print("Magic number: $y");
  }),
  CustomAction("print hi",
      customExecute: (doc, context) async => print("hi")),
]);

File Storage

File storage is handled by Firebase Cloud Stroage. You need to have Firebase set up to be able to upload files and images.

To use the storage capabilities, add the following fields to your collection's fields:

• SQFileField. For storing files.
• SQImageField. Fot Storing images.

Contribution

The best way to contribute is to suggest additions to the package and using it in your projects. Consider leaving a star on GitHub 😉.

Acknowledgements

The logo was generated using the Stable Diffusion AI image generation tool.