pwix:field

What is it ?

A package to manage field definitions in Meteor. You define here at once all specifications needed for both:

SimpleSchema definition, with aldeed:simple-schema
Datatables display, with aldeed:tabular
forms input, with pwix:forms
getter, setter and both client and server sides checks.

Installation

This Meteor package is installable with the usual command:

    meteor add pwix:field

Usage

1    import { Field } from 'meteor/pwix:field';
2
3    // define your fields specifications, both suitable for schema collection, tabular display and form edition
4    // this is mainly a SimpleSchema extenstion
5    const fieldSet = new Field.Set(
6        {
7            name: 'name'
8            type: String
9        },
10        {
11            name: 'surname',
12            type: String,
13            optional: true
14        }
15    );

Provides

`Field`

The exported Field global object provides following items:

Functions

`Field.configure()`

See [below](#configuration).

Classes

`Field.Def`

A class which provides the ad-hoc definitions for (almost) every use of a field in an application, and in particular:

to a SimpleSchema collection schema through the Field.ISchema interface
to a Datatable tabular display
to the Forms.Checker class provided by pwix:forms.

A Field.Def is instanciated with an object with some specific keys:

name

optional, the name of the field.

When set, defines a field in the collection schema, a column in the tabular display, an input element in the edition panel.

If not set, then there will NOT be any field defined in the Mongo collection.
dt_tabular

optional, whether to have this field in the columns of a tabular display, defaulting to true.

The whole field definition is ignored from tabular point of view when dt_tabular is false.
dt_data

optional, whether to have this field as a data subscription in a tabular display, defaulting to true if a name is set.

A named field defaults to be subscribed to by a tabular display. This option prevents to have a useless data subscription.

All SimpleSchema keys can be set in this field definition, and will be passed to the SimpleSchema() instanciation.

All Datatables column options are to be be passed with a dt_ prefix.

All Forms.Checker keys must be passed with a form_ prefix.

Methods

Field.Def.toForm()

Returns a columns specification suitable to Forms setup.
Field.Def.toTabular()

Returns a column definition suitable to Datatable initialization.
Field.Def.toSchema()

Returns a field definition suitable to instanciate a SimpleSchema .

`Field.Set`

An ordered collection of Field.Def objects.

It should be instanciated by the caller with a list of fields definitions as plain javascript objects.

1    app.fieldsSet = new Field.Set(
2        {
3            name: '_id',
4            type: String,
5            dt_tabular: false
6        },
7        {
8            name: 'emails',
9            type: Array,
10            optional: true,
11            dt_visible: false
12        },
13        {
14            name: 'emails.$',
15            type: Object,
16            optional: true,
17            dt_tabular: false
18        },
19        {
20            name: 'emails.$.address',
21            type: String,
22            regEx: SimpleSchema.RegEx.Email,
23            dt_data: false,
24            dt_title: pwixI18n.label( I18N, 'list.email_address_th' ),
25            dt_template: Meteor.isClient && Template.email_address,
26            form_check: AccountsManager.check?.emailAddress,
27            form_checkType: 'optional'
28        },
29        {
30            name: 'emails.$.verified',
31            type: Boolean,
32            dt_data: false,
33            dt_title: pwixI18n.label( I18N, 'list.email_verified_th' ),
34            dt_template: Meteor.isClient && Template.email_verified,
35            form_check: AccountsManager.check?.emailVerified
36        },
37        {
38            dt_template: Meteor.isClient && Template.email_more
39        },
40        {
41            name: 'username',
42            type: String,
43            optional: true,
44            dt_title: pwixI18n.label( I18N, 'list.username_th' ),
45            form_check: AccountsManager.check?.username
46        },
47        {
48            name: 'profile',
49            type: Object,
50            optional: true,
51            blackbox: true,
52            dt_tabular: false
53        },
54        Notes.field({
55            name: 'userNotes',
56            dt_title: pwixI18n.label( I18N, 'list.user_notes_th' ),
57            //dt_template: Meteor.isClient && Notes.template
58        })
59    );

Both all fields of a Mongo document, all columns of a tabular display based on this collection, and all fields managed in an editing panel must be defined here. Hence the different definitions.

Methods

Field.Set.byName( name )

Returns the named Field.Def object, or null.

Because the name key is optional when defining a field, then not all field's are retrievable by this method.
Field.Set.toForm()

Returns an ordered list of columns definitions suitable to Forms setup.
Field.Set.toTabular()

Returns an ordered list of columns definitions suitable to Datatable initialization.
Field.Set.toSchema()

Returns a field definition suitable to instanciate a SimpleSchema .

Configuration

The package's behavior can be configured through a call to the Field.configure() method, with just a single javascript object argument, which itself should only contains the options you want override.

Known configuration options are:

verbosity

Define the expected verbosity level.

The accepted value can be any or-ed combination of following:
- Field.C.Verbose.NONE
  
  Do not display any trace log to the console
- Field.C.Verbose.CONFIGURE
  
  Trace Field.configure() calls and their result

Please note that Field.configure() method should be called in the same terms both in client and server sides.

Remind too that Meteor packages are instanciated at application level. They are so only configurable once, or, in other words, only one instance has to be or can be configured. Addtionnal calls to Field.configure() will just override the previous one. You have been warned: only the application should configure a package.

NPM peer dependencies

Starting with v 0.3.0, and in accordance with advices from the Meteor Guide, we no more hardcode NPM dependencies in the Npm.depends clause of the package.js.

Instead we check npm versions of installed packages at runtime, on server startup, in development environment.

Dependencies as of v 1.0.0:

1    'lodash': '^4.17.0'

Each of these dependencies should be installed at application level:

    meteor npm install <package> --save

Translations

None at the moment.

Cookies and comparable technologies

None at the moment.

Issues & help

In case of support or error, please report your issue request to our Issues tracker.

P. Wieser

Last updated on 2024, Jun. 23rd