Merge pull request #2 from netlify/Persistence

Entry content & media files persistence

architecture.md

@@ -0,0 +1,51 @@
+# Technical Architecture
+
+Netlify CMS is a React Application, using Redux for state management with immutable data structures (immutable.js).
+
+## State shape / reducers
+**Auth:** Keeps track of the logged state and the current user.
+
+**Config:** Holds the environment configuration (backend type, available collections & fields).
+
+**Collections** List of available collections, its fields and metadata information.
+
+**Entries:** Entries for each field.
+
+**EntryDraft:** Reused for each entry that is edited or created. It holds the entry's temporary data util it's persisted on the backend.
+
+**Medias:** Keeps references to all media files uploaded by the user during the current session.
+
+## Selectors:
+Selectors are functions defined within reducers used to compute derived data from the Redux store. The available selectors are:
+
+**selectEntry:** Selects a single entry, given the collection and a slug.
+
+**selectEntries:** Selects all entries for a given collection.
+
+**getMedia:** Selects a single MediaProxy object for the given URI:
+
+## Value Objects:
+**MediaProxy:** MediaProxy is a Value Object that holds information regarding a media file (such as an image, for example), whether it's persisted online or hold locally in cache.
+
+For files persisted online, the MediaProxy only keeps information about it's URI. For local files, the MediaProxy will keep a reference to the actual File object while generating the expected final URIs and on-demand blobs for local preview.
+
+The MediaProxy object can be used directly inside a media tag (such as `<img>`), as it will always return something that can be used by the media tag to render correctly (either the URI for the online file or a single-use blob).
+
+## Components structure and Workflows
+Components are separated into two main categories: Container components and presentational components.
+
+
+### Entry Editing:
+For either updating an existing entry or creating a new one, the `EntryEditor` is used and the flow is the same:
+- When mounted, the `EntryPage` container component dispatches the `createDraft` action, setting the `entryDraft` state to a blank state (in case of a new entry) or to a copy of the selected entry (in case of an edit).
+- The `EntryPage` will also render widgets for each field type in the given entry.
+- Widgets are used for editing entry fields. There are different widgets for different field types, and they are always defined in a pair containing a `control` and a `preview` components. The control component is responsible for presenting the user with the appropriate interface for manipulating the current field value, while the preview component is responsible for displaying value with the appropriate styling.
+
+#### Widget components implementation:
+The control component receives 3 callbacks as props: onChange, onAddMedia & onRemoveMedia.
+  - onChange (Required): Should be called when the users changes the current value. It will ultimately end up updating the EntryDraft object in the Redux Store, thus updating the preview component.
+  - onAddMedia & onRemoveMedia (optionals): If the field accepts file uploads for media (images, for example), these callbacks should be invoked with a `MediaProxy` value object. `onAddMedia` will get the current media stored in the Redux state tree while `onRemoveMedia` will remove it. MediaProxy objects are stored in the `Medias` object and referenced in the `EntryDraft` object on the state tree.
+
+Both control and preview widgets receive a `getMedia` selector via props. Displaying the media (or its uri) for the user should always be done via `getMedia`, as it returns a MediaProxy that can return the correct value for both medias already persisted on server and cached media not yet uploaded.
+
+The actual persistence of the content and medias inserted into the control component are delegated to the backend implementation. The backend will be called with the updated values and a a list of mediaProxy objects for each field of the entry, and should return a promise that can resolve into the persisted entry object and the list of the persisted media URIs.

src/actions/config.js

@@ -1,6 +1,7 @@
 import yaml from 'js-yaml';
 import { currentBackend } from '../backends/backend';
 import { authenticate } from '../actions/auth';
+import * as MediaProxy from '../valueObjects/MediaProxy';
 
 export const CONFIG_REQUEST = 'CONFIG_REQUEST';
 export const CONFIG_SUCCESS = 'CONFIG_SUCCESS';
@@ -27,9 +28,17 @@ export function configFailed(err) {
   };
 }
 
+export function configDidLoad(config) {
+  return (dispatch) => {
+    MediaProxy.setConfig(config);
+    dispatch(configLoaded(config));
+  };
+}
+
+
 export function loadConfig(config) {
   if (window.CMS_CONFIG) {
-    return configLoaded(window.CMS_CONFIG);
+    return configDidLoad(window.CMS_CONFIG);
   }
   return (dispatch, getState) => {
     dispatch(configLoading());
@@ -40,7 +49,7 @@ export function loadConfig(config) {
       }
 
       response.text().then(parseConfig).then((config) => {
-        dispatch(configLoaded(config));
+        dispatch(configDidLoad(config));
         const backend = currentBackend(config);
         const user = backend && backend.currentUser();
         user && dispatch(authenticate(user));

src/actions/entries.js

@@ -1,5 +1,8 @@
 import { currentBackend } from '../backends/backend';
 
+/*
+ * Contant Declarations
+ */
 export const ENTRY_REQUEST = 'ENTRY_REQUEST';
 export const ENTRY_SUCCESS = 'ENTRY_SUCCESS';
 export const ENTRY_FAILURE = 'ENTRY_FAILURE';
@@ -8,7 +11,20 @@ export const ENTRIES_REQUEST = 'ENTRIES_REQUEST';
 export const ENTRIES_SUCCESS = 'ENTRIES_SUCCESS';
 export const ENTRIES_FAILURE = 'ENTRIES_FAILURE';
 
-export function entryLoading(collection, slug) {
+export const DRAFT_CREATE = 'DRAFT_CREATE';
+export const DRAFT_DISCARD = 'DRAFT_DISCARD';
+export const DRAFT_CHANGE = 'DRAFT_CHANGE';
+
+
+export const ENTRY_PERSIST_REQUEST = 'ENTRY_PERSIST_REQUEST';
+export const ENTRY_PERSIST_SUCCESS = 'ENTRY_PERSIST_SUCCESS';
+export const ENTRY_PERSIST_FAILURE = 'ENTRY_PERSIST_FAILURE';
+
+
+/*
+ * Simple Action Creators (Internal)
+ */
+function entryLoading(collection, slug) {
   return {
     type: ENTRY_REQUEST,
     payload: {
@@ -18,7 +34,7 @@ export function entryLoading(collection, slug) {
   };
 }
 
-export function entryLoaded(collection, entry) {
+function entryLoaded(collection, entry) {
   return {
     type: ENTRY_SUCCESS,
     payload: {
@@ -28,7 +44,16 @@ export function entryLoaded(collection, entry) {
   };
 }
 
-export function entriesLoaded(collection, entries, pagination) {
+function entriesLoading(collection) {
+  return {
+    type: ENTRIES_REQUEST,
+    payload: {
+      collection: collection.get('name')
+    }
+  };
+}
+
+function entriesLoaded(collection, entries, pagination) {
   return {
     type: ENTRIES_SUCCESS,
     payload: {
@@ -39,24 +64,69 @@ export function entriesLoaded(collection, entries, pagination) {
   };
 }
 
-export function entriesLoading(collection) {
+function entriesFailed(collection, error) {
   return {
-    type: ENTRIES_REQUEST,
+    type: ENTRIES_FAILURE,
+    error: 'Failed to load entries',
+    payload: error.toString(),
+    meta: {collection: collection.get('name')}
+  };
+}
+
+function entryPersisting(collection, entry) {
+  return {
+    type: ENTRY_PERSIST_REQUEST,
     payload: {
-      collection: collection.get('name')
+      collection: collection,
+      entry: entry
+    }
+  };
+}
+
+function entryPersisted(persistedEntry, persistedMediaFiles) {
+  return {
+    type: ENTRY_PERSIST_SUCCESS,
+    payload: {
+      persistedEntry: persistedEntry,
+      persistedMediaFiles: persistedMediaFiles
     }
   };
 }
 
-export function entriesFailed(collection, error) {
+function entryPersistFail(collection, entry, error) {
   return {
     type: ENTRIES_FAILURE,
-    error: 'Failed to load entries',
-    payload: error.toString(),
-    meta: {collection: collection.get('name')}
+    error: 'Failed to persist entry',
+    payload: error.toString()
   };
 }
 
+/*
+ * Exported simple Action Creators
+ */
+export function createDraft(entry) {
+  return {
+    type: DRAFT_CREATE,
+    payload: entry
+  };
+}
+
+export function discardDraft() {
+  return {
+    type: DRAFT_DISCARD
+  };
+}
+
+export function changeDraft(entry) {
+  return {
+    type: DRAFT_CHANGE,
+    payload: entry
+  };
+}
+
+/*
+ * Exported Thunk Action Creators
+ */
 export function loadEntry(collection, slug) {
   return (dispatch, getState) => {
     const state = getState();
@@ -75,7 +145,23 @@ export function loadEntries(collection) {
     const backend = currentBackend(state.config);
 
     dispatch(entriesLoading(collection));
-    backend.entries(collection)
-      .then((response) => dispatch(entriesLoaded(collection, response.entries, response.pagination)))
+    backend.entries(collection).then(
+      (response) => dispatch(entriesLoaded(collection, response.entries, response.pagination)),
+      (error) => dispatch(entriesFailed(collection, error))
+    );
+  };
+}
+
+export function persist(collection, entry, mediaFiles) {
+  return (dispatch, getState) => {
+    const state = getState();
+    const backend = currentBackend(state.config);
+    dispatch(entryPersisting(collection, entry));
+    backend.persist(collection, entry, mediaFiles).then(
+      ({persistedEntry, persistedMediaFiles}) => {
+        dispatch(entryPersisted(persistedEntry, persistedMediaFiles));
+      },
+      (error) => dispatch(entryPersistFail(collection, entry, error))
+    );
   };
 }

src/actions/media.js

@@ -0,0 +1,10 @@
+export const ADD_MEDIA = 'ADD_MEDIA';
+export const REMOVE_MEDIA = 'REMOVE_MEDIA';
+
+export function addMedia(mediaProxy) {
+  return {type: ADD_MEDIA, payload: mediaProxy};
+}
+
+export function removeMedia(uri) {
+  return {type: REMOVE_MEDIA, payload: uri};
+}

src/backends/backend.js

@@ -66,6 +66,26 @@ class Backend {
       return entry;
     };
   }
+
+  persist(collection, entryDraft) {
+    const entryData = entryDraft.getIn(['entry', 'data']).toObject();
+    const entryObj = {
+      path: entryDraft.getIn(['entry', 'path']),
+      slug: entryDraft.getIn(['entry', 'slug']),
+      raw: this.entryToRaw(collection, entryData)
+    };
+    return this.implementation.persist(collection, entryObj, entryDraft.get('mediaFiles').toJS()).then(
+      (response) => ({
+        persistedEntry: this.entryWithFormat(collection)(response.persistedEntry),
+        persistedMediaFiles:response.persistedMediaFiles
+      })
+    );
+  }
+
+  entryToRaw(collection, entry) {
+    const format = resolveFormat(collection, entry);
+    return format && format.toFile(entry);
+  }
 }
 
 export function resolveBackend(config) {

src/backends/test-repo/implementation.js

@@ -47,4 +47,11 @@ export default class TestRepo {
       response.entries.filter((entry) => entry.slug === slug)[0]
     ));
   }
+
+  persist(collection, entry, mediaFiles = []) {
+    const folder = collection.get('folder');
+    const fileName = entry.path.substring(entry.path.lastIndexOf('/') + 1);
+    window.repoFiles[folder][fileName]['content'] = entry.raw;
+    return Promise.resolve({persistedEntry:entry, persistedMediaFiles:[]});
+  }
 }

src/components/ControlPane.js

@@ -3,13 +3,16 @@ import Widgets from './Widgets';
 
 export default class ControlPane extends React.Component {
   controlFor(field) {
-    const { entry } = this.props;
+    const { entry, getMedia, onChange, onAddMedia, onRemoveMedia } = this.props;
     const widget = Widgets[field.get('widget')] || Widgets._unknown;
     return React.createElement(widget.Control, {
       key: field.get('name'),
       field: field,
       value: entry.getIn(['data', field.get('name')]),
-      onChange: (value) => this.props.onChange(entry.setIn(['data', field.get('name')], value))
+      onChange: (value) => onChange(entry.setIn(['data', field.get('name')], value)),
+      onAddMedia: onAddMedia,
+      onRemoveMedia: onRemoveMedia,
+      getMedia: getMedia
     });
   }
 

src/components/EntryEditor.js

@@ -3,30 +3,28 @@ import ControlPane from './ControlPane';
 import PreviewPane from './PreviewPane';
 
 export default class EntryEditor extends React.Component {
-  constructor(props) {
-    super(props);
-    this.state = {entry: props.entry};
-    this.handleChange = this.handleChange.bind(this);
-  }
-
-  handleChange(entry) {
-    this.setState({entry: entry});
-  }
 
   render() {
-    const { collection, entry } = this.props;
-
+    const { collection, entry, getMedia, onChange, onAddMedia, onRemoveMedia, onPersist } = this.props;
     return <div>
       <h1>Entry in {collection.get('label')}</h1>
       <h2>{entry && entry.get('title')}</h2>
       <div className="cms-container" style={styles.container}>
         <div className="cms-control-pane" style={styles.pane}>
-          <ControlPane collection={collection} entry={this.state.entry} onChange={this.handleChange}/>
+          <ControlPane
+              collection={collection}
+              entry={entry}
+              getMedia={getMedia}
+              onChange={onChange}
+              onAddMedia={onAddMedia}
+              onRemoveMedia={onRemoveMedia}
+          />
         </div>
         <div className="cms-preview-pane" style={styles.pane}>
-          <PreviewPane collection={collection} entry={this.state.entry}/>
+          <PreviewPane collection={collection} entry={entry} getMedia={getMedia} />
         </div>
       </div>
+      <button onClick={onPersist}>Save</button>
     </div>;
   }
 }

src/components/PreviewPane.js

@@ -3,12 +3,13 @@ import Widgets from './Widgets';
 
 export default class PreviewPane extends React.Component {
   previewFor(field) {
-    const { entry } = this.props;
+    const { entry, getMedia } = this.props;
     const widget = Widgets[field.get('widget')] || Widgets._unknown;
     return React.createElement(widget.Preview, {
       key: field.get('name'),
       field: field,
-      value: entry.getIn(['data', field.get('name')])
+      value: entry.getIn(['data', field.get('name')]),
+      getMedia: getMedia,
     });
   }