{"id":22194077,"url":"https://github.com/elbatanony/soar_quest","last_synced_at":"2025-08-24T09:30:34.072Z","repository":{"id":62399030,"uuid":"495763131","full_name":"ElBatanony/soar_quest","owner":"ElBatanony","description":"A framework to build Telegram Mini Apps with Flutter.","archived":false,"fork":false,"pushed_at":"2024-02-02T23:07:33.000Z","size":1664,"stargazers_count":20,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"mini-apps-contest-3","last_synced_at":"2024-12-16T05:51:41.216Z","etag":null,"topics":["dart","flutter","miniapps","telegram"],"latest_commit_sha":null,"homepage":"https://miniapps.quest","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ElBatanony.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-24T09:52:18.000Z","updated_at":"2024-12-06T21:07:57.000Z","dependencies_parsed_at":"2023-10-04T06:20:55.573Z","dependency_job_id":"d2f45d96-1150-4516-9b63-db1b2ad3cdbc","html_url":"https://github.com/ElBatanony/soar_quest","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElBatanony%2Fsoar_quest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElBatanony%2Fsoar_quest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElBatanony%2Fsoar_quest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElBatanony%2Fsoar_quest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ElBatanony","download_url":"https://codeload.github.com/ElBatanony/soar_quest/tar.gz/refs/heads/mini-apps-contest-3","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230788228,"owners_count":18280300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","flutter","miniapps","telegram"],"created_at":"2024-12-02T13:11:01.009Z","updated_at":"2024-12-22T02:42:15.179Z","avatar_url":"https://github.com/ElBatanony.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Soar Quest\n\nA framework to build [Telegram Mini Apps](https://core.telegram.org/bots/webapps) faster with [Flutter](https://flutter.dev/).\n\n[![pub package](https://img.shields.io/pub/v/soar_quest.svg?\u0026logo=Flutter\u0026color=blue)](https://pub.dev/packages/soar_quest)\n[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](/LICENSE)\n\n![Soar Quest Logo](logo.png)\n\n## Introduction\n\nSoar Quest is designed to help you get straight to providing value to your users.\nTherefore, it abstracts many concerns that one would traditionally have when it comes to developing applications.\nNevertheless, the developer still has full access to the full power of Flutter.\n\nThe framework provides the following set of functionality and components:\n\n- Application builder. i.e., `SQApp`\n- Authentication system, with profile screen and sign in screen\n- Databases. Collections (Tables) and Docs (Items/Rows)\n- Screens to display collections and docs\n- Actions to perform on data\n- User settings\n- File storage system\n\nThe functionality is described briefly in the following sections.\n\n### Motivation\n\nThis project is driven by a belief that the current software engineering processes are too inefficient.\nA guiding principle is that new code should be added only to provide new value to the app's user.\nThis would entail less code to create apps, less effort, and faster development.\nMany design decisions here are inspired by No-code tools, due to the efficiency they provide for creators.\n\n## Installing\n\nAdd the following line to your dependencies in `pubspec.yaml`.\n\n```yaml\nsoar_quest: ^0.8.0\n```\n\nThe depndencies section will look something like:\n\n```yaml\ndependencies:\n  flutter:\n    sdk: flutter\n  soar_quest: ^0.8.0\n```\n\n### QR Code Scanning Setup\n\nSee instructions [here](https://pub.dev/packages/mobile_scanner/versions/3.0.0-beta.4#platform-specific-setup).\n\n## SQApp\n\nThe root of your application uses `SQApp`.\n\nThe following code can get you started with your first Soar Quest app.\n\n```dart\nimport 'package:flutter/material.dart';\nimport 'package:soar_quest/soar_quest.dart';\n\nvoid main() async {\n  await SQApp.init(\"My Cool App\");\n\n  SQApp.run([\n    Screen(\"Hello World\"),\n    Screen(\"Second Screen\"),\n  ]);\n}\n```\n\n### Designing Mini Apps\n\nSoar Quest automatically captures the user's custom [`ThemeParams`](https://core.telegram.org/bots/webapps#themeparams)\nand adjusts the [Material Design 3](https://m3.material.io/) Theme.\n\n### User Data (Fields)\n\nTo include custom user data fields, populate the `userDocFields` parameter when creating the `SQApp`.\n\n```dart\nawait SQApp.init(\"My Cool App\",\n      userDocFields: [SQStringField(\"Telegram Handle\")]);\n```\n\n### User Settings\n\nLocal data used to configure the application. Example: dark mode vs light mode.\nThe Settings screen appears automatically in the drawer (if you include a drawer).\n\n```dart\nawait UserSettings.setSettings([ SQBoolField(\"Enable feature X\") ]);\n\nSQApp.run([\n  CollectionScreen(collection: testCollection),\n], drawer: SQDrawer([]) );\n```\n\n## Data: Collections, Docs, and Fields\n\nCompared to Google Sheets. Collections are sheets. Docs are rows. Fields are column cells.\n\nCompared to SQL. Collections are Tables. Docs are rows (entries). Fields are data values.\n\nEach collection has a set of fields describing the data the docs of the collection would have.\n\n### SQCollection\n\nThere are several collections provided by SQ.\nThe difference if the location of storage.\nThe behave the same.\n\n- `LocalCollection`\n- `InMemoryCollection`\n\n#### CollectionSlice\n\n`CollectionSlice` method to filter docs from a collection.\nTreated by other components of SQ as an `SQCollection`.\n\n```dart\nCollectionSlice slice =\n      CollectionSlice(testCollection, filter: ValueFilter(\"Status\", \"Done\"));\n\nSQApp.run([CollectionScreen(collection: slice)]);\n```\n\n## DocCondition\n\n### SQDoc\n\nEach piece of information in your app is contained in a doc.\nDocs have fields that contain values.\n\n### Fields\n\nFields represent the data values (or types) that your docs could contain.\nSoar Quest provides numerous fields. Some of them include:\n\n- `SQStringField`. Text.\n- `SQBoolField`. True/False. Yes/No.\n- `SQIntField`. Integer numbers.\n- `SQDoubleField`. Floating point (fractional) numbers.\n- `SQRefField`. A value that points to another doc (in a collection).\n- `SQInverseRefsField`. An automatically generated list of docs referring/pointing to this doc.\n- `SQTimestampField`. Date (day/month/year).\n- `SQTimeOfDayField`. Time of day (hour/minutes).\n- `SQFileField`. Storing files.\n- `SQImageField`. Storing images.\n\n## Screens\n\nScreens include by default the `AppBar` and bottom `NavBar`.\n\nScreens could be extended and customized.\nThe following piece of code shows how to create a custom screen.\nAdd your custom implementation inside the `screenBody` method.\n\n```dart\nclass MyCustomScreen extends Screen {\n  const MyCustomScreen(String title, {Key? key}) : super(title, key: key);\n\n  @override\n  State\u003cMyCustomScreen\u003e createState() =\u003e _MyCustomScreenState();\n}\n\nclass _MyCustomScreenState extends ScreenState\u003cMyCustomScreen\u003e {\n  @override\n  Widget screenBody(BuildContext context) {\n    // TODO: implement screenBody\n    return super.screenBody(context);\n  }\n}\n```\n\n### Collection Screens\n\nPrebuild screens that displays the docs of a collection.\n\n- `CollectionScreen`. The default list of docs screen.\n- `GalleryScreen`. A grid (2 per row) screen.\n- `TableScreen`. Displays doc fields and values in table format.\n\n```dart\nSQApp.run(\n  [\n    CollectionScreen(collection: testCollection),\n    GalleryScreen(collection: testCollection),\n    TableScreen(collection: testCollection),\n  ],\n);\n```\n\nUse the following code to create a custom `CollectionScreen`.\n\n```dart\nclass MyCustomCollectionScreen extends CollectionScreen {\n  MyCustomCollectionScreen({super.title, required super.collection, super.key});\n\n  @override\n  State\u003cMyCustomCollectionScreen\u003e createState() =\u003e _MyCustomCollectionScreenState();\n}\n\nclass _MyCustomCollectionScreenState extends CollectionScreenState\u003cMyCustomCollectionScreen\u003e {\n  @override\n  Widget screenBody(BuildContext context) {\n    // TODO: implement screenBody for MyCustomCollectionScreen\n    return super.screenBody(context);\n  }\n}\n```\n\n### DocScreen\n\nA screen that displays the fields of a single document.\n\nUse the following code to create a custom `DocScreen`.\n\n```dart\nclass MyCustomDocScreen extends DocScreen {\n  MyCustomDocScreen(super.doc,{super.key});\n\n  @override\n  State\u003cMyCustomDocScreen\u003e createState() =\u003e _MyCustomDocScreenState();\n}\n\nclass _MyCustomDocScreenState extends DocScreenState\u003cMyCustomDocScreen\u003e {\n  @override\n  Widget screenBody(BuildContext context) {\n    // TODO: implement screenBody for MyCustomDocScreen\n    return super.screenBody(context);\n  }\n}\n```\n\n### FormScreen\n\nThe `FormScreen` is the screen where you edit the data (fields) of an `SQDoc`.\nYou would not need to interact with the `FormScreen` directly, unless you want to customize the form.\n\n## SQAction\n\nActions on (or from) data (docs).\nActions are assigned when creating a `SQCollection`.\n\nThe following examples are the most common examples of actions provided by default:\n\n- `SetFieldsAction`\n- `GoScreenAction`\n- `CreateDocAction`\n- `OpenUrlAction`\n- `CustomAction`\n\nThe following are a few examples of how to set actions for a collection.\n\n```dart\nlate SQCollection simpleCollection;\nsimpleCollection = LocalCollection(id: \"Simple Collection\", fields: [\n  SQStringField(\"Name\"),\n  SQBoolField(\"Magic\"),\n  SQStringField(\"Status\", value: \"To-Do\"),\n  SQIntField(\"Points\"),\n], actions: [\n  SetFieldsAction(\"Mark as Done\",\n      getFields: (doc) =\u003e {\n            \"Status\": \"Done\",\n            \"Points\": (doc.value\u003cint\u003e(\"Points\") ?? 0) + 1,\n          }),\n  CreateDocAction(\"Create Magic Doc\",\n      getCollection: () =\u003e simpleCollection,\n      initialFields: (doc) =\u003e [\n            SQStringField(\"Name\", value: \"Magic Doc\"),\n            SQBoolField(\"Magic\", value: true),\n            SQIntField(\"Points\", value: 99),\n          ]),\n  CustomAction(\"Do Maths\", customExecute: (doc, context) async {\n    int x = doc.value\u003cint\u003e(\"Points\") ?? 0;\n    int y = x + 5;\n    print(\"Magic number: $y\");\n  }),\n  CustomAction(\"print hi\",\n      customExecute: (doc, context) async =\u003e print(\"hi\")),\n]);\n```\n\n## Contribution\n\nThe best way to contribute is to [suggest additions](https://github.com/ElBatanony/soar_quest/issues/new) to the package and using it in your projects.\nConsider leaving a star on GitHub 😉.\n\n## Acknowledgements\n\nThe logo was generated using the [Stable Diffusion](https://huggingface.co/spaces/stabilityai/stable-diffusion) AI image generation tool.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felbatanony%2Fsoar_quest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felbatanony%2Fsoar_quest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felbatanony%2Fsoar_quest/lists"}