فرم‌های پیشرفته

فینچ امکانات پیشرفته‌ای برای مدیریت فرم‌ها در برنامه‌های وب شما فراهم می‌کند. می‌توانید به راحتی فرم‌ها را ایجاد، اعتبارسنجی و پردازش کنید.

فرم پیشرفته چیست؟

فرم‌های پیشرفته در فینچ راهی برای ساخت فرم‌های پیچیده با اعتبارسنجی و مدیریت خطا هستند. این فرم‌ها مبتنی بر کلاس AdvancedForm هستند که راه ساده‌ای برای ساخت فرم با اعتبارسنجی و مدیریت خطا فراهم می‌کند. می‌توانید با این کلاس فرم‌هایی با چندین فیلد و قوانین اعتبارسنجی مختلف بسازید.

این کلاس داده‌ها را از درخواست می‌خواند و بر اساس قوانین اعتبارسنجی بررسی می‌کند. همچنین امکان رندر فرم در نما را فراهم می‌کند. می‌توانید برای ثبت‌نام، ورود، ویرایش پروفایل و ... از این کلاس استفاده کنید.

استفاده از فرم‌های پیشرفته

برای استفاده از فرم‌های پیشرفته باید یک کلاس بسازید که از AdvancedForm ارث‌بری کند و متد fields را پیاده‌سازی کند که لیستی از اشیای Field را بازمی‌گرداند. هر شیء Field نماینده یک فیلد فرم و قوانین اعتبارسنجی آن است.

مثال ساخت فرم ثبت‌نام کاربر:

class UserRegistrationForm extends AdvancedForm {
  @override
  String get widget => 'forms/registration.j2.html';

  @override
  String get name => 'form_example';

  @override
  List<Field> fields() {
    return [
      csrf(),
      Field('name', validators: [
        FieldValidator.requiredField(),
        FieldValidator.fieldLength(min: 3),
      ]),
      Field('email', validators: [
        FieldValidator.requiredField(),
        // سایر اعتبارسنجی‌ها
      ]),
    ];
  }
}

ایجاد فرم در HTML

می‌توانید فرم را در قالب HTML خود با عناصر استاندارد ایجاد کنید:

<form method="post" action="/submit">
  <input type="text" name="username" />
  <input type="password" name="password" />
  <button type="submit">ارسال</button>
</form>

مدیریت ارسال فرم

در کنترلر خود می‌توانید ارسال فرم را با دسترسی به داده‌های درخواست مدیریت کنید:

class MyController extends Controller {
  @Post('/submit')
  Future<Response> submitForm(Request req) async {
    final username = req.body['username'];
    final password = req.body['password'];
    // پردازش داده‌ها
    return Response.text('فرم ارسال شد!');
  }
}

اعتبارسنجی فرم

می‌توانید داده‌های فرم را با ابزارهای اعتبارسنجی فینچ اعتبارسنجی کنید:

import 'package:finch/finch.dart';

class MyController extends Controller {
  @Post('/submit')
  Future<Response> submitForm(Request req) async {
    final validator = Validator(req.body);
    validator.required(['username', 'password']);
    if (!validator.isValid) {
      return Response.text('اعتبارسنجی ناموفق: ' + validator.errors.join(', '));
    }
    // پردازش داده‌ها
    return Response.text('فرم ارسال شد!');
  }
}

آپلود فایل

فینچ از آپلود فایل در فرم‌ها پشتیبانی می‌کند. می‌توانید به فایل‌های آپلود شده با ویژگی req.files دسترسی داشته باشید:

class MyController extends Controller {
  @Post('/upload')
  Future<Response> uploadFile(Request req) async {
    final file = req.files['myfile'];
    if (file != null) {
      // ذخیره یا پردازش فایل
    }
    return Response.text('فایل آپلود شد!');
  }
}

محافظت CSRF

فینچ محافظت CSRF را برای فرم‌های شما فراهم می‌کند. می‌توانید توکن CSRF را با متغیر csrfToken در قالب خود قرار دهید:

<form method="post" action="/submit">
  <input type="hidden" name="csrf_token" value="{{ csrfToken }}" />
  <!-- سایر فیلدهای فرم -->
</form>

مثال

برای مشاهده مثال کامل، به پروژه example در مخزن فینچ مراجعه کنید.