dbxForm Leitfaden

dbxForm ist die Standardpipeline fuer Formulare, Panels und einfache Template-Ausgaben.

Wofuer dbxForm genutzt wird

• Eingabeformulare.
• Admin-Panels.
• Konfigurationsmasken.
• Template-Ausgaben mit Markern und Objekten.
• Formularzustand, Validierung, Meldungen und AJAX-Targets.

Minimalbeispiel

$form = new \dbxForm();
$form->init('contact-edit', 'contact-edit');
$form->_action = '?dbx_modul=dbxContact_admin&dbx_run1=save';
$form->_dd = 'dbxContact|contactRequest';
$form->_fd = 'dbxContact|contact-request-form';
 
$form->add_flds('fd::');
 
return $form->run();

Template:

<div id="dbx_target_{i}" class="dbx-panel dbxForm_wrapper">
   <form action="{action}" method="post" id="dbx_form_{i}" class="dbxAjax"
         data-ajax-target="dbx_target_{i}" data-ajax-replace="target">
      [dbx:form]
      <button class="btn btn-primary" type="submit">Speichern</button>
   </form>
</div>

Reales Beispiel: Profil bearbeiten

Das Benutzerprofil nutzt dbxForm mit einem eigenen Template:

dbx/modules/dbxUser/include/dbxUser_profil.class.php
dbx/modules/dbxUser/tpl/htm/form-profil.htm

Der Modulcode bereitet Daten, Formularzustand, Felder, Modul-Bar und Save-Aktion vor:

$oForm = dbx()->get_system_obj('dbxForm');
$oForm->init('dbxUser_profil', 'form-profil');
$oForm->_dd = 'dbxUser';
$oForm->_action = '?dbx_modul=dbxUser&dbx_run1=user&dbx_run2=edit_profil';
$oForm->add_module_bar(
   'Mein Profil',
   'bi-person-circle',
   'Eigene Stammdaten, Kontakt, Adresse und Oberflaeche'
);
$oForm->prepare_form_shell(array('class' => 'dbx-user-profile-form'));
$oForm->add_obj('avatar', 'obj-value', dbx()->get_include_obj('dbxUser_avatar')->run());
$oForm->add_fld('name', 'text-label', 'Name', 'parameter|max=255');
$oForm->add_fld('email', 'text-label', 'E-Mail', 'email|max=255');

Das Template bestimmt nur die Anordnung:

[tpl=dbx|form-shell-head]
 <div class="row g-3 align-items-start">
  <div class="col-lg-8">
   <section class="dbx-form-group">
    <div class="dbx-form-group-head">
     <h5>Persoenliche Daten</h5>
    </div>
    <div class="row g-3">
     <div class="col-md-4">{obj:name}</div>
     <div class="col-md-4">{obj:name2}</div>
     <div class="col-md-4">{obj:email}</div>
    </div>
   </section>
  </div>
  <div class="col-lg-4">
   {obj:avatar}
  </div>
 </div>
[tpl=dbx|form-shell-foot]

Das ist der wichtige Punkt: dbxForm erzeugt die Feldobjekte, validiert, speichert und fuehrt Meldungen. Das Template ordnet {obj:...} in Gruppen, Spalten und Shell-Templates an.

add_rep und add_obj

add_rep() setzt einfache Marker:

$form->add_rep('headline', dbx()->esc('Kontakt bearbeiten'));

add_obj() rendert oder setzt Teilobjekte:

$form->add_obj('report', 'obj-value', $this->message_report($id));

Template:

<h2>{headline}</h2>
{obj:report}

FD und DD in dbxForm

dbxForm kann Felder aus DD oder FD aufbauen:

$form->_dd = 'dbxContact|contactRequest';
$form->_fd = 'dbxContact|contact-request-form';
$form->add_fld('subject', tpl: 'fd::', label: 'fd::', rules: 'fd::');

Kurzform:

$form->add_flds('fd::');

Speichern

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
   $form->check_flds_data();
   if (!$form->has_errors()) {
      $form->save($rid);
   }
}

Der genaue Save-Ablauf haengt vom vorhandenen Modulcode ab. Wichtig ist: Die Validierung und Feldzustandslogik bleiben in dbxForm.

Form mit Report

Ein Formular kann einen Report enthalten:

$form = new \dbxForm();
$form->init('ticket-detail', 'ticket-detail');
$form->add_rep('ticket_id', (int)$id);
$form->add_obj('messages', 'obj-value', $this->message_report($id));
return $form->run();

Template:

<div id="dbx_target_{i}" class="dbx-panel">
   <form action="{action}" method="post" class="dbxAjax"
         data-ajax-target="dbx_target_{i}">
      [dbx:form]
   </form>
   {obj:messages}
</div>

AJAX

Formulare verwenden ajax.js:

<form class="dbxAjax" data-ajax-target="dbx_target_{i}" data-ajax-replace="target">

Der Server liefert im Standard HTML zurueck. JSON ist nur fuer reine Datenaktionen gedacht.

Regeln

• Kein Formular-HTML komplett in PHP bauen.
• FD/DD verwenden.
• Eindeutiges Target mit {i} nutzen.
• Meldungen ueber dbxForm fuehren.
• JavaScript nur ueber Libs anbinden.