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 );
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 theField.ISchema
interface - to a
Datatable
tabular display - to the
Forms.Checker
class provided bypwix: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 aname
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.
A field which have a
form = false
key/value pair is ignored when building the schema. -
Field.Def.toHelp()
Extract and returns the help data, which may be an empty object.
A field which have a
help = false
key/value pair is ignored when building the help data. -
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 a field definition suitable to instanciate a SimpleSchema .
A field which have a
schema = false
key/value pair is ignored when building the schema.
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 // 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.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.
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.1.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. 24th