You are here

Home » API reference » Flag 7.3 » flag_entity.inc

class flag_entity in Flag 7.3

Same name and namespace in other branches
  1. 7.2 flag.inc \flag_entity

Base entity flag handler.

Hierarchy

Expanded class hierarchy of flag_entity

2 string references to 'flag_entity'
flag_flag_type_info in ./flag.flag.inc
Implements hook_flag_type_info().
flag_flag_type_info_alter in ./flag.flag.inc
Implements hook_flag_type_info_alter().

File

includes/flag/flag_entity.inc, line 11
Contains the flag_entity class.

View source 
class flag_entity extends flag_flag {

  /**
   * Adds additional options that are common for all entity types.
   */
  function options() {
    $options = parent::options();
    $options += array(
      // Output the flag in the entity links.
      // This is empty for now and will get overriden for different
      // entities.
      // @see hook_entity_view().
      'show_in_links' => array(),
      // Output the flag as individual pseudofields.
      'show_as_field' => FALSE,
      // Add a checkbox for the flag in the entity form.
      // @see hook_field_attach_form().
      'show_on_form' => FALSE,
      'access_author' => '',
      'show_contextual_link' => FALSE,
    );
    return $options;
  }

  /**
   * Options form extras for the generic entity flag.
   */
  function options_form(&$form) {
    $bundles = array();
    $entity_info = entity_get_info($this->entity_type);
    foreach ($entity_info['bundles'] as $bundle_key => $bundle) {
      $bundles[$bundle_key] = check_plain($bundle['label']);
    }
    $form['access']['types'] = array(
      '#type' => 'checkboxes',
      '#title' => t('Bundles'),
      '#options' => $bundles,
      '#description' => t('Select the bundles that this flag may be used on. Leave blank to allow on all bundles for the entity type.'),
      '#default_value' => $this->types,
    );

    // Add checkboxes to show flag link on each entity view mode.
    $options = array();
    $defaults = array();
    $entity_view_modes = $entity_info['view modes'];
    foreach ($entity_view_modes as $name => $view_mode) {
      $options[$name] = t('Display on @name view mode', array(
        '@name' => $view_mode['label'],
      ));
      $defaults[$name] = !empty($this->show_in_links[$name]) ? $name : 0;
    }

    // Select the first display option by default if this is a new flag.
    if (empty($this->fid)) {
      $first_view_mode_keys = array_keys($entity_view_modes);
      $first_view_mode = reset($first_view_mode_keys);
      $defaults[$first_view_mode] = $first_view_mode;
    }
    $form['display']['show_in_links'] = array(
      '#type' => 'checkboxes',
      '#title' => t('Display in entity links'),
      '#description' => t('Show the flag link with the other links on the entity.'),
      '#options' => $options,
      '#default_value' => $defaults,
    );
    $form['display']['show_as_field'] = array(
      '#type' => 'checkbox',
      '#title' => t('Display link as field'),
      '#description' => t('Show the flag link as a pseudofield, which can be ordered among other entity elements in the "Manage display" settings for the entity type.'),
      '#default_value' => isset($this->show_as_field) ? $this->show_as_field : TRUE,
    );
    if (empty($entity_info['fieldable'])) {
      $form['display']['show_as_field']['#disabled'] = TRUE;
      $form['display']['show_as_field']['#description'] = t("This entity type is not fieldable.");
    }
    $form['display']['show_on_form'] = array(
      '#type' => 'checkbox',
      '#title' => t('Display checkbox on entity edit form'),
      '#default_value' => $this->show_on_form,
      '#weight' => 5,
    );

    // We use FieldAPI to put the flag checkbox on the entity form, so therefore
    // require the entity to be fielable. Since this is a potential DX
    // headscratcher for a developer wondering where this option has gone,
    // we disable it and explain why.
    if (empty($entity_info['fieldable'])) {
      $form['display']['show_on_form']['#disabled'] = TRUE;
      $form['display']['show_on_form']['#description'] = t('This is only possible on entities which are fieldable.');
    }
    $form['display']['show_contextual_link'] = array(
      '#type' => 'checkbox',
      '#title' => t('Display in contextual links'),
      '#default_value' => $this->show_contextual_link,
      '#description' => t('Note that not all entity types support contextual links.'),
      '#access' => module_exists('contextual'),
      '#weight' => 10,
    );
  }

  /**
   * Loads the entity object.
   */
  function _load_entity($entity_id) {
    if (is_numeric($entity_id)) {
      $entity = entity_load($this->entity_type, array(
        $entity_id,
      ));
      return reset($entity);
    }
    return NULL;
  }

  /**
   * Checks whether the flag applies for the current entity bundle.
   */
  function applies_to_entity($entity) {
    $entity_info = entity_get_info($this->entity_type);

    // The following conditions are applied:
    // - if the types array is empty, the flag applies to all bundles and thus
    //   to this entity.
    // - if the entity has no bundles, the flag applies to the entity.
    // - if the entity's bundle is in the list of types.
    if (empty($this->types) || empty($entity_info['entity keys']['bundle']) || in_array($entity->{$entity_info['entity keys']['bundle']}, $this->types)) {
      return TRUE;
    }
    return FALSE;
  }

  /**
   * Provides permissions for this flag.
   *
   * @return
   *  An array of permissions for hook_permission().
   */
  function get_permissions() {

    // For entity flags, use the human label of the entity.
    $entity_info = entity_get_info($this->entity_type);
    $entity_label = $entity_info['label'];
    return array(
      "flag {$this->name}" => array(
        'title' => t('Flag %entity entities as %flag_title', array(
          '%flag_title' => $this->title,
          '%entity' => $entity_label,
        )),
      ),
      "unflag {$this->name}" => array(
        'title' => t('Unflag %entity entities as %flag_title', array(
          '%flag_title' => $this->title,
          '%entity' => $entity_label,
        )),
      ),
    );
  }

  /**
   * Invoke a Rules event in reaction to a flagging or unflagging.
   *
   * @param $action
   *   Either 'flag' or 'unflag'.
   * @param $flagging
   *  The flagging entity that is either newly created or about to be deleted.
   * @param $entity_id
   *  The entity ID of entity being flagged or unflagged.
   * @param $account
   *  The account performing the action.
   */
  protected function invoke_rules_event($action, $flagging, $entity_id, $account) {
    switch ($action) {
      case 'flag':
        $event_name = 'flag_flagged_' . $this->name;
        break;
      case 'unflag':
        $event_name = 'flag_unflagged_' . $this->name;
        break;
    }
    $variables = array(
      'flag' => $this,
      'flagged_' . $this->entity_type => $entity_id,
      'flagging_user' => $account,
      'flagging' => $flagging,
    );
    rules_invoke_event_by_args($event_name, $variables);
  }

  /**
   * Returns the entity id, if it already exists.
   */
  function get_entity_id($entity) {
    $entity_info = entity_get_info($this->entity_type);
    if ($entity && isset($entity->{$entity_info['entity keys']['id']})) {
      return $entity->{$entity_info['entity keys']['id']};
    }
  }

  /**
   * Determine whether the flag should show a flag link in entity links.
   */
  function shows_in_entity_links($view_mode) {

    // Check for settings for the given view mode.
    if (isset($this->show_in_links[$view_mode])) {
      return (bool) $this->show_in_links[$view_mode];
    }
    return FALSE;
  }

  /**
   * Returns token types for the current entity type.
   */
  function get_labels_token_types() {

    // The token type name might be different to the entity type name. If so,
    // an own flag entity handler can be used for overriding this.
    $entity_info = entity_get_info($this->entity_type);
    if (isset($entity_info['token type'])) {
      return array_merge(array(
        $entity_info['token type'],
      ), parent::get_labels_token_types());
    }
    else {
      return array_merge(array(
        $this->entity_type,
      ), parent::get_labels_token_types());
    }
  }

  /**
   * Replaces tokens.
   */
  function replace_tokens($label, $contexts, $options, $entity_id) {
    if ($entity_id && ($entity = $this
      ->fetch_entity($entity_id))) {
      $contexts[$this->entity_type] = $entity;
    }
    return parent::replace_tokens($label, $contexts, $options, $entity_id);
  }

  /**
   * Returns a 'flag action' object.
   */
  function get_flag_action($entity_id) {
    $flag_action = parent::get_flag_action($entity_id);
    $entity = $this
      ->fetch_entity($entity_id);
    $flag_action->content_title = entity_label($this->entity_type, $entity);
    $flag_action->content_url = $this
      ->_flag_url($this->entity_type . '/' . $this
      ->get_entity_id($entity));
    return $flag_action;
  }

  /**
   * Returns objects the action may possible need.
   */
  function get_relevant_action_objects($entity_id) {
    return array(
      $this->entity_type => $this
        ->fetch_entity($entity_id),
    );
  }

  /**
   * Returns information for the Views integration.
   */
  function get_views_info() {
    $entity_info = entity_get_info($this->entity_type);
    if (!isset($entity_info['base table'])) {
      return NULL;
    }
    return array(
      'views table' => $entity_info['base table'],
      'join field' => $entity_info['entity keys']['id'],
      'title field' => isset($entity_info['entity keys']['label']) ? $entity_info['entity keys']['label'] : '',
      'title' => t('@entity_label flag', array(
        '@entity_label' => $entity_info['label'],
      )),
      'help' => t('Limit results to only those entity flagged by a certain flag; Or display information about the flag set on a entity.'),
      'counter title' => t('@entity_label flag counter', array(
        '@entity_label' => $entity_info['label'],
      )),
      'counter help' => t('Include this to gain access to the flag counter field.'),
    );
  }

}

Members

Namesort descending Modifiers Type Description Overrides
flag_entity::applies_to_entity function Checks whether the flag applies for the current entity bundle. Overrides flag_flag::applies_to_entity
flag_entity::get_entity_id function Returns the entity id, if it already exists. Overrides flag_flag::get_entity_id 1
flag_entity::get_flag_action function Returns a 'flag action' object. Overrides flag_flag::get_flag_action 2
flag_entity::get_labels_token_types function Returns token types for the current entity type. Overrides flag_flag::get_labels_token_types 1
flag_entity::get_permissions function Provides permissions for this flag. Overrides flag_flag::get_permissions
flag_entity::get_relevant_action_objects function Returns objects the action may possible need. Overrides flag_flag::get_relevant_action_objects 2
flag_entity::get_views_info function Returns information for the Views integration. Overrides flag_flag::get_views_info 1
flag_entity::invoke_rules_event protected function Invoke a Rules event in reaction to a flagging or unflagging. Overrides flag_flag::invoke_rules_event
flag_entity::options function Adds additional options that are common for all entity types. Overrides flag_flag::options 3
flag_entity::options_form function Options form extras for the generic entity flag. Overrides flag_flag::options_form 3
flag_entity::replace_tokens function Replaces tokens. Overrides flag_flag::replace_tokens 2
flag_entity::shows_in_entity_links function Determine whether the flag should show a flag link in entity links. Overrides flag_flag::shows_in_entity_links
flag_entity::_load_entity function Loads the entity object. Overrides flag_flag::_load_entity
flag_flag::$entity_type property The entity type this flag works with.
flag_flag::$errors public property An associative array containing textual errors that may be created during validation.
flag_flag::$fid property The database ID.
flag_flag::$global property Whether this flag state should act as a single toggle to all users.
flag_flag::$name property The flag's "machine readable" name.
flag_flag::$roles property The roles array. This can be populated by fetch_roles() when needed.
flag_flag::$title property The human-readable title for this flag.
flag_flag::$types property The sub-types, AKA bundles, this flag applies to.
flag_flag::access function Determines whether the user may flag, or unflag, the given entity.
flag_flag::access_entity_enabled function Utility function: Checks whether a flag applies to a certain type, and possibly subtype, of entity.
flag_flag::access_multiple function Determine access to multiple objects.
flag_flag::admin_path function Returns administrative menu path for carrying out some action.
flag_flag::applies_to_entity_id function Returns TRUE if the flag applies to the entity with the given ID.
flag_flag::construct function Default constructor. Loads the default options.
flag_flag::delete function Deletes a flag from the database.
flag_flag::disable function Disable a flag provided by a module.
flag_flag::enable function Enable a flag provided by a module.
flag_flag::factory_by_array static function Create a complete flag (except an FID) from an array definition.
flag_flag::factory_by_entity_type static function Another factory method. Returns a new, "empty" flag; e.g., one suitable for the "Add new flag" page.
flag_flag::factory_by_row static function Creates a flag from a database row. Returns it.
flag_flag::fetch_entity function Fetches, possibly from some cache, an entity this flag works with.
flag_flag::fetch_roles function Load this flag's role data from permissions.
flag_flag::find_default_flag function Finds the "default flag" corresponding to this flag.
flag_flag::flag function Flags, or unflags, an item. 1
flag_flag::flagging_delete private function Unflag an entity by deleting a Flagging.
flag_flag::flagging_insert private function Create a new Flagging to flag an entity.
flag_flag::flagging_update private function Update a Flagging.
flag_flag::form_input function Update the flag with settings entered in a form. 1
flag_flag::get_count function Returns the number of times an item is flagged.
flag_flag::get_errors function Returns an array of errors set during validation.
flag_flag::get_flagging function Similar to is_flagged() excepts it returns the flagging entity.
flag_flag::get_flagging_record function Returns the flagging record. 2
flag_flag::get_label function Processes a flag label for display. This means language translation and token replacements.
flag_flag::get_link_type function Get the link type for this flag.
flag_flag::get_serialized_options function Options are stored serialized in the database.
flag_flag::get_title function A convenience method for getting the flag title.
flag_flag::get_user_count function Returns the number of items a user has flagged.
flag_flag::get_valid_actions function Returns an array of all actions that are executable with this flag.
flag_flag::insert function Saves a new flag to the database. Better use save().
flag_flag::is_compatible function Returns TRUE if this flag's declared API version is compatible with this module.
flag_flag::is_flagged function Determines if a certain user has flagged this object.
flag_flag::new_flagging function Construct a new, empty flagging entity object.
flag_flag::remember_entity function Store an object in the flag handler's cache.
flag_flag::revert function Reverts an overriding flag to its default state.
flag_flag::save function Saves a flag to the database. It is a wrapper around update() and insert().
flag_flag::theme function Renders a flag/unflag link.
flag_flag::theme_suggestions function Provides an array of possible themes to try for a given flag.
flag_flag::type_access function Implements access() implemented by each child class. 1
flag_flag::type_access_multiple function Implements access_multiple() implemented by each child class. 3
flag_flag::update function Saves an existing flag to the database. Better use save().
flag_flag::user_access function Determines whether the user has the permission to use this flag.
flag_flag::uses_anonymous_cookies function Returns TRUE if this flag requires anonymous user cookies.
flag_flag::validate function Validates this flag's options.
flag_flag::validate_access function Validates that the current flag's access settings are valid.
flag_flag::validate_name function Validates that the current flag's name is valid.
flag_flag::_decrease_count function Decreases the flag count for an object and clears the static counts cache.
flag_flag::_flag_anonymous function Set a cookie for anonymous users to record their flagging.
flag_flag::_flag_url function A shortcut function to output the link URL.
flag_flag::_increase_count function Increases the flag count for an object and clears the static counts cache.
flag_flag::_is_flagged function Determines if a certain user has flagged this object.
flag_flag::_unflag_anonymous function Remove the cookie for anonymous users to record their unflagging.