card_settings 1.5.3
Card Settings #
A flutter package for building card based settings forms. This includes a library of pre-built form field widgets. The style is a bit like a cross between the cupertino settings screen and material design; The idea is it should be usable and intutive on both iOS and Android.
This package consists of a CardSettings layout wrapper and a series of form field options including:
- Text Fields
- CardSettingsText - Basic text field
- CardSettingsParagraph - Multiline text field with a counter
- CardSettingsEmail - A text field pre-configured for email input
- CardSettingsPassword - A text field pre-configured for passwords
- CardSettingsPhone - A masked phone entry field (US style currently)
- Numeric Fields
- CardSettingsDouble - Field for double precision numbers
- CardSettingsInt - Field for integer numbers
- CardSettingsCurrency - Field for currency entry
- CardSettingsSwitch - Field for boolean state
- Pickers
- CardSettingsListPicker - Picker list of arbitrary options
- CardSettingsNumberPicker - Picker list of numbers in a given range
- CardSettingsColorPicker - Picker for colors with three flavors: RGB, Material, and Block
- CardSettingsDatePicker - Material Design Date Picker
- CardSettingsTimePicker - Material Design Time Picker
- Selection
- CardSettingsMultiselect - Select from a list of available options
- Informational Sections
- CardSettingsHeader - A control to put a header between form sections
- CardSettingsInstructions - Informational read-only text
- Actions
- CardSettingsButton - Actions buttons for the form
All fields support validate
, onChange
, onSaved
, autovalidate
, and visible
.
- [Warning] For the text fields on iOS using [CupertinoTextFields] the [validator] and [onSaved] do not exist, please use [showErrorIOS] to show a [red] Border around the Text Field and [onChanged] and [onFieldSubmitted] to update the value like in the example.
- Require Indicator on iOS will show _next to the label if [requireIndicator] is not equal to null. (For Example: 'label _')
The package also includes these additonal items:
- CardSettingsField - The base layout widget. You can use this to build custom fields
- Converters - a set of utility functions to assist in converting data into and out of the fields
Simple Example #
All fields in this package are compatible with the standard Flutter Form widget. Simply wrap the CardSettings control in a form and use it as you normally would with the form functionality.
String title = "Spheria";
String author = "Cody Leet";
String url = "http://www.codyleet.com/spheria";
final GlobalKey<FormState> _formKey = GlobalKey<FormState>();
@override
Widget build(BuildContext context) {
body: Form(
key: _formKey,
child: CardSettings(
children: <Widget>[
CardSettingsHeader(label: 'Favorite Book'),
CardSettingsText(
label: 'Title',
initialValue: title,
validator: (value) {
if (value == null || value.isEmpty) return 'Title is required.';
},
onSaved: (value) => title = value,
),
CardSettingsText(
label: 'URL',
initialValue: url,
validator: (value) {
if (!value.startsWith('http:')) return 'Must be a valid website.';
},
onSaved: (value) => url = value,
),
],
),
),
);
}
See the full demo example here.
Theming #
The widgets support the material design theme. This example shows what global theme values to set to determine how the various elements appear.
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return new MaterialApp(
title: 'Card Settings Example',
home: new HomePage(),
theme: ThemeData(
accentColor: Colors.indigo[400], // used for card headers
cardColor: Colors.white, // used for field backgrounds
backgroundColor: Colors.indigo[100], // color outside the card
primaryColor: Colors.teal, // color of page header
buttonColor: Colors.lightBlueAccent[100], // background color of buttons
textTheme: TextTheme(
button: TextStyle(color: Colors.deepPurple[900]), // style of button text
subhead: TextStyle(color: Colors.deepOrange[900]), // style of input text
),
),
);
}
}
Or if you want to apply a different theme to the CardSettings
hierarchy only, you can wrap it in a Theme
widget like so:
Theme(
data: Theme.of(context).copyWith(
primaryTextTheme: TextTheme(
title: TextStyle(color: Colors.lightBlue[50]), // style for headers
),
inputDecorationTheme: InputDecorationTheme(
labelStyle: TextStyle(color: Colors.deepPurple), // style for labels
),
),
child: CardSettings(
...
),
)
Global Properties #
The CardSettings
widget implements a few global settings that all child fields can inherit. Currently it supports only label customization.
Labels #
You can control how the labels are rendered with four properties:
CardSettings(
labelAlign: TextAlign.right, // change the label alignment
labelWidth: 120.0, // change how wide the label portion is
labelSuffix: ':', // add an optional tag after the label
labelPadding: 10.0, // control the spacing between the label and the content
contentAlign: TextAlign.left, // alignment of the entry widgets
icon: Icon(Icons.person), // puts and option icon to the left of the label
requiredIndicator: Text('*', style: TextStyle(color: Colors.red)), // puts an optional indicator to the right of the label
)
The labelAlign
and contentAlign
properties are also available on each field, so you can override the global setting for individual fields.
CardSettingsText(
label: 'Last Name',
labelAlign: TextAlign.left,
contentAlign: TextAlign.right,
)
Dynamic Visibility #
Each field implements a visible
property that you can use to control the visibility based on the value of other fields. In this example, the switch field controls the visibility of the text field:
bool _ateOut = false;
CardSettingsSwitch(
label: 'Ate out?',
initialValue: _ateOut,
onChanged: (value) => setState(() => _ateOut = value),
),
CardSettingsText(
label: 'Restaurant',
visible: _ateOut,
),
Masking #
The CardSettingsText
widget has an inputMask
property that forces entered text to conform to a given pattern. This is built upon the flutter_masked_text
package and as such masks are formatted with the following characters:
- 0: accept numbers
- A: accept letters
- @: accept numbers and letters
- *: accept any character
So for example, phone number would be '(000) 000-0000'.
Note: CardSettingsPhone
is a convenience widget that is pre-configured to use this pattern.
Caution: flutter_masked_text
is a controller and as such, you will not be able to use an inputMask and a custom controller at the same time. This might be rectified in the future.
Orientation #
This suite allows for orientation switching. To configure this, build different layouts depending on the orientation provided by MediaQuery
.
You might want to have different fields in each layout, or a different field order. So that Flutter doesn't get confused tracking state under this circumstance, you must provide a unique state key for each individual field, using the same key in each layout.
@override
Widget build(BuildContext context) {
final GlobalKey<FormState> _emailKey = GlobalKey<FormState>();
var orientation = MediaQuery.of(context).orientation;
return Form
key: _formKey,(
child: (orientation == Orientation.portraitUp)
? CardSettings(children: <Widget>[
// Portrait layout here
CardSettingsEmail(key: _emailKey)
])
: CardSettings(children: <Widget>[
// Landscape layout here
CardSettingsEmail(key: _emailKey)
]);
},
);
}
You may have multiple fields on the same row in landscape orientation. This normally requires the use of container widgets to provide the layout inside the row. Instead, you can use the CardFieldLayout
helper widget to streamline this. It will by default make it's children equally spaced, but you can provide an array of flex values to control the relative sizes.
// equally spaced example
CardSettings(
children: <Widget>[
CardFieldLayout(children: <Widget>[
CardSettingsEmail(),
CardSettingsPassword(),
]),
],
);
// relative width example
CardSettings(
children: <Widget>[
CardFieldLayout_FractionallySpaced(
children: <Widget>[
CardSettingsEmail(),
CardSettingsPassword(),
],
flexValues: [2, 1], // 66% and 33% widths
),
],
);
Custom Fields #
The CardSettingsField
is the basis of all other fields and can be used to build unique fields outside of this library. Its purpose is to govern layout with consistent decorations. The best way to make a custom field is to inherit from FormField<T>
, which will manage the state of your field. The cleanest example of this is the CardSettingsSwitch
widget. All you have to do is provide your custom widgets in the content
property.
Screenshots #
Material | Cupertino |
---|---|
![]() | ![]() |
:-------------------------: | :-------------------------: |
![]() | ![]() |
:-------------------------: | :-------------------------: |
![]() | ![]() |
Dependencies #
This widget set relies on these external third-party components:
Changelog #
Please see the Changelog page to know what's recently changed.
Authors #
- Jeff Jorczak jeff@jorczak.com
- Rody Davis Jr rody.davis.jr@gmail.com
NOTE: We would like a third author for redundency. Please contect us if interested.
Contributions #
If you find a bug or want a feature, but don't know how to fix/implement it, please fill an issue.
If you fixed a bug or implemented a new feature, please send a pull request.
Releases #
[1.5.3] - 12/13/2019
- Enhanced ListPicker to allow a list of values separate from options. https://github.com/codegrue/card_settings/issues/60
[1.5.2] - 12/13/2019
- Fixed elevation not showing in .sectioned version. Padding as well. https://github.com/codegrue/card_settings/issues/63
[1.5.1] - 12/13/2019
- Fixed display of ColorPicker
- Added pickerType property to pick one of "Colors", "Material", or "Block". https://github.com/codegrue/card_settings/issues/62
- Migrated Android example to use AndroidX API
[1.5.0] - 12/12/2019
- Upgraded intl dpendency to 1.16.0 https://github.com/codegrue/card_settings/issues/82
- Added code to restrict double's number of decimal digits https://github.com/codegrue/card_settings/issues/81
- Added .IsDense to field content so heights line up
- Added global labelWidth property https://github.com/codegrue/card_settings/issues/80
- fixed all code warnings
- replaced deprecated code
[1.4.2] - 10/3/2019
- text align will now used property or end if null
- Added hint text and made initial value optional
- Fixed validator and save issue
- Fixed required indicator position in android
- dynamic multi line support
[1.4.1] - 2/21/2019
- Added Slider
- Added Dark Mode Support
- Updated Example
[1.4.0] - 2/18/2019
- Added Optional override for showing material on iOS
- Added Cupertino Forms and all Cupertino Equilivant Controls and Actions
- Updated Example
- [Warning] For the text fields on iOS using [CupertinoTextFields] the [validator] and [onSaved] do not exist, please use [showErrorIOS] to show a [red] Border around the Text Field and [onChanged] and [onFieldSubmitted] to update the value like in the example.
- Require Indicator on iOS will show * next to the label if [requireIndicator] is not equal to null.
[1.3.1] - 2/15/2019
- Updated Build Methodes for All Widgets (No More Errors for Dart 2)
- Added Cupertino Widgets for Date, DateTime, Time and List Picker (onLongPress Overrides to material)
[1.2.5] - 1/22/2019
- Fixed validator text not showing up in any new line fields (e.g. CardSettingsMultiselect)
[1.2.4] - 1/9/2019
- Allow for zero width margin around card by setting padding to zero
[1.2.3] - 1/9/2019
- Fixes text color not reflecting custom color in the Instructions widget
- Added the ability to hide the counter in the paragraph control
- Added missing hint text for the password field
- fixed case where if there is no change handler then we crashed
- Added missing contentOnNewLine field
- Added missing contentOnNewLine field
- Added missing contentOnNewLine field
[1.2.2] - 11/2/2018
- Fixed a crash bug with icons when a theme color is not provided
[1.2.1] - 10/2/2018
- Removed hard coded word 'Select' from picker title
- Added text capitalization to CardSettingsText
- Set picker to first item if no initialvalue is provided
- Added 'hintText' to CardListPicker
[1.2.0] - 9/8/2018
- Fixed overflow bug with picker dialogs on smaller screens
- Refactored row layout helpers into a single flexible
CardFieldLayout
[1.1.0] - 9/5/2018
- Added
hintText
toCardSettingsText
widget
[1.0.1] - 8/24/2018
- Changed Example to use
NativeDeviceOrientationReader
for orientation changes.
[1.0.0] - 8/24/2018
- Ready for full release. No API changes predicted
- Added Discord channel to the collaboration section
[0.1.16] - 8/23/2018
- Added
CardSettingsMultiselect
widget - Fixed bug when onChange was null
- Fixed validation issue with phone numbers
[0.1.15] - 8/20/2018
- Added landscape layout and material title for
CardSettingsListPicker
- Added landscape layout and material title for
CardSettingsNumberPicker
- Added landscape layout and material title for
CardSettingsColorPicker
[0.1.14] - 8/20/2018
- Added
CardFieldLayout_FractionallySpaced
for controlled spacing in a row - Fixed bug with labelAlign right not working
[0.1.13] - 8/19/2018
- Enhanced the example to show switching to landscape orientation
- Created
CardFieldLayout_EqualSpaced
to handle mutiple fields in a row.
[0.1.12] - 8/17/2018
- Added
padding
andcardElevation
toCardSettings
- Added support for field
icon
to every widget - Added a
requiredIndicator
to show next to a label - Removed
textInputAction
property to be compatible with the current beta branch
[0.1.11] - 8/15/2018
- downgraded intl dependency to ^0.15.6
- removed a few properties that were reported as issues in dartpub analyze
[0.1.10] - 8/9/2018
- Removed TextCapitalization from CardSettingsText due to an analysis error
[0.1.8] - 8/9/2018
- Added a analysis_options.yaml file and a bunch if linter checks
- Cleaned and tigtened code
[0.1.7] - 8/8/2018
- All fields now implement an
onChange
event. - Added a
CardSettingsPhone
widget - Enhanced
CardSettingsText
to allow a input mask (based on flutter_masked_text)
[0.1.6] - 8/2/2018
- Added contentAlign property to all fields to allow for right justification
- Added labelAlign to CardHeaders to allow center or right positioning
- Improved support of themes for input text and labels
[0.1.5] - 8/1/2018
- Support default button style through themes
- All text fields expose controller as optional parameter (except currency)
- Support theming of header text
- Changed
CardSettings
to anInheritableWidget
with global properties to control label appearance - Added a
labelAlign
property to all fields
[0.1.4] - 7/31/2018
- Added
CardSettingsEmail
field - Added
CardSettingsPassword
field - Changed all TextFormFields to be stateless widget wrappers
[0.1.3] - 7/30/2018
- Added
CardSettingsCurrency
field - Added
CardSettingsInstructions
field - Added
CardSettingsButton
field - Added ability to tap to select in pickers
[0.1.2] - 7/27/2018
- Attempt to improve documentation and remove warnings
[0.1.1] - 7/26/2018
- General cleanup to meet publication requirements.
[0.1.0] - 7/26/2018
- First release implementing card view and core set of field widgets.
card_settings_example #
Demonstrates how to use the card_settings package.
Getting Started #
For help getting started with Flutter, view our online documentation.
Use this package as a library
1. Depend on it
Add this to your package's pubspec.yaml file:
dependencies:
card_settings: ^1.5.3
2. Install it
You can install packages from the command line:
with Flutter:
$ flutter pub get
Alternatively, your editor might support flutter pub get
.
Check the docs for your editor to learn more.
3. Import it
Now in your Dart code, you can use:
import 'package:card_settings/card_settings.dart';
Popularity:
Describes how popular the package is relative to other packages.
[more]
|
90
|
Health:
Code health derived from static analysis.
[more]
|
100
|
Maintenance:
Reflects how tidy and up-to-date the package is.
[more]
|
80
|
Overall:
Weighted score of the above.
[more]
|
91
|
We analyzed this package on Dec 13, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:
- Dart: 2.7.0
- pana: 0.13.1+4
- Flutter: 1.12.13+hotfix.4
Health suggestions
Format lib/widgets/selection_fields/card_settings_multiselect.dart
.
Run flutter format
to format lib/widgets/selection_fields/card_settings_multiselect.dart
.
Maintenance issues and suggestions
Support latest dependencies. (-20 points)
The version constraint in pubspec.yaml
does not support the latest published versions for 2 dependencies (flutter_cupertino_settings
, flutter_masked_text
).
Dependencies
Package | Constraint | Resolved | Available |
---|---|---|---|
Direct dependencies | |||
Dart SDK | >=2.0.0 <3.0.0 | ||
auto_size_text | ^2.0.0 | 2.1.0 | |
cupertino_icons | ^0.1.2 | 0.1.3 | |
flutter | 0.0.0 | ||
flutter_colorpicker | ^0.2.6 | 0.2.6 | |
flutter_cupertino_settings | ^0.1.0 | 0.1.0 | 0.2.0 |
flutter_masked_text | ^0.7.0 | 0.7.0 | 0.8.0 |
intl | ^0.16.0 | 0.16.0 | |
meta | ^1.1.6 | 1.1.8 | |
Transitive dependencies | |||
collection | 1.14.11 | 1.14.12 | |
path | 1.6.4 | ||
sky_engine | 0.0.99 | ||
typed_data | 1.1.6 | ||
vector_math | 2.0.8 | ||
Dev dependencies | |||
flutter_test |