pageflow 0.11.4 → 12.0.0.rc1

data/app/assets/javascripts/pageflow/editor/api.js

@@ -3,186 +3,226 @@
 
 /**
  * Interface for engines providing editor extensions.
+ * @alias pageflow.editor
+ * @memberof module:pageflow/editor
  */
-pageflow.EditorApi = pageflow.Object.extend({
-  initialize: function() {
+pageflow.EditorApi = pageflow.Object.extend(
+/** @lends module:pageflow/editor.pageflow.editor */{
+
+  initialize: function(options) {
+    this.router = options && options.router;
+
     this.sideBarRoutings = [];
     this.mainMenuItems = [];
     this.initializers = [];
     this.fileSelectionHandlers = {};
 
-    /**
-     *  Display Backbone/Marionette View inside the main panel
-     *  of the editor.
-     */
-    this.showViewInMainPanel = function(view) {
-      pageflow.app.mainRegion.show(view);
-    };
-
-    /**
-     *  Display the Pageflow-Preview inside the main panel.
-     */
-    this.showPreview = function() {
-      pageflow.app.mainRegion.$el.empty();
-    };
-
-    /**
-     * Register additional router and controller for sidebar.
-     *
-     * Supported options:
-     * - router: constructor function of Backbone Marionette app router
-     * - controller: constructor function of Backbone Marionette controller
-     */
-    this.registerSideBarRouting = function(options) {
-      this.sideBarRoutings.push(options);
-    };
-
-    /**
-     * Set the name of the help entry that shall be selected by
-     * default when the help view is opened. This value is
-     * automatically reset when navigation occurs.
-     */
-    this.setDefaultHelpEntry = function(name) {
-      this.nextDefaultHelpEntry = name;
-    };
-
-    /** @api private */
-    this.applyDefaultHelpEntry = function(name) {
-      this.defaultHelpEntry = this.nextDefaultHelpEntry;
-      this.nextDefaultHelpEntry = null;
-    };
-
-    /**
-     * Register additional menu item to be displayed on the root sidebar
-     * view.
-     *
-     * Supported options:
-     * - translationKey: for the label
-     * - path: route to link to
-     * - click: click handler
-     */
-    this.registerMainMenuItem = function(options) {
-      this.mainMenuItems.push(options);
-    };
-
-    /**
-     * Register a custom initializer which will be run before the boot
-     * initializer of the editor.
-     */
-    this.addInitializer = function(fn) {
-      this.initializers.push(fn);
-    };
-
-    /**
-     * Navigate to the given path.
-     */
-    this.navigate = function(path, options) {
-      editor.navigate(path, options);
-    };
-
-    /**
-     * Extend the interface of page configuration objects. This is
-     * especially convenient to wrap structured data from the page
-     * configuration as Backbone objects.
-     *
-     * Example:
-     *
-     *     pageflow.editor.registerPageConfigurationMixin({
-     *       externalLinks: function() {
-     *         return new Backbone.Collection(this.get('external_links'));
-     *       }
-     *     }
-     *
-     *     pageflow.pages.get(1).configuration.externalLinks().each(...);
-     */
-    this.registerPageConfigurationMixin = function(mixin) {
-      Cocktail.mixin(pageflow.Configuration, mixin);
-    };
-
-    /**
-     * File selection handlers let editor extensions use the files view
-     * to select files for usage in their custom models.
-     *
-     * See selectFile method for details how to trigger file selection.
-     *
-     * Example:
-     *
-     *     function MyFileSelectionHandler(options) {
-     *       this.call = function(file) {
-     *         // invoked with the selected file
-     *       };
-     *
-     *       this.getReferer = function() {
-     *         // the path to return to when the back button is clicked
-     *         // or after file selection
-     *         return '/some/path';
-     *       }
-     *     }
-     *
-     *     pageflow.editor.registerFileSelectionHandler('my_file_selection_handler', MyFileSelectionHandler);
-     */
-    this.registerFileSelectionHandler = function(name, handler) {
-      this.fileSelectionHandlers[name] = handler;
-    };
-
-    /**
-     * Trigger selection of the given file type with the given
-     * handler. Payload hash is passed to selection handler as options.
-     *
-     * Example:
-     *
-     *     pageflow.editor.selectFile('image_files', 'my_file_selection_handler', {some: 'option for handler'});
-     */
-    this.selectFile = function(fileType, handlerName, payload) {
-      this.navigate('/files/' + fileType + '?handler=' + handlerName + '&payload=' + encodeURIComponent(JSON.stringify(payload)), {trigger: true});
-    };
-
-    /**
-     * Returns a promise which resolves to a page selected by the
-     * user.
-     *
-     * Supported options:
-     * - isAllowed: function which given a page returns true or false depending on
-     *   whether the page is a valid selection
-     */
-    this.selectPage = function(options) {
-      return pageflow.PageSelectionView.selectPage(options);
-    };
-
     /**
      * Failures API
      *
-     * Can watch collections for errors saving models and display the error
-     * allong with a retry button.
-     *
-     *     pageflow.editor.failures.watch(collection);
-     *
-     * It's possible to add failures to the UI by adding instances of subclasses of pageflow.Failure:
-     *
-     *     pageflow.editor.failures.add(new pageflow.OrderingFailure(model, collection));
+     * @returns {pageflow.Failures}
      *
+     * @alias failures
+     * @memberof module:pageflow/editor.pageflow.editor
      */
     this.failures = new pageflow.FailuresAPI();
 
     /**
      * Setup editor integration for page types.
+     * @alias pageTypes
+     * @memberof module:pageflow/editor.pageflow.editor
      */
     this.pageTypes = new pageflow.PageTypes();
 
     /**
-     *
+     * @alias fileTypes
+     * @memberof module:pageflow/editor.pageflow.editor
      */
     this.fileTypes = new pageflow.FileTypes();
-
-    /** @private */
-    this.createFileSelectionHandler = function(handlerName, encodedPayload) {
-      /** @private */
-      if (!this.fileSelectionHandlers[handlerName]) {
-        throw 'Unknown FileSelectionHandler ' + handlerName;
-      }
-
-      var payloadJson = JSON.parse(decodeURIComponent(encodedPayload));
-      return new this.fileSelectionHandlers[handlerName](payloadJson);
-    };
-  }
+  },
+
+  /**
+   *  Display Backbone/Marionette View inside the main panel
+   *  of the editor.
+   */
+  showViewInMainPanel: function(view) {
+    pageflow.app.mainRegion.show(view);
+  },
+
+  /**
+   *  Display the Pageflow-Preview inside the main panel.
+   */
+  showPreview: function() {
+    pageflow.app.mainRegion.$el.empty();
+  },
+
+  /**
+   * Register additional router and controller for sidebar.
+   *
+   * Supported options:
+   * - router: constructor function of Backbone Marionette app router
+   * - controller: constructor function of Backbone Marionette controller
+   */
+  registerSideBarRouting: function(options) {
+    this.sideBarRoutings.push(options);
+  },
+
+  /**
+   * Set the file that is the parent of nested files when they are
+   * uploaded. This value is automatically set and unset upon
+   * navigating towards the appropriate views.
+   */
+  setUploadTargetFile: function(file) {
+    this.nextUploadTargetFile = file;
+  },
+
+  /**
+   * Set the name of the help entry that shall be selected by
+   * default when the help view is opened. This value is
+   * automatically reset when navigation occurs.
+   */
+  setDefaultHelpEntry: function(name) {
+    this.nextDefaultHelpEntry = name;
+  },
+
+  applyDefaultHelpEntry: function(name) {
+    this.defaultHelpEntry = this.nextDefaultHelpEntry;
+    this.nextDefaultHelpEntry = null;
+  },
+
+  /**
+   * Register additional menu item to be displayed on the root sidebar
+   * view.
+   *
+   * Supported options:
+   * - translationKey: for the label
+   * - path: route to link to
+   * - click: click handler
+   */
+  registerMainMenuItem: function(options) {
+    this.mainMenuItems.push(options);
+  },
+
+  /**
+   * Register a custom initializer which will be run before the boot
+   * initializer of the editor.
+   */
+  addInitializer: function(fn) {
+    this.initializers.push(fn);
+  },
+
+  /**
+   * Navigate to the given path.
+   */
+  navigate: function(path, options) {
+    if (!this.router) {
+      throw 'Routing has not been initialized yet.';
+    }
+
+    this.router.navigate(path, options);
+  },
+
+  /**
+   * Extend the interface of page configuration objects. This is
+   * especially convenient to wrap structured data from the page
+   * configuration as Backbone objects.
+   *
+   * Example:
+   *
+   *     pageflow.editor.registerPageConfigurationMixin({
+   *       externalLinks: function() {
+   *         return new Backbone.Collection(this.get('external_links'));
+   *       }
+   *     }
+   *
+   *     pageflow.pages.get(1).configuration.externalLinks().each(...);
+   */
+  registerPageConfigurationMixin: function(mixin) {
+    Cocktail.mixin(pageflow.Configuration, mixin);
+  },
+
+  /**
+   * File selection handlers let editor extensions use the files view
+   * to select files for usage in their custom models.
+   *
+   * See {@link module:pageflow/editor.pageflow.editor.selectFile
+   * selectFile} method for details how to trigger file selection.
+   *
+   * Example:
+   *
+   *     function MyFileSelectionHandler(options) { this.call =
+   *       function(file) { // invoked with the selected file };
+   *
+   *       this.getReferer = function() { // the path to return to
+   *         when the back button is clicked // or after file
+   *         selection return '/some/path'; } }
+   *
+   *
+         pageflow.editor.registerFileSelectionHandler('my_file_selection_handler',
+         MyFileSelectionHandler);
+   */
+  registerFileSelectionHandler: function(name, handler) {
+    this.fileSelectionHandlers[name] = handler;
+  },
+
+  /**
+   * Trigger selection of the given file type with the given
+   * handler. Payload hash is passed to selection handler as options.
+   *
+   * @param {string|{name: string, filter: string}} fileType
+   *   Either collection name of a file type or and object containing
+   *   the collection name a file type and a the name of a file type
+   *   filter.
+   *
+   * @param {string} handlerName
+   *   The name of a handler registered via {@link
+   *   module:pageflow/editor.pageflow.editor.registerFileSelectionHandler}.
+   *
+   * @param {Object} payload
+   *   Options passed to the file selection handler.
+   *
+   * @example
+   *
+   * pageflow.editor.selectFile('image_files',
+   *                            'my_file_selection_handler',
+   *                            {some: 'option for handler'});
+   *
+   * pageflow.editor.selectFile({name: 'image_files', filter: 'some_filter'},
+   *                            'my_file_selection_handler',
+   *                            {some: 'option for handler'});
+   */
+  selectFile: function(fileType, handlerName, payload) {
+    if (typeof fileType === 'string') {
+      fileType = {
+        name: fileType
+      };
+    }
+
+    this.navigate('/files/' + fileType.name +
+                  '?handler=' + handlerName +
+                  '&payload=' + encodeURIComponent(JSON.stringify(payload)) +
+                  (fileType.filter ? '&filter=' + fileType.filter : ''),
+                  {trigger: true});
+  },
+
+  /**
+   * Returns a promise which resolves to a page selected by the
+   * user.
+   *
+   * Supported options:
+   * - isAllowed: function which given a page returns true or false depending on
+   *   whether the page is a valid selection
+   */
+  selectPage: function(options) {
+    return pageflow.PageSelectionView.selectPage(options);
+  },
+
+  createFileSelectionHandler: function(handlerName, encodedPayload) {
+    if (!this.fileSelectionHandlers[handlerName]) {
+      throw 'Unknown FileSelectionHandler ' + handlerName;
+    }
+
+    var payloadJson = JSON.parse(decodeURIComponent(encodedPayload));
+    return new this.fileSelectionHandlers[handlerName](payloadJson);
+  },
 });

data/app/assets/javascripts/pageflow/editor/api/errors.js

@@ -0,0 +1,80 @@
+pageflow.UploadError = pageflow.Object.extend({
+  setMessage: function(options) {
+    this.upload = options.upload;
+
+    var typeTranslation;
+    if (options.typeTranslation) {
+      typeTranslation = options.typeTranslation;
+    } else if (this.upload.type !== ''){
+      typeTranslation = this.upload.type;
+    } else {
+      typeTranslation = I18n.t('pageflow.editor.errors.upload.type_empty');
+    }
+
+    var interpolations = {name: this.upload.name,
+                          type: typeTranslation,
+                          validList: options.validList};
+
+    this.message = I18n.t(options.translationKey, interpolations);
+  }
+});
+
+pageflow.UnmatchedUploadError = pageflow.UploadError.extend({
+  name: 'UnmatchedUploadError',
+
+  initialize: function(upload) {
+    this.setMessage({upload: upload,
+                     translationKey: 'pageflow.editor.errors.unmatched_upload_error'});
+  }
+});
+
+pageflow.validFileTypeTranslationList = {
+  validFileTypeTranslations: function(validFileTypes) {
+    return _.map(validFileTypes,
+            function(validFileType) {
+              return I18n.t('activerecord.models.' + validFileType.i18nKey + '.other');
+            }).join(', ');
+  }
+};
+
+pageflow.NestedTypeError = pageflow.UploadError.extend({
+  name: 'NestedTypeError',
+
+  initialize: function(upload, options) {
+    var fileType = options.fileType;
+    var fileTypes = options.fileTypes;
+    var validParentFileTypes = fileTypes.filter(function(parentFileType) {
+      return parentFileType.nestedFileTypes.contains(fileType);
+    });
+    var validParentFileTypeTranslations = this.validFileTypeTranslations(validParentFileTypes);
+
+    var typeI18nKey = fileTypes.findByUpload(upload).i18nKey;
+    var typePluralTranslation = I18n.t('activerecord.models.' + typeI18nKey + '.other');
+
+    this.setMessage({upload: upload,
+                     translationKey: 'pageflow.editor.errors.nested_type_error',
+                     typeTranslation: typePluralTranslation,
+                     validList: validParentFileTypeTranslations});
+  }
+});
+Cocktail.mixin(pageflow.NestedTypeError, pageflow.validFileTypeTranslationList);
+
+pageflow.InvalidNestedTypeError = pageflow.UploadError.extend({
+  name: 'InvalidNestedTypeError',
+
+  initialize: function(upload, options) {
+    var editor = options.editor;
+    var fileType = options.fileType;
+    var validFileTypes = editor.nextUploadTargetFile.fileType().nestedFileTypes.fileTypes;
+    var validFileTypeTranslations = this.validFileTypeTranslations(validFileTypes);
+
+    var typeI18nKey = fileType.i18nKey;
+    var typeSingularTranslation = I18n.t('activerecord.models.' + typeI18nKey + '.one');
+
+    this.setMessage({upload: upload,
+                     translationKey: 'pageflow.editor.errors.invalid_nested_type_error',
+                     typeTranslation: typeSingularTranslation,
+                     validList: validFileTypeTranslations});
+  }
+});
+Cocktail.mixin(pageflow.InvalidNestedTypeError, pageflow.validFileTypeTranslationList);