https://github.com/trychlos/pwix-field
Define common field specifications for Meteor usages
https://github.com/trychlos/pwix-field
Last synced: about 2 months ago
JSON representation
Define common field specifications for Meteor usages
- Host: GitHub
- URL: https://github.com/trychlos/pwix-field
- Owner: trychlos
- Created: 2024-06-23T10:07:31.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2024-11-19T15:08:51.000Z (over 1 year ago)
- Last Synced: 2025-01-16T06:28:29.107Z (over 1 year ago)
- Language: JavaScript
- Size: 66.4 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
Awesome Lists containing this project
README
# 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` or `pwix:tabular` extension,
- forms input, with `pwix:forms`,
- getter, setter and both client and server sides checks,
- help lines,
- or additional features.
## Installation
This Meteor package is installable with the usual command:
```sh
meteor add pwix:field
```
## Usage
```js
import { Field } from 'meteor/pwix:field';
// define your fields specifications, both suitable for schema collection, tabular display and form edition
// this is mainly a SimpleSchema extenstion
const fieldSet = new Field.Set(
{
name: 'name'
type: String
},
{
name: 'surname',
type: String,
optional: true
}
);
```
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`](https://datatables.net) tabular display with `dt_`-prefixed keys,
- to the `Forms.Checker` class provided by `pwix:forms` with `form_`-prefixed keys,
- to compare two items with `comp_`-prefixed keys,
- 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`](https://datatables.net).
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:
- `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 `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.
- Additional features
When it is needed to compare two objects, we may need to translate some data format to some comparable value.
While default is to EJSON.clone() each and every data, any fields can provide a `add_ejson()` function to replace this former.
###### Methods
- `Field.Def.set( attribs )`
Merge a new definition part with the existing one.
- `Field.Def.toForm()`
Returns a columns specification suitable to [Forms](https://github.com/trychlos/pwix-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](https://datatables.net/) initialization.
A field which have a `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](https://github.com/Meteor-Community-Packages/meteor-simple-schema).
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.
```js
app.fieldsSet = new Field.Set(
{
name: '_id',
type: String,
// not considered in the tabular displays
tabular: false
},
{
name: 'emails',
type: Array,
optional: true,
// not visible in the tabular displays
dt_visible: false
},
{
name: 'emails.$',
type: Object,
optional: true,
// not considered in the tabular displays
// really useless as emails is subscribed to anyway
tabular: false
},
{
name: 'emails.$.address',
type: String,
regEx: SimpleSchema.RegEx.Email,
dt_data: false,
// the title of the header
dt_title: pwixI18n.label( I18N, 'list.email_address_th' ),
dt_template: Meteor.isClient && Template.email_address,
// check function
form_check: AccountsManager.check?.emailAddress,
// if the email address is optional ?
form_checkType: 'optional'
},
{
name: 'emails.$.verified',
type: Boolean,
dt_data: false,
dt_title: pwixI18n.label( I18N, 'list.email_verified_th' ),
dt_template: Meteor.isClient && Template.email_verified,
form_check: AccountsManager.check?.emailVerified
},
{
dt_template: Meteor.isClient && Template.email_more
},
{
name: 'username',
type: String,
optional: true,
dt_title: pwixI18n.label( I18N, 'list.username_th' ),
form_check: AccountsManager.check?.username
},
{
name: 'profile',
type: Object,
optional: true,
blackbox: true,
tabular: false
},
Notes.field({
name: 'userNotes',
dt_title: pwixI18n.label( I18N, 'list.user_notes_th' ),
//dt_template: Meteor.isClient && Notes.template
})
);
```
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.byPrefix( prefix )`
Returns the list of `Field.Def` objects which contains at least one key which starts by the given prefix, or an empty array.
`prefix` defaults to an empty string, which means all fields.
- `Field.Set.comparable( item )`
Returns an EJSON-comparable version of the provided item.
- `Field.Set.extend( [, options ] )`
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`: an optional column name to be inserted before, must be already defined.
If a column name is not specified, or not found, or the key not specified at all, then the provided fields definitions are appended to the existing ones.
- `fields`: an array of field definitions.
When a `Field.Set` is provided as first agument, then optional `options` is considered, following keys being honored:
- `rename`: an object where each key is the name of a `Field.Def` of the provided `Field.Set`, and each value the new name to be set in the result.
- `Field.Set.indexByName( name )`
Returns the index of the named column, or -1.
Because the `name` key is optional when defining a field, then not all field's are retrievable by this method.
- `Field.Set.names()`
Returns the array of defined `name`'s.
- `Field.Set.tabularIndexByName( name, opts )`
Returns the index inside of the tabular display of the named column, or -1.
Because the `name` key is optional when defining a field, then not all field's are retrievable by this method.
`opts` is an optional options object with following keys:
- `columns`, the tabular columns to be searched for, defaulting to the columns as returned by `toTabular()` method.
- `only_visible`, when set to `true`, returns an index based only on visible columns, defaulting to counting all columns.
- `Field.Set.toForm()`
Returns an ordered list of columns definitions suitable to [Forms](https://github.com/trychlos/pwix-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](https://datatables.net/) initialization.
- `Field.Set.toSchema()`
Returns a field definition suitable to instanciate a [SimpleSchema](https://github.com/Meteor-Community-Packages/meteor-simple-schema).
## 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:
- `prefixes`
A list of prefixes used by the application.
The package needs to know them in order to filter them before sending to schema or tabular or...
Default to an empty array.
- `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](https://guide.meteor.com/writing-atmosphere-packages.html#peer-npm-dependencies), 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.7.0:
```js
'lodash': '^4.17.0'
```
Each of these dependencies should be installed at application level:
```sh
meteor npm install --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](https://github.com/trychlos/pwix-field/issues).
---
P. Wieser
- Last updated on 2026, Apr. 2nd