search

insin / newforms-bootstrap

Components for rendering a newforms Form using Bootstrap 3
http://insin.github.io/newforms-bootstrap/grid.html
Other
48 stars 13 forks source link

readme

newforms-bootstrap

build status

Components for rendering a newforms Form using Bootstrap 3 CSS classes and conventions for layout.

Demos

Install

Node.js

newforms-bootstrap can be used on the server, or bundled for the client using an npm-compatible packaging system such as Browserify or webpack.

npm install newforms-bootstrap

By default, newforms-bootstrap will be in development mode. To use it in production mode, set the environment variable NODE_ENV to 'production' when bundling. To completely remove all development mode code, use a minifier that performs dead-code elimination, such as UglifyJS.

Browser bundle

The browser bundle exposes a global BootstrapForm variable and expects to find global React (React) and forms (newforms) variables to work with.

The uncompressed bundle is in development mode, so will log warnings about potential mistakes.

You can find it in the /dist directory.

Usage

Basic Form

Pass BootstrapForm a Form instance as a form prop.

Any component which accepts a form prop can be used as a custom renderer for newforms' RenderForm component, which can also handle creation of a form instance for you:

var forms = require('newforms')
var BootstrapForm = require('newforms-bootstrap')

var SignupForm = forms.Form.extend({
  username: forms.CharField({maxLength: 20}),
  // ...
})

var Signup = React.createClass({
  _onSubmit() {
    var form = this.refs.signupForm.getForm()
    if (form.validate()) {
      // ...
    }
  },

  render() {
    return <form onSubmit={this._onSubmit}>
      <forms.RenderForm form={SignupForm} ref="signupForm">
        <BootstrapForm/>
      </forms.RenderForm>
      <button>Sign Up</button>
    </form>
  }
})

Grid Form

To render a form as a Bootstrap grid, you can use the provided grid components:

var {Col, Container, Row, Field} = BootstrapForm
<forms.RenderForm form={ProductForm} ref="productForm">
  <Container>
    <Row>
      <Field name="productName" md="8"/>
      <Field name="tags" md="4"/>
    </Row>
    <Row>
      <Field name="vendor" md="6"/>
      <Field name="productType" md="6"/>
    </Row>
    <Row>
      <Field name="productDescription" md="12"/>
    </Row>
    <Row>
      <Col md="2">
        I'm just a regular column.
      </Col>
      <Field name="sku" md="2"/>
      <Field name="initialStockLevel" md="2"/>
      <Field name="costPrice" md="2"/>
      <Field name="wholesalePrice" md="2"/>
      <Field name="retailPrice" md="2"/>
    </Row>
  </Container>
</forms.RenderForm>

To automatically split the 12 available Bootstrap grid units among columns, pass an autoColumns prop to a Container or Row component. For example, the following rows would render identically:

<Row>
  <Field name="vendor" md="6"/>
  <Field name="productType" md="6"/>
</Row>

<Row autoColumns="md">
  <Field name="vendor"/>
  <Field name="productType"/>
</Row>

This takes into account any column widths and offsets which have been provided for the specified size unit, so this grid layout would render identically to the first grid layout example above:

<forms.RenderForm form={ProductForm} ref="productForm">
  <Container autoColumns="md">
    <Row>
      <Field name="productName" md="8"/>
      <Field name="tags"/>
    </Row>
    <Row>
      <Field name="vendor"/>
      <Field name="productType"/>
    </Row>
    <Row>
      <Field name="productDescription"/>
    </Row>
    <Row>
      <Col>
        I'm just a regular column.
      </Col>
      <Field name="sku"/>
      <Field name="initialStockLevel"/>
      <Field name="costPrice"/>
      <Field name="wholesalePrice"/>
      <Field name="retailPrice"/>
    </Row>
  </Container>
</forms.RenderForm>

API

BootstrapForm props

Bootstrap-compatible choice field renderers

The following custom renderers are available for use. Note that the non-inline renderers will be automatically applied for you if you're using certain combinations of default fields and widgets.

Use the inline renderers manually if you want to configure fields to render inline checkbox or radio inputs using Bootstrap 3's checkbox-inline and radio-inline classes, respectively:

var StuffForm = forms.Form.extend({
  stuff: forms.MultipleChoiceField({
    choices: [1, 2, 3, 4, 5],
    widget: forms.CheckboxSelectMultiple({renderer: BootstrapForm.CheckboxInlineRenderer})
  })
})

Grid Components

Container

Renders a .container or .container-fluid.

Container props

Row

Renders a .row.

These should be nested directly under Container components.

Row props

Field

Renders a column containing a named form field.

These should be nested directly under Row components.

Field props

Field is a specialisation of Col, so it accepts all the sizing/offset props described below plus the following:

Col

Renders a column, with contents manually provided as its children.

Note that Field components generates their own column container, you do not need to and should not wrap a Field with a Col

Col props

Column sizing props can be passed as a String or Number.

At least one of the following sizing props must be give to define the column's width:

Additionally, the column's offset can be specified with the following props:

Field / Widget Patching

BootstrapForm and Container will automatically patch the widgets of certain fields for Bootstrap-compatible output.

These changes will be made the first time they renders a form - patching will only affect the form instance it was given.

ChoiceField with RadioSelect

If the widget is using the default renderer, it will be replaced with BootstrapForm.RadioRenderer.

MultipleChoiceField with CheckboxSelectMultiple

If the widget is using the default renderer, it will be replaced with BootstrapForm.CheckboxRenderer.

MultiValueField

If the field has fewer than 5 sub-fields and its widget is using the default implementation of MultiWidget.prototype.formatOutput(), the widget will be given a Bootstrap-specific version of formatOutput() which wraps the rendered widgets as equally-distributed columns in a Bootstrap grid row.

TODO

MIT Licensed