Merge pull request #745 from marmelab/next

Prepare 1.2.0

Author: fzaninotto

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## v1.2.0
+
+* Add ability to override redirect behavior on save for `<Create>` and `<Edit>` views ([wesley6j](https://github.com/wesley6j))
+* Add refresh button to `<Show>` view ([djhi](https://github.com/djhi))
+* Add asterisk to label on required `Input` ([djhi](https://github.com/djhi))
+* Add `<FileInput>` ([djhi](https://github.com/djhi))
+* Add sort feature to `<ReferenceManyField>` ([wesley6j](https://github.com/wesley6j))
+* Add ability to use custom history in `<Admin>` ([fzaninotto](https://github.com/fzaninotto))
+* Add `<TabbedShowLayout>` to mirror `<TabbedForm>` ([remi13131](https://github.com/remi13131))
+* Add `options` prop to `<BooleanInput>` and pass them to mui `<Toggle>` ([djhi](https://github.com/djhi))
+* Add `AOR/` prefix to Redux actions ([ThieryMichel](https://github.com/ThieryMichel))
+* Add deep path support for `optionText` and `optionValue` props the `Input` components used as `Reference` children ([mtakayuki](https://github.com/mtakayuki))
+* Add ability to override `<SimpleShowLayout>` container styles ([djhi](https://github.com/djhi))
+* Add `<MenuItemLink>` to fix bad click handling of menu on mobile ([djhi](https://github.com/djhi))
+* Add `aor-firebase-client` to the list of REST clients ([sidferreira](https://github.com/sidferreira))
+* Update redux-saga to 0.15.3 ([dervos](https://github.com/dervos))
+* Fix filter in `<ReferenceInput>` not taken into account when `<AutocompleteInput>` is filled ([djhi](https://github.com/djhi))
+* Fix `<ReferenceArrayField>` when ids is null ([wesley6j](https://github.com/wesley6j))
+* Fix missing translation helper in `<Show>` view ([djhi](https://github.com/djhi))
+* Fix code highlighting on REAMDE ([diegohaz](https://github.com/diegohaz))
+* Fix custom REST client list format for better readability ([fzaninotto](https://github.com/fzaninotto))
+
 ## v1.1.2
 
 * Fix a typo in tutorial ([calebhaye](https://github.com/calebhaye))

docs/Actions.md

@@ -234,10 +234,10 @@ function* commentApproveFailure({ error }) {
 }
 
 export default function* commentSaga() {
-    yield [
+    yield all([
         takeEvery('COMMENT_APPROVE_SUCCESS', commentApproveSuccess),
         takeEvery('COMMENT_APPROVE_FAILURE', commentApproveFailure),
-    ];
+    ]);
 }
 ```
 

docs/Admin.md

@@ -118,19 +118,20 @@ If you want to add or remove menu items, for instance to link to non-resources p
 ```jsx
 // in src/Menu.js
 import React from 'react';
-import MenuItem from 'material-ui/MenuItem';
-import { Link } from 'react-router-dom';
+import { MenuItemLink } from 'admin-on-rest';
 
 export default ({ resources, onMenuTap, logout }) => (
     <div>
-        <MenuItem containerElement={<Link to="/posts" />} primaryText="Posts" onTouchTap={onMenuTap} />
-        <MenuItem containerElement={<Link to="/comments" />} primaryText="Comments" onTouchTap={onMenuTap} />
-        <MenuItem containerElement={<Link to="/custom-route" />} primaryText="Miscellaneous" onTouchTap={onMenuTap} />
+        <MenuItemLink to="/posts" primaryText="Posts" onTouchTap={onMenuTap} />
+        <MenuItemLink to="/comments" primaryText="Comments" onTouchTap={onMenuTap} />
+        <MenuItemLink to="/custom-route" primaryText="Miscellaneous" onTouchTap={onMenuTap} />
         {logout}
     </div>
 );
 ```
 
+**Tip**: Note the `MenuItemLink` component. It must be used to avoid unwanted side effects in mobile views.
+
 Then, pass it to the `<Admin>` component as the `menu` prop:
 
 ```jsx

docs/CreateEdit.md

@@ -157,6 +157,9 @@ Here are all the props accepted by the `<SimpleForm>` component:
 
 * [`defautValue`](#default-values)
 * [`validation`](#validation)
+* [`submitOnEnter`](#submit-on-enter)
+* [`redirect`](#redirection-after-submission)
+* [`toolbar`](#toolbar)
 
 ```jsx
 export const PostCreate = (props) => (
@@ -183,6 +186,9 @@ Here are all the props accepted by the `<TabbedForm>` component:
 
 * [`defautValue`](#default-values)
 * [`validation`](#validation)
+* [`submitOnEnter`](#submit-on-enter)
+* [`redirect`](#redirection-after-submission)
+* [`toolbar`](#toolbar)
 
 {% raw %}
 ```jsx
@@ -336,7 +342,7 @@ Input validation functions receive the current field value, and the values of al
 **Tip**: Validator functions receive the form `props` as third parameter, including the `translate` function. This lets you build internationalized validators:
 
 ```jsx
-const required = (value, _, props) => value ? undefined : props.translate('myroot.validation.required');
+const required = (value, allValues, props) => value ? undefined : props.translate('myroot.validation.required');
 ```
 
 **Tip**: The props of your Input components are passed to a redux-form `<Field>` component. So in addition to `validate`, you can also use `warn`.
@@ -348,13 +354,13 @@ const required = (value, _, props) => value ? undefined : props.translate('myroo
 Admin-on-rest already bundles a few validator functions, that you can just require and use as field validators:
 
 * `required` if the field is mandatory,
-* `minValue` to specify a minimum value for integers,
-* `maxValue` to specify a maximum value for integers,
-* `minLength` to specify a minimum length for strings,
-* `maxLength` to specify a maximum length for strings,
+* `minValue(min, message)` to specify a minimum value for integers,
+* `maxValue(max, message)` to specify a maximum value for integers,
+* `minLength(min, message)` to specify a minimum length for strings,
+* `maxLength(max, message)` to specify a maximum length for strings,
 * `email` to check that the input is a valid email address,
-* `regex` to validate that the input matches a regex,
-* `choices` to validate that the input is within a given list,
+* `regex(pattern, message)` to validate that the input matches a regex,
+* `choices(list, message)` to validate that the input is within a given list,
 
 Example usage:
 
@@ -376,3 +382,72 @@ export const UserCreate = (props) => (
     </Create>
 );
 ```
+
+## Submit On Enter
+
+By default, pressing `ENTER` in any of the form fields submits the form - this is the expected behavior in most cases. However, some of your custom input components (e.g. Google Maps widget) may have special handlers for the `ENTER` key. In that case, to disable the automated form submission on enter, set the `submitOnEnter` prop of the form component to `false`:
+
+```jsx
+export const PostEdit = (props) => (
+    <Edit {...props}>
+        <SimpleForm submitOnEnter={false}>
+            ...
+        </SimpleForm>
+    </Edit>
+);
+```
+
+## Redirection After Submission
+
+By default:
+
+- Submitting the form in the `<Create>` view redirects to the `<Edit>` view
+- Submitting the form in the `<Edit>` view redirects to the `<List>` view
+
+You can customize the redirection by setting the `redirect` prop of the form component. Possible values are "edit", "show", "list", and `false` to disable redirection. For instance, to redirect to the `<Show>` view after edition:
+
+```jsx
+export const PostEdit = (props) => (
+    <Edit {...props}>
+        <SimpleForm redirect="show">
+            ...
+        </SimpleForm>
+    </Edit>
+);
+```
+
+This affects both the submit button, and the form submission when the user presses `ENTER` in one of the form fields.
+
+## Toolbar
+
+At the bottom of the form, the toolbar displays the submit button. You can override this component by setting the `toolbar` prop, to display the buttons of your choice.
+
+The most common use case is to display two submit buttons in the `<Create>` view:
+
+- one that creates and redirects to the `<Show>` view of the new resource, and
+- one that redirects to a blank `<Create>` view after creation (allowing bulk creation)
+
+![Form toolbar](./img/form-toolbar.png)
+
+For that use case, use the `<SaveButton>` component with a custom `redirect` prop:
+
+```jsx
+impot { SaveButton, Toolbar } from 'admin-on-rest';
+
+const PostCreateToolbar = props => <Toolbar {...props} >
+    <SaveButton label="post.action.save_and_show" redirect="show" submitOnEnter={true} />
+    <SaveButton label="post.action.save_and_add" redirect={false} submitOnEnter={false} raised={false} />
+</Toolbar>;
+
+export const PostEdit = (props) => (
+    <Edit {...props}>
+        <SimpleForm toolbar={<PostCreateToolbar />} redirect="show">
+            ...
+        </SimpleForm>
+    </Edit>
+);
+```
+
+**Tip**: Use admin-on-rest's `<Toolbar>` component instead of material-ui's `<Toolbar>` component. The former builds up on the latter, and adds support for an alternative mobile layout (and is therefore responsive).
+
+**Tip**: Don't forget to also set the `redirect` prop of the Form component to handle submission by the `ENTER` key.

docs/Fields.md

@@ -184,6 +184,61 @@ The optional `title` prop points to the picture title property, used for both `a
 
 If passed value is an existing path within your JSON object, then it uses the object attribute. Otherwise, it considers its value as an hard-written title.
 
+
+If the record actually contains an array of images in its property defined by the `source` prop, the `src` prop will be needed to determine the `src` value of the images, for example:
+
+```js
+// This is the record
+{
+    pictures: [
+        { url: 'image1.jpg', desc: 'First image' },
+        { url: 'image2.jpg', desc: 'Second image' },
+    ],
+}
+
+<ImageField source="pictures" src="url" title="desc" />
+```
+
+## `<FileField>`
+
+If you need to display a file provided by your API, you can use the `<FileField />` component:
+
+```jsx
+import { FileField } from 'admin-on-rest';
+
+<FileField source="url" title="title" />
+```
+
+This field is also generally used within an [<FileInput />](http://marmelab.com/admin-on-rest/Inputs.html#fileinput) component to display preview.
+
+The optional `title` prop points to the file title property, used for `title` attributes. It can either be an hard-written string, or a path within your JSON object:
+
+```jsx
+// { file: { url: 'doc.pdf', title: 'Presentation' } }
+
+// Title would be "file.title", hence "Presentation"
+<FileField source="file.url" title="file.title" />
+
+// Title would be "File", as "File" is not a path in previous given object
+<FileField source="file.url" title="File" />
+```
+
+If passed value is an existing path within your JSON object, then it uses the object attribute. Otherwise, it considers its value as an hard-written title.
+
+If the record actually contains an array of files in its property defined by the `source` prop, the `src` prop will be needed to determine the `href` value of the links, for example:
+
+```js
+// This is the record
+{
+    files: [
+        { url: 'image1.jpg', desc: 'First image' },
+        { url: 'image2.jpg', desc: 'Second image' },
+    ],
+}
+
+<FileField source="files" src="url" title="desc" />
+```
+
 ## `<NumberField>`
 
 Displays a number formatted according to the browser locale, right aligned.

docs/Inputs.md

@@ -166,6 +166,18 @@ import { BooleanInput } from 'admin-on-rest';
 
 This input does not handle `null` values. You would need the `<NullableBooleanInput />` component if you have to handle non-set booleans.
 
+You can use the `options` prop to pass any option supported by the Material UI `Toggle` components.
+
+{% raw %}
+```jsx
+<BooleanInput source="finished" options={{
+    labelPosition: 'right'
+}} />
+```
+{% endraw %}
+
+Refer to [Material UI Toggle documentation](http://www.material-ui.com/#/components/toggle) for more details.
+
 `<NullableBooleanInput />` renders as a dropdown list, allowing to choose between true, false, and null values.
 
 ```jsx
@@ -345,9 +357,13 @@ Previews are enabled using `<ImageInput>` children, as following:
 </ImageInput>
 ```
 
-This component accepts all [react-dropzone properties](https://github.com/okonet/react-dropzone#features), in addition to those of admin-on-rest. For instance, if you need to upload several images at once, just add the `multiple` DropZone attribute to your `<ImageInput />` field.
+Writing a custom field component for displaying the current value(s) is easy:  it's a standard [field](./Fields.html#writing_your_own_field_component).
+
+When receiving **new** files, `ImageInput` will add a `rawFile` property to the object passed as the `record` prop of children. This `rawFile` is the [File](https://developer.mozilla.org/en-US/docs/Web/API/File) instance of the newly added file. This can be useful to display informations about size or mimetype inside a custom field.
+
+The `ImageInput` component accepts all [react-dropzone properties](https://github.com/okonet/react-dropzone#features), in addition to those of admin-on-rest. For instance, if you need to upload several images at once, just add the `multiple` DropZone attribute to your `<ImageInput />` field.
 
-If the default Dropzone label don't fit with your need, you can pass a `placeholder` attribute to overwrite it. The attribute can be anything React can render (`PropTypes.node`):
+If the default Dropzone label doesn't fit with your need, you can pass a `placeholder` attribute to overwrite it. The attribute can be anything React can render (`PropTypes.node`):
 
 ```jsx
 <ImageInput source="pictures" label="Related pictures" accept="image/*" placeholder={<p>Drop your file here</p>}>
@@ -357,6 +373,36 @@ If the default Dropzone label don't fit with your need, you can pass a `placehol
 
 Note that the image upload returns a [File](https://developer.mozilla.org/en/docs/Web/API/File) object. It is your responsibility to handle it depending on your API behavior. You can for instance encode it in base64, or send it as a multi-part form data. Check [this example](./RestClients.html#decorating-your-rest-client-example-of-file-upload) for base64 encoding data by extending the REST Client.
 
+## `<FileInput>`
+
+`<FileInput>` allows to upload some files using [react-dropzone](https://github.com/okonet/react-dropzone).
+
+![FileInput](./img/file-input.png)
+
+Previews (actually a simple list of files names) are enabled using `<FileInput>` children, as following:
+
+```jsx
+<FileInput source="files" label="Related files" accept="application/pdf">
+    <FileField source="src" title="title" />
+</FileInput>
+```
+
+Writing a custom field component for displaying the current value(s) is easy:  it's a standard [field](./Fields.html#writing_your_own_field_component).
+
+When receiving **new** files, `FileInput` will add a `rawFile` property to the object passed as the `record` prop of children. This `rawFile` is the [File](https://developer.mozilla.org/en-US/docs/Web/API/File) instance of the newly added file. This can be useful to display informations about size or mimetype inside a custom field.
+
+The `FileInput` component accepts all [react-dropzone properties](https://github.com/okonet/react-dropzone#features), in addition to those of admin-on-rest. For instance, if you need to upload several files at once, just add the `multiple` DropZone attribute to your `<FileInput />` field.
+
+If the default Dropzone label doesn't fit with your need, you can pass a `placeholder` attribute to overwrite it. The attribute can be anything React can render (`PropTypes.node`):
+
+```jsx
+<FileInput source="files" label="Related files" accept="application/pdf" placeholder={<p>Drop your file here</p>}>
+    <ImageField source="src" title="title" />
+</FileInput>
+```
+
+Note that the file upload returns a [File](https://developer.mozilla.org/en/docs/Web/API/File) object. It is your responsibility to handle it depending on your API behavior. You can for instance encode it in base64, or send it as a multi-part form data. Check [this example](./RestClients.html#decorating-your-rest-client-example-of-file-upload) for base64 encoding data by extending the REST Client.
+
 ## `<LongTextInput>`
 
 `<LongTextInput>` is the best choice for multiline text values. It renders as an auto expandable textarea.

docs/Reference.md

@@ -35,6 +35,8 @@ title: "Reference"
 * `<EditActions>`
 * `<EditButton>`
 * [`<EmailField>`](./Fields.html#emailfield)
+* [`<FileField>`](./Fields.html#filefield)
+* [`<FileInput>`](./Inputs.html#fileinput)
 * [`<Filter>`](./List.html#filters)
 * `<FilterButton>`
 * `<FilterForm>`
@@ -82,7 +84,9 @@ title: "Reference"
 * [`<SimpleList>`](./List.html#the-simplelist-component)
 * [`<SimpleShowLayout>`](./Show.html#the-simpleshowlayout-component)
 * [`<SingleFieldList>`](./List.html#the-singlefieldlist-component)
+* `<Tab>`
 * [`<TabbedForm>`](./CreateEdit.html#the-tabbedform-component)
+* `<TabbedShowLayout>`
 * [`<TextField>`](./Fields.html#textfield)
 * [`<TextInput>`](./Inputs.html#textinput)
 * `<Title>`

docs/Show.md

@@ -135,3 +135,26 @@ export const PostShow = (props) => (
     </Show>
 );
 ```
+
+It is possible to override its style by specifying the `style` prop, for example:
+
+```jsx
+const styles = {
+    container: {
+        display: 'flex',
+    },
+    item: {
+        marginRight: '1rem',
+    },
+};
+
+export const PostShow = (props) => (
+    <Show {...props}>
+        <SimpleShowLayout style={styles.container}>
+            <TextField source="title" style={styles.item} />
+            <RichTextField source="body" style={styles.item} />
+            <NumberField source="nb_views" style={styles.item} />
+        </SimpleShowLayout>
+    </Show>
+);
+```