TYPO3 v15 dev-main snapshot ()
This commit is contained in:
+245
@@ -0,0 +1,245 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
.. _concepts-finishers-savetodatabasefinisher:
|
||||
|
||||
=======================
|
||||
SaveToDatabase finisher
|
||||
=======================
|
||||
|
||||
The "SaveToDatabase finisher" saves data from a submitted form into a
|
||||
database table.
|
||||
|
||||
.. contents:: Table of contents
|
||||
|
||||
.. note::
|
||||
|
||||
This finisher cannot be used in the backend form editor. It can only be
|
||||
used in a form definition YAML file or programmatically.
|
||||
|
||||
.. include:: /Includes/_NoteFinisher.rst
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options:
|
||||
|
||||
SaveToDatabase finisher options
|
||||
===============================
|
||||
|
||||
The finisher options can be set in the form definition YAML file or
|
||||
programmatically:
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-table:
|
||||
|
||||
.. confval:: table
|
||||
:name: savetodatabasefinisher-table
|
||||
:type: string
|
||||
:required: true
|
||||
|
||||
Insert or update values in this table.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-mode:
|
||||
|
||||
.. confval:: mode
|
||||
:name: savetodatabasefinisher-mode
|
||||
:type: string
|
||||
:default: `'insert'`
|
||||
|
||||
`insert`
|
||||
will create a new database row with the values from the submitted form
|
||||
and/or some predefined values. See also :confval:`savetodatabasefinisher-elements` and
|
||||
:confval:`savetodatabasefinisher-databaseColumnMappings`.
|
||||
|
||||
`update`
|
||||
will update a database row with the values from the submitted form
|
||||
and/or some predefined values. In this case :confval:`savetodatabasefinisher-whereClause` is required.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-whereclause:
|
||||
|
||||
.. confval:: whereClause
|
||||
:name: savetodatabasefinisher-whereClause
|
||||
:type: array
|
||||
:required: true (if mode = update)
|
||||
:default: `[]`
|
||||
|
||||
The ``where`` clause for a database update action.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements:
|
||||
|
||||
.. confval:: elements
|
||||
:name: savetodatabasefinisher-elements
|
||||
:type: array
|
||||
:required: true
|
||||
|
||||
Use `options.elements` to map form element values to database columns (they must exist).
|
||||
Each key in `options.elements` has to match a form element identifier.
|
||||
The value of each key in `options.elements` is an array containing additional information.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements-mapondatabasecolumn:
|
||||
|
||||
.. confval:: elements.<formElementIdentifier>.mapOnDatabaseColumn
|
||||
:name: savetodatabasefinisher-elements-mapOnDatabaseColumn
|
||||
:type: string
|
||||
:required: true
|
||||
|
||||
The value from the submitted form element with the identifier
|
||||
`<formElementIdentifier>` will be written into this database column.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements-skipifvalueisempty:
|
||||
|
||||
.. confval:: elements.<formElementIdentifier>.skipIfValueIsEmpty
|
||||
:name: savetodatabasefinisher-elements-skipIfValueIsEmpty
|
||||
:type: bool
|
||||
:default: `false`
|
||||
|
||||
Set this to true if the database column should not be written if the value from the
|
||||
submitted form element with the identifier `<formElementIdentifier>` is empty
|
||||
(e.g. for password fields). Empty means strings without content, whitespace is valid content.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements-hashed:
|
||||
|
||||
.. confval:: elements.<formElementIdentifier>.hashed
|
||||
:name: savetodatabasefinisher-elements-hashed
|
||||
:type: bool
|
||||
:default: `false`
|
||||
|
||||
Set this to true if the value from the submitted form element should be hashed before
|
||||
writing into the database.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements-savefileidentifierinsteadofuid:
|
||||
|
||||
.. confval:: elements.<formElementIdentifier>.saveFileIdentifierInsteadOfUid
|
||||
:name: savetodatabasefinisher-elements-saveFileIdentifierInsteadOfUid
|
||||
:type: bool
|
||||
:default: `false`
|
||||
|
||||
By default, the uid of the FAL object will be written into the database column.
|
||||
Set this to true if you want to store the FAL identifier
|
||||
(e.g. `1:/user_uploads/some_uploaded_pic.jpg`) instead.
|
||||
|
||||
This only applies for form elements which create a FAL object like
|
||||
`FileUpload` or `ImageUpload`.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-elements-dateformat:
|
||||
|
||||
.. confval:: elements.<formElementIdentifier>.dateFormat
|
||||
:name: savetodatabasefinisher-elements-dateFormat
|
||||
:type: string
|
||||
:default: `'U'`
|
||||
|
||||
If the internal datatype is :php:`\DateTime` (true for the form element type
|
||||
:yaml:`Date`), the object needs to be converted into a string.
|
||||
This option defines the format of the date. You can use any format accepted by
|
||||
the PHP :php:`date()` function.
|
||||
Default is `'U'` (Unix timestamp).
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings:
|
||||
|
||||
.. confval:: databaseColumnMappings
|
||||
:name: savetodatabasefinisher-databaseColumnMappings
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
Use this to map database columns to values.
|
||||
Each key within `options.databaseColumnMappings` has to match an existing database column.
|
||||
Each value in `options.databaseColumnMappings` is an array with
|
||||
additional information.
|
||||
|
||||
This mapping is done *before* :confval:`savetodatabasefinisher-elements` are mapped.
|
||||
If you map both, the value from :confval:`savetodatabasefinisher-elements` will override the
|
||||
:confval:`savetodatabasefinisher-databaseColumnMappings-value`.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings-value:
|
||||
|
||||
.. confval:: databaseColumnMappings.<databaseColumnName>.value
|
||||
:name: savetodatabasefinisher-databaseColumnMappings-value
|
||||
:type: string
|
||||
:required: true
|
||||
|
||||
The value which will be written to the database column.
|
||||
You can also use the :ref:`FormRuntime accessor feature
|
||||
<concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor>`
|
||||
to access properties from the `FormRuntime`, e.g. `{<formElementIdentifier>}`.
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings-skipifvalueisempty:
|
||||
|
||||
.. confval:: databaseColumnMappings.<databaseColumnName>.skipIfValueIsEmpty
|
||||
:name: savetodatabasefinisher-databaseColumnMappings-skipIfValueIsEmpty
|
||||
:type: bool
|
||||
:default: `false`
|
||||
|
||||
Set this to true if the database column should not be written if the value from
|
||||
:confval:`savetodatabasefinisher-databaseColumnMappings-value` is empty.
|
||||
|
||||
.. confval:: translation.propertiesExcludedFromTranslation
|
||||
:name: savetodatabasefinisher-translation-propertiesExcludedFromTranslation
|
||||
:type: array
|
||||
:default: `[]`
|
||||
|
||||
Defines a list of finisher option properties to be excluded from
|
||||
translation.
|
||||
|
||||
If set, these properties are not processed by the
|
||||
:php-short:`\TYPO3\CMS\Form\Service\TranslationService` during translation.
|
||||
This prevents the values from being replaced by
|
||||
translated equivalents, even if translations exist for those options.
|
||||
|
||||
This option is usually generated when FlexForm overrides
|
||||
exist and normally does not need to be set manually in the form
|
||||
definition.
|
||||
|
||||
See `Skip translation of overridden form finisher options <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher-yaml-propertiesexcludedfromtranslation>`_
|
||||
for an example.
|
||||
|
||||
.. _concepts-finishers-savetodatabasefinisher-yaml:
|
||||
|
||||
SaveToDatabase finisher in a YAML form definition
|
||||
=================================================
|
||||
|
||||
This finisher saves data from a submitted form into a database table.
|
||||
|
||||
.. literalinclude:: _codesnippets/_form.yaml
|
||||
:linenos:
|
||||
:caption: public/fileadmin/forms/my_form.yaml
|
||||
|
||||
.. _concepts-finishers-savetodatabasefinisher-example-news:
|
||||
|
||||
Example: adding uploads to ext:news (fal_related_files and fal_media):
|
||||
======================================================================
|
||||
|
||||
.. literalinclude:: _codesnippets/_example-fal-uploads_news.yaml
|
||||
:linenos:
|
||||
:caption: public/fileadmin/forms/my_form_with_multiple_finishers.yaml
|
||||
|
||||
.. _apireference-finisheroptions-savetodatabasefinisher:
|
||||
|
||||
Using a SaveToDatabase finisher in PHP code
|
||||
================================================
|
||||
|
||||
Developers can use the finisher key `SaveToDatabase` to create
|
||||
flash message finishers in their own classes:
|
||||
|
||||
.. literalinclude:: _codesnippets/_finisher.php.inc
|
||||
:language: php
|
||||
:linenos:
|
||||
|
||||
This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\SaveToDatabaseFinisher`.
|
||||
|
||||
.. _concepts-finishers-savetodatabasefinisher-multiple:
|
||||
|
||||
Multiple database operations
|
||||
============================
|
||||
|
||||
You can use options to perform multiple database operations.
|
||||
|
||||
Example form definition file (performs inserts):
|
||||
|
||||
.. literalinclude:: _codesnippets/_example-fal-uploads_news.yaml
|
||||
:linenos:
|
||||
:caption: public/fileadmin/forms/my_form_with_multiple_finishers.yaml
|
||||
|
||||
Using PHP code (performs an update):
|
||||
|
||||
.. literalinclude:: _codesnippets/_finisher.php.inc
|
||||
:language: php
|
||||
:linenos:
|
||||
|
||||
You can access inserted UIDs with '{SaveToDatabase.insertedUids.<theArrayKeyNumberInsideOptions>}'.
|
||||
If you perform an insert operation, the inserted values will be stored in the FinisherVariableProvider.
|
||||
<theArrayKeyNumberInOptions> references the numeric options.* key.
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
-
|
||||
identifier: SaveToDatabase
|
||||
options:
|
||||
-
|
||||
table: tx_news_domain_model_news
|
||||
mode: insert
|
||||
elements:
|
||||
my-field:
|
||||
mapOnDatabaseColumn: bodytext
|
||||
imageupload-1:
|
||||
mapOnDatabaseColumn: fal_media
|
||||
fileupload-1:
|
||||
mapOnDatabaseColumn: fal_related_files
|
||||
databaseColumnMappings:
|
||||
pid:
|
||||
value: 3
|
||||
tstamp:
|
||||
value: '{__currentTimestamp}'
|
||||
datetime:
|
||||
value: '{__currentTimestamp}'
|
||||
crdate:
|
||||
value: '{__currentTimestamp}'
|
||||
hidden:
|
||||
value: 1
|
||||
-
|
||||
table: sys_file_reference
|
||||
mode: insert
|
||||
elements:
|
||||
imageupload-1:
|
||||
mapOnDatabaseColumn: uid_local
|
||||
skipIfValueIsEmpty: true
|
||||
databaseColumnMappings:
|
||||
tablenames:
|
||||
value: tx_news_domain_model_news
|
||||
fieldname:
|
||||
value: fal_media
|
||||
tstamp:
|
||||
value: '{__currentTimestamp}'
|
||||
crdate:
|
||||
value: '{__currentTimestamp}'
|
||||
showinpreview:
|
||||
value: 1
|
||||
uid_foreign:
|
||||
value: '{SaveToDatabase.insertedUids.0}'
|
||||
-
|
||||
table: sys_file_reference
|
||||
mode: insert
|
||||
elements:
|
||||
fileupload-1:
|
||||
mapOnDatabaseColumn: uid_local
|
||||
skipIfValueIsEmpty: true
|
||||
databaseColumnMappings:
|
||||
tablenames:
|
||||
value: tx_news_domain_model_news
|
||||
fieldname:
|
||||
value: fal_related_files
|
||||
tstamp:
|
||||
value: '{__currentTimestamp}'
|
||||
crdate:
|
||||
value: '{__currentTimestamp}'
|
||||
uid_foreign:
|
||||
value: '{SaveToDatabase.insertedUids.0}'
|
||||
-
|
||||
table: sys_file_reference
|
||||
mode: update
|
||||
whereClause:
|
||||
uid_foreign: '{SaveToDatabase.insertedUids.0}'
|
||||
uid_local: 0
|
||||
databaseColumnMappings:
|
||||
pid:
|
||||
value: 0
|
||||
uid_foreign:
|
||||
value: 0
|
||||
+30
@@ -0,0 +1,30 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Core\Utility\GeneralUtility;
|
||||
use TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher;
|
||||
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
|
||||
class SomeClass
|
||||
{
|
||||
private function addDeleteUploadsFinisherWithMessage(FormDefinition $formDefinition, string $message)
|
||||
{
|
||||
$formDefinition->createFinisher('SaveToDatabase', [
|
||||
1 => [
|
||||
'table' => 'my_table',
|
||||
'mode' => 'insert',
|
||||
'databaseColumnMappings' => [
|
||||
'some_column' => ['value' => 'cool'],
|
||||
],
|
||||
],
|
||||
2 => [
|
||||
'table' => 'my_other_table',
|
||||
'mode' => 'update',
|
||||
'whereClause' => [
|
||||
'pid' => 1,
|
||||
],
|
||||
'databaseColumnMappings' => [
|
||||
'some_other_column' => ['value' => '{SaveToDatabase.insertedUids.1}'],
|
||||
],
|
||||
],
|
||||
]);
|
||||
}
|
||||
}
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
<?php
|
||||
|
||||
use TYPO3\CMS\Core\Utility\GeneralUtility;
|
||||
use TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher;
|
||||
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
|
||||
class SomeClass
|
||||
{
|
||||
private function addDeleteUploadsFinisherWithMessage(FormDefinition $formDefinition, string $message)
|
||||
{
|
||||
$formDefinition->createFinisher('SaveToDatabase', [
|
||||
'table' => 'fe_users',
|
||||
'mode' => 'update',
|
||||
'whereClause' => [
|
||||
'uid' => 1,
|
||||
],
|
||||
'databaseColumnMappings' => [
|
||||
'pid' => ['value' => 1],
|
||||
],
|
||||
'elements' => [
|
||||
'textfield-identifier-1' => ['mapOnDatabaseColumn' => 'first_name'],
|
||||
'textfield-identifier-2' => ['mapOnDatabaseColumn' => 'last_name'],
|
||||
'textfield-identifier-3' => ['mapOnDatabaseColumn' => 'username'],
|
||||
'advancedpassword-1' => [
|
||||
'mapOnDatabaseColumn' => 'password',
|
||||
'skipIfValueIsEmpty' => true,
|
||||
'hashed' => true
|
||||
],
|
||||
],
|
||||
]);
|
||||
}
|
||||
}
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
identifier: SaveToDatabase
|
||||
options:
|
||||
1:
|
||||
table: 'my_table'
|
||||
mode: insert
|
||||
databaseColumnMappings:
|
||||
some_column:
|
||||
value: 'cool'
|
||||
2:
|
||||
table: 'my_other_table'
|
||||
mode: update
|
||||
whereClause:
|
||||
pid: 1
|
||||
databaseColumnMappings:
|
||||
some_other_column:
|
||||
value: '{SaveToDatabase.insertedUids.1}'
|
||||
+28
@@ -0,0 +1,28 @@
|
||||
identifier: example-form
|
||||
label: 'example'
|
||||
type: Form
|
||||
|
||||
finishers:
|
||||
-
|
||||
identifier: SaveToDatabase
|
||||
options:
|
||||
table: 'fe_users'
|
||||
mode: update
|
||||
whereClause:
|
||||
uid: 1
|
||||
databaseColumnMappings:
|
||||
tstamp:
|
||||
value: '{__currentTimestamp}'
|
||||
pid:
|
||||
value: 1
|
||||
elements:
|
||||
textfield-identifier-1:
|
||||
mapOnDatabaseColumn: 'first_name'
|
||||
textfield-identifier-2:
|
||||
mapOnDatabaseColumn: 'last_name'
|
||||
textfield-identifier-3:
|
||||
mapOnDatabaseColumn: 'username'
|
||||
advancedpassword-1:
|
||||
mapOnDatabaseColumn: 'password'
|
||||
skipIfValueIsEmpty: true
|
||||
hashed: true
|
||||
Reference in New Issue
Block a user