apostrophe-forms
Build forms for ApostropheCMS in a simple user interface.
Last updated 15 days ago by alexbea .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install apostrophe-forms 
SYNC missed versions from official npm registry.

Apostrophe Forms

npm i apostrophe-forms

Configuration

Enable the modules in your app.js file as with other modules:

// in app.js
modules: {
  // ...,
  'apostrophe-forms': {},
  'apostrophe-forms-widgets': {},
  // Enable only the field widgets that your application needs to make it
  // easier for application/website managers.
  'apostrophe-forms-text-field-widgets': {},
  'apostrophe-forms-textarea-field-widgets': {},
  'apostrophe-forms-file-field-widgets': {},
  'apostrophe-forms-select-field-widgets': {},
  'apostrophe-forms-radio-field-widgets': {},
  'apostrophe-forms-checkboxes-field-widgets': {},
  'apostrophe-forms-boolean-field-widgets': {},
  'apostrophe-forms-conditional-widgets': {},
  // END of field widgets
  'apostrophe-email': {
    // See the email tutorial for required configuration.
    // https://docs.apostrophecms.org/apostrophe/tutorials/howtos/email
  },
  'apostrophe-permissions': {
    construct: function(self, options) {
      // Required if you want file fields to work on public pages.
      self.addPublic([ 'edit-attachment' ]);
    }
  }
}

In the page, widget, or other template, add only the main widget module to the configuration in an area or singleton.

Example:

  {{ apos.area(data.page, 'body', {
    widgets: {
      'apostrophe-forms': {}
    }
  }) }}

Submissions

By default, submissions are saved to a new MongoDB collection, aposFormSubmissions. If you do not want submissions saved to this collection, add the saveSubmissions: false option to the apostrophe-forms module.

Form submission triggers a 'submission' event that you can listen for and handle in an additional method if you choose. The callback for that event is provided the arguments, req, form (the form object), output (the submission output).

The module also emits browser events on submission (apostrophe-forms:submission-form) and submission failure (apostrophe-forms:submission-failed). Both events are attached to the document body element.

Email

If apostrophe-email is configured, submissions can be sent to multiple email addresses as well. In the "After-Submission" tab, enter a comma-separated list of email addresses to the "Email Address(es) for Results" field. If not using this feature, set the emailSubmissions: false on the apostrophe-forms module to hide the related field on forms.

Styling

Starter styles for user-facing forms are included in a forms.less file. These offer some spacing as well as styling for error states. If you do not want to use these, pass the disableBaseStyles: true option to apostrophe-forms-widgets. This file can also be used to identify the error state classes that you should style in your project.

'apostrophe-forms-widgets': {
  disableBaseStyles: true
},

Need more control over your styling? You can include your own class prefix that will be in included on most of the labels, inputs, and message/error elements within the forms. The class that is created uses the BEM convention. You add the prefix you want in the apostrophe-forms configuration.

'apostrophe-forms': {
  classPrefix: 'my-form'
}

This results in a class like my-form__input being added to input elements in the form, for example.

Using reCAPTCHA for user validation

Google's reCAPTCHA is built in as an option. You will first need to set up a reCAPTCHA site up on their website using the version two option. Make sure your domains are configured (using "localhost" for local development) and make note of the site key and secret key. Those should be added as options to apostrophe-forms:

// in app.js
modules: {
  // ...,
  'apostrophe-forms': {
    recaptchaSecret: 'YOUR SECRET KEY',
    recaptchaSite: 'YOUR SITE KEY'
  },
  // ...,

To make these options configurable by end-users, you can use apostrophe-override-options to make global fields set these for you. This would look something like:

// in app.js
modules: {
  'apostrophe-override-options': {},
// in lib/modules/apostrophe-global/index.js
module.exports = {
  addFields: [
    {
      name: 'recaptchaSecret',
      label: 'reCAPTCHA Secret',
      type: 'string'
    },
    {
      name: 'recaptchaSite',
      label: 'reCAPTCHA Site',
      type: 'string'
    }
  ],
  overrideOptions: {
    editable: {
      'apos.apostrophe-forms.recaptchaSite': 'recaptchaSite',
      'apos.apostrophe-forms.recaptchaSecret': 'recaptchaSecret'
    }
  }
};

The reCAPTCHA field will then be present on all fields. There is an open issue to improve this to allow form-level disabling.

Adding project-level form widgets

The form widget included here cover most basic form needs, but you may want to include others, such as structural widgets to create columns within your form.

To override the widgets available in a form, set the formWidgets option on apostrophe-forms to an object enabling the widgets as you would in any area options. You will need to include the form field widgets here (allowing you to exclude some as well). See the full list in the index.js file in the contents schema object.

If you're looking to create a sub-widget that also contains all of the field widgets to do a multi-column treatment you will need to also pass the form field widgets in as options to an area or areas there as well.

Current Tags

  • 1.8.2                                ...           latest (15 days ago)
  • 0.5.23                                ...           ohdotfive (10 months ago)

41 Versions

  • 1.8.2                                ...           15 days ago
  • 1.8.1                                ...           a month ago
  • 1.8.0                                ...           2 months ago
  • 1.7.1                                ...           2 months ago
  • 1.7.0                                ...           3 months ago
  • 1.6.0                                ...           3 months ago
  • 1.5.1                                ...           4 months ago
  • 1.5.0                                ...           5 months ago
  • 1.4.2                                ...           5 months ago
  • 1.4.1                                ...           6 months ago
  • 1.4.0                                ...           7 months ago
  • 1.3.1                                ...           8 months ago
  • 1.3.0                                ...           9 months ago
  • 0.5.23                                ...           10 months ago
  • 1.2.1                                ...           10 months ago
  • 1.2.0                                ...           10 months ago
  • 1.1.0                                ...           a year ago
  • 1.0.1                                ...           a year ago
  • 1.0.0                                ...           a year ago
  • 0.5.22                                ...           4 years ago
  • 0.5.21                                ...           4 years ago
  • 0.5.20                                ...           4 years ago
  • 0.5.19                                ...           4 years ago
  • 0.5.18                                ...           5 years ago
  • 0.5.17                                ...           5 years ago
  • 0.5.16                                ...           5 years ago
  • 0.5.15                                ...           5 years ago
  • 0.5.14                                ...           5 years ago
  • 0.5.13                                ...           5 years ago
  • 0.5.12                                ...           5 years ago
  • 0.5.11                                ...           5 years ago
  • 0.5.10                                ...           5 years ago
  • 0.5.9                                ...           5 years ago
  • 0.5.8                                ...           5 years ago
  • 0.5.7                                ...           5 years ago
  • 0.5.5                                ...           5 years ago
  • 0.5.4                                ...           5 years ago
  • 0.5.3                                ...           5 years ago
  • 0.5.2                                ...           5 years ago
  • 0.5.1                                ...           5 years ago
  • 0.5.0                                ...           5 years ago
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 14
Dependencies (3)
Dev Dependencies (10)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |