@qooxdoo/framework/source/class/qx/ui/form/renderer/AbstractRenderer.js

The JS Framework for Coders

/* ************************************************************************

   qooxdoo - the new era of web development

   http://qooxdoo.org

   Copyright:
     2004-2009 1&1 Internet AG, Germany, http://www.1und1.de

   License:
     MIT: https://opensource.org/licenses/MIT
     See the LICENSE file in the project's top-level directory for details.

   Authors:
     * Martin Wittemann (martinwittemann)

************************************************************************ */

/**
 * Abstract renderer for {@link qx.ui.form.Form}. This abstract renderer should
 * be the superclass of all form renderer. It takes the form, which is
 * supplied as constructor parameter and configures itself. So if you need to
 * set some additional information on your renderer before adding the widgets,
 * be sure to do that before calling this.base(arguments, form).
 */
qx.Class.define("qx.ui.form.renderer.AbstractRenderer", {
  type: "abstract",
  extend: qx.ui.core.Widget,
  implement: qx.ui.form.renderer.IFormRenderer,

  /**
   * @param form {qx.ui.form.Form} The form to render.
   */
  construct(form) {
    super();

    this._labels = [];

    // translation support
    if (qx.core.Environment.get("qx.dynlocale")) {
      this.__changeLocaleRendererListenerId = qx.locale.Manager.getInstance().addListener(
        "changeLocale",
        this._onChangeLocale,
        this
      );

      this._names = [];
    }
    this._form = form;
    this._render();

    form.addListener("change", this._onFormChange, this);
  },

  properties: {
    /**
     * A string that is appended to the label if it is not empty.
     * Defaults to " :"
     */
    labelSuffix: {
      check: "String",
      init: " :",
      event: "changeLabelSuffix",
      nullable: true
    },

    /**
     * A string that is appended to the label and the label suffix if the corresponding
     * form field is mandatory. Defaults to space plus a red asterisk.
     */
    requiredSuffix: {
      check: "String",
      init: " <span style='color:red'>*</span> ",
      event: "changeRequiredSuffix",
      nullable: false
    }
  },

  members: {
    _names: null,
    _form: null,
    _labels: null,

    /**
     * Renders the form: adds the items and buttons.
     */
    _render() {
      // add the groups
      var groups = this._form.getGroups();
      for (var i = 0; i < groups.length; i++) {
        var group = groups[i];
        this.addItems(
          group.items,
          group.labels,
          group.title,
          group.options,
          group.headerOptions
        );
      }

      // add the buttons
      var buttons = this._form.getButtons();
      var buttonOptions = this._form.getButtonOptions();
      for (var i = 0; i < buttons.length; i++) {
        this.addButton(buttons[i], buttonOptions[i]);
      }
    },

    /**
     * Handler responsible for updating the rendered widget as soon as the
     * form changes.
     */
    _onFormChange() {
      this._removeAll();
      // remove all created labels
      for (var i = 0; i < this._labels.length; i++) {
        this._labels[i].dispose();
      }
      this._labels = [];

      this._render();
    },

    /**
     * Helper to bind the item's visibility to the label's visibility.
     * @param item {qx.ui.core.Widget} The form element.
     * @param label {qx.ui.basic.Label} The label for the form element.
     */
    _connectVisibility(item, label) {
      // map the items visibility to the label
      item.bind("visibility", label, "visibility");
    },

    /**
     * Locale change event handler
     *
     * @signature function(e)
     * @param e {Event} the change event
     */
    _onChangeLocale: qx.core.Environment.select("qx.dynlocale", {
      true(e) {
        for (var i = 0; i < this._names.length; i++) {
          var entry = this._names[i];
          if (entry.name && entry.name.translate) {
            entry.name = entry.name.translate();
          }
          var newText = this._createLabelText(entry.name, entry.item);
          entry.label.setValue(newText);
        }
      },

      false: null
    }),

    /**
     * Creates the label text for the given form item.
     *
     * @param name {String} The content of the label without the
     *   trailing * and :
     * @param item {qx.ui.form.IForm} The item, which has the required state.
     * @return {String} The text for the given item.
     */
    _createLabelText(name, item) {
      var requiredSuffix = "";
      if (item.getRequired()) {
        requiredSuffix = this.getRequiredSuffix();
      }

      // Create the label. Append a suffix only if there's text to display.
      var labelSuffix =
        name.length > 0 || item.getRequired() ? this.getLabelSuffix() : "";
      return name + requiredSuffix + labelSuffix;
    },

    // interface implementation
    addItems(items, names, title) {
      throw new Error("Abstract method call");
    },

    // interface implementation
    addButton(button) {
      throw new Error("Abstract method call");
    }
  },

  /*
  *****************************************************************************
     DESTRUCTOR
  *****************************************************************************
  */

  destruct() {
    if (qx.core.Environment.get("qx.dynlocale") && this.__changeLocaleRendererListenerId) {
      qx.locale.Manager.getInstance().removeListenerById(
        this.__changeLocaleRendererListenerId
      );
    }
    this._names = null;

    this._form.removeListener("change", this._onFormChange, this);
    this._form = null;
  }
});