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

• help lines.

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    );

This package is not tied to a client or server side. We strongly suggest to use it in common code.

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
• as a help memento with help_-prefixed keys.

A Field.Def is instanciated with an object with some specific keys, depending of the target usage:

• Mongo schema

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

  Some particular keys are defined and are considered here:

  • name

    Optional, the name of the field.

    Though this field is optional at the Field.Def level, it is mandatory to trigger a schema definition. In other words, Field.Def definitions are just ignored from schema point of view if no name is set.

  • schema

    When false, ignore this Field.Def definition from schema point of view even if a name is set.

• Tabular display

  Tabular display is managed through Datatable.

  The Field.Def definitions are used to build the columns definition argument at Tabular.Table instanciation time. All arguments accepted in this columns definition can be provided here, with a dt_ prefix, plus following keys:

  • 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.

  • dt_template

  • dt_templateContext

    Replace the tmpl and tmplContext defined by aldeed:tabular with same mean and usage.

• Forms usage

  All Forms.Checker keys must be passed with a form_ prefix. All fields are considered unless a form: false is specified.

  See pwix:forms documentation for the list of available keys.

Methods

• Field.Def.set( attribs<Object> )

  Merge a new definition part with the existing one.

• Field.Def.toForm()

  Returns a columns specification suitable to Forms setup.

  A field which have a form = false key/value pair is ignored when building the fields definition.

  All Field.Def definitions are considered when building the forms definition, unless:

  • no name is set

  • or a form = false key/value pair is specified.

  If none of the two above conditions are met, then the method returns at least an empty object.

• Field.Def.toHelp()

  Extract and returns the help data, which may be an empty object.

  All Field.Def definitions are considered when building the help data, unless:

  • no name is set

  • or a help: false key/value pair is specified.

  If none of the two above conditions are met, then the method returns at least an empty object.

• Field.Def.toTabular()

  Returns a column definition suitable to Datatable initialization.

  A field which have a dt_tabular = false key/value pair is ignored when building the tabular definition.

• Field.Def.toSchema()

  Returns an object with fields definitions suitable to instanciate a SimpleSchema.

  All Field.Def definitions are considered when building a schema, unless:

  • no name is set

  • or a schema = false key/value pair is specified.

Field.Set

An ordered collection of Field.Def objects.

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

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

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.extend( <Array|Object> )

  Extends the Field.Set set with the provided fields definitions, as an object, or an array of objects, where each object has following keys:

  • before: the optional column reference name to be inserted before, must be already defined.

    If a column name is not specified, then the provided fields definitions are appended to the existing ones.

  • fields: an array of field definitions.

• Field.Set.names()

  Returns the array of defined name's.

• Field.Set.toForm()

  Returns an ordered list of columns definitions suitable to Forms setup.

• Field.Set.toHelp()

  Extract and returns a keyed object with the help data.

• 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.

Field.configure() is a reactive data source.

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.4.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, Oct. 4th