****************************
foundation-collection-action
****************************

``foundation-collection-action`` is a control to perform an certain action related to :doc:`foundation-selections <../../../vocabulary/selections>`.


.foundation-collection-action
=============================

Indicates the control.

Selector Rule::

   .foundation-collection-action


[data-foundation-collection-action]
===================================

The JSON config to configure the behaviour of ``.foundation-collection-action``, which satisfies ``FoundationCollectionActionConfig`` interface.

Selector Rule::

   .foundation-collection-action[data-foundation-collection-action]


Activation Behavior
===================

Upon activation, the control will execute the action as specified at action property of ``data-foundation-collection-action`` attribute.

The selections and collection passed to the action handler are based on the following priority:

1. If the control has internal data named ``foundationCollectionItem`` of type ``HTMLElement`` (jQuery: ``item = control.data("foundationCollectionItem")``), the selection is that item, while the collection is the ``.foundation-collection`` of that item.

2. If the control has ``target`` property of ``data-foundation-collection-action`` attribute, the collection is from that property, while the selections are from the ``.foundation-selections-item`` of that collection.

3. If the control is a descendant of ``.foundation-collection-item``, the selection is that item, while the collection is the ``.foundation-collection`` of that item.


Showing and Hiding Behavior
===========================

When the control is not a descendant of ``.foundation-collection-item``, the control is shown if all the following conditions are true (``AND`` logic); otherwise it’s hidden:

1. ``activeCount`` property of ``data-foundation-collection-action`` attribute is set and its value is evaluated to ``true``.
2. ``activeSelectionCount`` property of ``data-foundation-collection-action`` attribute is set and its value is evaluated to ``true``.
3. ``ignoreRel`` property of ``data-foundation-collection-action`` attribute is evaluated to ``false`` and the control matches the common relationships of all selected items. i.e. ``isCommon()`` is evaluated to ``true``.

isCommon() Algorithm
--------------------

.. code-block:: ts

   /**
    * Returns <code>true</code> if the given control matches the common relationships of all selected items; <code>false</code> otherwise.
    *
    * @param control The jQuery object wrapping <code>.foundation-collection-action</code>.
    * @param collection The jQuery object wrapping <code>.foundation-collection</code> specified by <code>target</code> property of <code>data-foundation-collection-action</code> attribute.
    */
   function isCommon(control: JQuery, collection: JQuery): boolean {
     var rels = collection.find(".foundation-selections-item").toArray().map(function(item) {
       var qa = $(item).find(".foundation-collection-quickactions");
       var rel = (qa.data("foundationCollectionQuickactionsRel") || "").trim();
       return rel.length ? rel.split(/\s+/) : [];
     });

     var noRelAtAll = rels.every(function(v) { return v.length === 0; });
     if (noRelAtAll) return true;

     return rels.every(function(v) {
       return !v.every(function(rel) { return !control.hasClass(rel); });
     });
   }


FoundationCollectionActionConfig
================================

.. code-block:: ts

   interface FoundationCollectionActionConfig {
     /**
      * The selector to the <code>.foundation-collection</code>. This is optional and used when the control is placed outside the collection.
      */
     target: string;

     /**
      * The optional property to show or hide the control according to how many <code>.foundation-collection-item</code> in the collection.
      *
      * 0: Show when there is no item at all; hide otherwise
      * ">0": Show when there is at least one item; hide otherwise
      */
     activeCount?: any;

     /**
      * The optional property to show or hide the control according to how many <code>.foundation-selections-item</code> in the collection.
      *
      * "none": Show when there is no selection at all; hide otherwise
      * "single": Show when there is exactly one selection; hide otherwise
      * "multiple": Show when there is one or more selections; hide otherwise
      */
     activeSelectionCount?: string;

     /**
      * The action to be performed when the control is activated. See Action Registration section.
      * If this property is not specified, no action will be performed.
      */
     action?: string;

     /**
      * The optional property to skip the processing of <code>isCommon()</code> algorithm.
      * <code>true</code> to skip, <code>false</code> (default) otherwise.
      */
     ignoreRel: boolean;

     /**
      * The general purpose data to be used by the action handler. Consult specific action handler for details.
      */
     data?: any;
   }

.. _foundation-collection-action-action-legacy:

Action Registration
===================

The action of ``.foundation-collection-action`` can be registered to the :doc:`registry <../../registry/index>` using ``foundation.collection.action.action`` as the name and the config satisfying the following interface:

.. code-block:: ts

   interface FoundationCollectionActionActionAdapter {
     /**
      * The name of the action. It is recommended that it is namespaced using dot notation according to application that register the action.
      * "foundation" namespace is reserved for Granite UI.
      *
      * @example
      * foundation.link
      */
     name: string;

     /**
      * The handler to actually perform the action.
      * If <code>false</code> is returned, the next action in the chain will be evaluated. Otherwise the chain stops.
      *
      * @param name The name of the action
      * @param el The element of the <code>.foundation-collection-action</code>
      * @param config The value of <code>[data-foundation-collection-action]</code>
      * @param collection The <code>.foundation-collection</code> associated to the action
      * @param selections The array of <code>.foundation-selections-item</code> elements of the collection
      */
     handler: (name: string, el: Element, config: FoundationCollectionActionConfig, collection: Element, selections: Element[]) => boolean;
   }

A chain of registered actions is created using LIFO (last in, first out) algorithm. The action handler will be called when the name matches. If false is returned by the handler, the next action in the chain will be evaluated. Otherwise the chain stops.

Example
-------

.. code-block:: js

   $(window).adaptTo("foundation-registry").register("foundation.collection.action.action", {
     name: "foundation.link",
     handler: function(name, el, config, collection, selections) {
       var url = URITemplate.expand(config.data.href, {
         item: selections.map(function(item) { return $(item).data("foundation-collection-item-id"); })
       });

       window.location = url;
     }
   });


Relationship Graph
==================

.. graphviz::

   digraph "foundation-collection" {
     rankdir=BT;
     "foundation-selections" -> "foundation-collection" [label="extends", weight=8];
     "foundation-collection-action" -> "foundation-selections" [label="reacts to"];
     "foundation.link" -> "foundation-collection-action" [label="provides action to"];
     "foundation.pushstate" -> "foundation-collection-action" [label="provides action to"];
   }