Dartvel data models: storage, forms, tables, admin and pages

// lib/models/article.dart
import 'package:dartvel_core/dartvel.dart';

@DVModel(
  semantic: true,
  history: DVHistory(keep: Duration(days: 365)),
  softDelete: true,
  subject: DVSubject.field('authorId'),
  retain: DVRetention.indefinite,
)
class const _Article({
  required final String slug,
  @DVModel.pageTitle() required final String title,
  @DVModel.mainContent() required final String body,
  @DVModel.searchableField() required final String tags,
  required final bool published,
  required final String authorId,
  @DVModel.sensitiveField() required final String editorNotes,
});

Where records are stored is the framework's job. You read and write them through the model, on whichever database DATABASE_URL names.

Dartvel exports Get, Post, Put, Patch and Delete. A model with one of those names clashes with them in your code, so call it Article or BlogPost.

What it does: Who may view, create, update and delete through the data API, where no @DVPolicy class says

final Article article = Article(
  slug: 'hello-world',
  title: 'Hello, world',
  body: 'The first article.',
  tags: 'news',
  published: false,
  authorId: 'user-1',
  editorNotes: 'Check the title',
);
await article.save();

final List<Article> all = await Article.all();
final Article? found = await Article.find('hello-world');

final Article published = await found!.copyWith(published: true).save();
await published.destroy();

Widget articleEditor(Article article) => article.Form();

Widget articleTable(List<Article> articles) => Article.Table(articles);

Widget articlePage(Article article) => Article.Page.sync(article);

Article.Form() creates one and article.Form() edits that one. Saving is what the form does, and it checks the model's rules first. See Forms.

@DVPage(title: 'Articles admin', policy: DVPolicies.viewAdmin)
Widget _articlesAdminPage(BuildContext context) => Article.Admin();

Dartvel generates a public page for every record by default. To turn it off for a data model, set generatePublicPages: false on it.

The route comes from the model's name, in plural kebab-case, followed by the record's slug, or its id when the model has no slug: an Article is served at /articles/hello-world, and a BlogPost at /blog-posts/42.

Sensitive fields, and the field that names the record's subject, stay hidden. Only a viewer your viewSensitive policy allows sees them on the page.

Users, sessions, tokens, audit logs and tenant data get no page unless you set generatePublicPages: true.

// lib/policies/article_policy.dart
import '../dartvel_client/dartvel_client.dart';

@DVPolicy(Article)
class ArticlePolicy {
  // Who may open an article's page. Anyone else gets a 404.
  bool view(DVSessionPrincipal? user, Article article) =>
      article.published || user?.userId == article.authorId;

  // Who also sees editorNotes and authorId on the page.
  bool viewSensitive(DVSessionPrincipal? user, Article article) =>
      user?.userId == article.authorId;
}

@DVPage(title: 'Article')
Widget _articlePage(BuildContext context) => Article.Page.fromId(
      context.dvParams['slug'] ?? 'hello-world',
      findById: (String slug) async => (await Article.find(slug))!,
    );

@DVModel(publicPathsResolver: productPaths)
class const _Product({
  required final String slug,
  required final String name,
  required final bool published,
});

// Public, top level, and in the model's own file.
Future<List<String>> productPaths() async => <String>['starter-kit', 'pro-kit'];

try {
  await article.save();
} on DVConflictError catch (conflict) {
  // Someone saved a newer version after you read this one.
  debugPrint('Stored version ${conflict.actualVersion}');
}

// Replace the stored row on purpose.
await Article.save(article, onConflict: DVConflict.lastWriteWins);

// Needs @DVModel(history: DVHistory(...)).
final List<DVHistoryEntry> entries = await article.history();
for (final DVHistoryEntry entry in entries) {
  debugPrint('version ${entry.version} at ${entry.at}');
}
await article.revert(to: entries.first);

// Needs @DVModel(softDelete: true).
await article.destroy(); // hidden from find() and all()

final Article? deleted = await Article.withDeleted.find(article.slug);
final List<Article> everything = await Article.withDeleted.all();

await Article.restore(article.slug); // visible again

Article.useSearchProvider(DVInMemorySearchProvider<Article, ArticleFacets>(
  records: await Article.all(),
  document: (Article article) => '${article.title} ${article.body}',
));

final DVSearchResultPage<Article> page = await Article.search('dart', perPage: 10);

GETTING STARTED

APP

DATA

BACKEND

OPERATIONS

SHIPPING

REFERENCE

Data models

Declare a data model

Data model options

Field annotations

Save, find and delete records

Use the generated form, table and page

Add an admin screen

Serve a public page per record

Decide who sees what

Render a record in your own page

List the static paths yourself

Catch stale writes

Keep and revert record history

Soft delete and restore

Search records

Protect sensitive fields

Status