danielebarchiesi@4: <?php
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * @file
danielebarchiesi@4:  * Abstraction of the selection logic of an entity reference field.
danielebarchiesi@4:  *
danielebarchiesi@4:  * Implementations that wish to provide an implementation of this should
danielebarchiesi@4:  * register it using CTools' plugin system.
danielebarchiesi@4:  */
danielebarchiesi@4: interface EntityReference_SelectionHandler {
danielebarchiesi@4:   /**
danielebarchiesi@4:    * Factory function: create a new instance of this handler for a given field.
danielebarchiesi@4:    *
danielebarchiesi@4:    * @param $field
danielebarchiesi@4:    *   A field datastructure.
danielebarchiesi@4:    * @return EntityReferenceHandler
danielebarchiesi@4:    */
danielebarchiesi@4:   public static function getInstance($field, $instance = NULL, $entity_type = NULL, $entity = NULL);
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * Return a list of referencable entities.
danielebarchiesi@4:    *
danielebarchiesi@4:    * @return
danielebarchiesi@4:    *   An array of referencable entities, which keys are entity ids and
danielebarchiesi@4:    *   values (safe HTML) labels to be displayed to the user.
danielebarchiesi@4:    */
danielebarchiesi@4:   public function getReferencableEntities($match = NULL, $match_operator = 'CONTAINS', $limit = 0);
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * Count entities that are referencable by a given field.
danielebarchiesi@4:    */
danielebarchiesi@4:   public function countReferencableEntities($match = NULL, $match_operator = 'CONTAINS');
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * Validate that entities can be referenced by this field.
danielebarchiesi@4:    *
danielebarchiesi@4:    * @return
danielebarchiesi@4:    *   An array of entity ids that are valid.
danielebarchiesi@4:    */
danielebarchiesi@4:   public function validateReferencableEntities(array $ids);
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * Validate Input from autocomplete widget that has no Id.
danielebarchiesi@4:    *
danielebarchiesi@4:    * @see _entityreference_autocomplete_validate()
danielebarchiesi@4:    *
danielebarchiesi@4:    * @param $input
danielebarchiesi@4:    * 	 Single string from autocomplete widget.
danielebarchiesi@4:    * @param $element
danielebarchiesi@4:    *   The form element to set a form error.
danielebarchiesi@4:    * @return
danielebarchiesi@4:    *   Value of a matching entity id, or NULL if none.
danielebarchiesi@4:    */
danielebarchiesi@4:   public function validateAutocompleteInput($input, &$element, &$form_state, $form);
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * Give the handler a chance to alter the SelectQuery generated by EntityFieldQuery.
danielebarchiesi@4:    */
danielebarchiesi@4:   public function entityFieldQueryAlter(SelectQueryInterface $query);
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * Return the label of a given entity.
danielebarchiesi@4:    */
danielebarchiesi@4:   public function getLabel($entity);
danielebarchiesi@4: 
danielebarchiesi@4:   /**
danielebarchiesi@4:    * Generate a settings form for this handler.
danielebarchiesi@4:    */
danielebarchiesi@4:   public static function settingsForm($field, $instance);
danielebarchiesi@4: }
danielebarchiesi@4: 
danielebarchiesi@4: /**
danielebarchiesi@4:  * A null implementation of EntityReference_SelectionHandler.
danielebarchiesi@4:  */
danielebarchiesi@4: class EntityReference_SelectionHandler_Broken implements EntityReference_SelectionHandler {
danielebarchiesi@4:   public static function getInstance($field, $instance = NULL, $entity_type = NULL, $entity = NULL) {
danielebarchiesi@4:     return new EntityReference_SelectionHandler_Broken($field, $instance, $entity_type, $entity);
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   protected function __construct($field, $instance) {
danielebarchiesi@4:     $this->field = $field;
danielebarchiesi@4:     $this->instance = $instance;
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   public static function settingsForm($field, $instance) {
danielebarchiesi@4:     $form['selection_handler'] = array(
danielebarchiesi@4:       '#markup' => t('The selected selection handler is broken.'),
danielebarchiesi@4:     );
danielebarchiesi@4:     return $form;
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   public function getReferencableEntities($match = NULL, $match_operator = 'CONTAINS', $limit = 0) {
danielebarchiesi@4:     return array();
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   public function countReferencableEntities($match = NULL, $match_operator = 'CONTAINS') {
danielebarchiesi@4:     return 0;
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   public function validateReferencableEntities(array $ids) {
danielebarchiesi@4:     return array();
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   public function validateAutocompleteInput($input, &$element, &$form_state, $form) {
danielebarchiesi@4:     return NULL;
danielebarchiesi@4:   }
danielebarchiesi@4: 
danielebarchiesi@4:   public function entityFieldQueryAlter(SelectQueryInterface $query) {}
danielebarchiesi@4: 
danielebarchiesi@4:   public function getLabel($entity) {
danielebarchiesi@4:     return '';
danielebarchiesi@4:   }
danielebarchiesi@4: }