nswdpc/silverstripe-details-field

Composite form field rendered as an HTML details tag, with child fields

Installs: 373

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 1

Forks: 0

Open Issues: 0

Type:silverstripe-vendormodule

v1.0.0 2024-05-14 02:27 UTC

This package is auto-updated.

Last update: 2024-10-14 03:28:01 UTC


README

This module implements a FormField for Silverstripe using the HTML Details element.

The field is a CompositeField allowing zero or more child fields to be displayed when the element is in an open state.

It's useful for containing long selection fields and/or optional information not required in a form submission.

Usage

After module installation, use the DetailsField in code:

Adding child fields

<?php
namespace MyApp;

use NSWDPC\Forms\DetailsField\DetailsField;
use SilverStripe\Forms\FieldList;
use SilverStripe\Forms\TextField;

// ... etc

$childFields = FieldList::create(
    TextField::create('Salutation', _t('myapp.SALUTATION','Salutation')),
    TextField::create('FirstName', _t('myapp.FIRST_NAME','First name')),
    TextField::create('Surname', _t('myapp.SURNAME','Surname'))
);

$detailsField = DetailsField::create($childFields)
    ->setTitle(
        _t(
            'myapp.PROVIDE_DETAILS',
            'Provide some optional information'
        )
    )->setDescription(
        _t(
            'myapp.PROVIDE_DETAILS_DESCRIPTION',
            'A field description'
        )
    );
    
// by default the element is in a closed state, to open by default (or when values are present in the child fields)
// $detailsField = $detailsField->setIsOpen(true)

// push onto form fields
$fields->push($detailsField);
// ... etc

See tests/DetailsFieldTest for more.

Example rendered field

Provide some optional information

A field description

Salutation [___________] First name [___________] Surname [___________]

Extras

  • setTitle is aliased to the setSummary method, both set the title property value on the field
  • You can set a standard FormField description, right title and field validation message
  • IsOpen and Summary return those property values, for use in templates
  • As the <summary> element can contain certain HTML, you can provide a DBHTMLVarchar field as the value to setTitle or setSummary
  • When the field or a child field has a validation message, the details element will be open by default

Installation

composer require nswdpc/silverstripe-details-field

License

BSD-3-Clause

Maintainers

Bugtracker

We welcome bug reports, pull requests and feature requests on the Github Issue tracker for this project.

Please review the code of conduct prior to opening a new issue.

Security

If you have found a security issue with this module, please email digital[@]dpc.nsw.gov.au in the first instance, detailing your findings.

Development and contribution

If you would like to make contributions to the module please ensure you raise a pull request and discuss with the module maintainers.

Please review the code of conduct prior to completing a pull request.