----------------
Omeka_Navigation
----------------

.. php:class:: Omeka_Navigation

    Package: :doc:`Navigation </Reference/packages/Navigation/index>`

    Customized subclass of Zend Framework's Zend_Navigation class.

    .. php:method:: __construct(array|Zend_Config $pages)
    
        Creates a new navigation container
        
        :param array|Zend_Config $pages:    [optional] pages to add

    .. php:method:: saveAsOption(String $optionName)
    
        Saves the navigation in the global options table.
        
        :param String $optionName:    The name of the option

    .. php:method:: loadAsOption(String $optionName)
    
        Loads the navigation from the global options table
        
        :param String $optionName:    The name of the option

    .. php:method:: addPage($page)
    
        Adds a page to the container.  If a page does not have a valid id, it will give it one.
        If a direct child page already has another page with the same uid then it will not add the page.
        However, it will add the page as a child of this navigation if one of its descendants already
        has the page.
        
        This method will inject the container as the given page's parent bycalling {@link Zend_Navigation_Page::setParent()}.
        
        :param unknown $page: 
        :returns: Zend_Navigation_Container                     fluent interface, returns self

    .. php:method:: getChildByUid(string $uid)
    
        Returns an immediate child page that has a uid of $uid.  If none exists, it returns null.
        
        :param string $uid:   The uid to search for in this navigation
        :returns: Zend_Navigation_Page The page

    .. php:method:: addPageToContainer(Zend_Navigation_Page $page, Zend_Navigation_Container $container)
    
        Adds a page to a container after normalizing it and its subpages
        
        :param Zend_Navigation_Page $page:    The page to add
        :param Zend_Navigation_Container $container:    The container to which to add the page
        :returns: Zend_Navigation_Container The container with the page added

    .. php:method:: createNavigationFromFilter(String $filterName = )
    
        Creates an Omeka Navigation object by adding
        pages generated by Omeka plugins and other contributors via a filter (e.x. 'public_navigation_main').
        The filter should provide an array pages like they are added to Zend_Navigation_Container::addPages
        However, the page types should only be one of the following types:
        Omeka_Navigation_Page_Uri or Zend_Navigation_Page_Mvc.  
        If the associated uri of any page is invalid, it will not add that page to the navigation. 
        Also, it removes expired pages from formerly active plugins and other former handlers of the filter.
        
        :param String $filterName:    The name of the filter

    .. php:method:: baseAddNormalizedPage($normalizedPage)
    
        Add a normalized page to the navigation using parent::addPage()
        This needs to wrapped so that methods like createNavigationFromFilter() can add pages directly using
        the parent class method.
        
        :param unknown $normalizedPage: 
        :returns: Zend_Navigation_Container                     fluent interface, returns self

    .. php:method:: mergePage(Zend_Navigation_Page $page, Zend_Navigation_Container $parentContainer)
    
        Merges a page (and its subpages) into this navigation.
        If the page already exists in the navigation, then it attempts to add 
        any new subpages of the page to it.  If a subpages already exists in the navigation, then it 
        it recursively attempts to add its new subpages to it, and so on.
        
        :param Zend_Navigation_Page $page: 
        :param Zend_Navigation_Container $parentContainer: 
        :returns: Zend_Navigation_Container  $parentContainer the suggested parentContainer for the page. The parentContainer must already be in the navigation and remain so throughout the merge.

    .. php:method:: _getLastPageOrderInContainer($container)
    
        Returns the page order of the last child page in the container.  
        If no page exists in the container, it returns 0.
        
        :param unknown $container: 
        :returns: int    the last page order in the container

    .. php:method:: mergeNavigation(Omeka_Navigation $nav)
    
        Merges a navigation object into this navigation.
        
        :param Omeka_Navigation $nav:

    .. php:method:: addPagesFromFilter(String $filterName = )
    
        Adds pages generated by Omeka plugins and other contributors via a filter (e.x. 'public_navigation_main').
        The filter should provide an array pages like they are added to Zend_Navigation_Container::addPages
        However, the page types should only be one of the following types:
        Omeka_Navigation_Page_Uri or Omeka_Navigation_Page_Mvc.  
        If the associated uri of any page is invalid, it will not add that page to the navigation. 
        Also, it removes expired pages from formerly active plugins and other former handlers of the filter.
        
        :param String $filterName:    The name of the filter

    .. php:method:: getExpiredPagesFromNav(Omeka_Navigation $excludeNav)
    
        Returns an array of expired pages from this navigation, 
        where all pages in the $excludeNav are considered non-expired.
        
        :param Omeka_Navigation $excludeNav: 
        :returns: array The array of expired pages

    .. php:method:: prunePages($pages)
    
        Prunes pages from this navigation.
        When a page is pruned its children pages are reattached to the first non-pruneable ancestor page.
        
        :param unknown $pages:

    .. php:method:: prunePage(Omeka_Navigation_Page_Mvc|Omeka_Navigation_Page_Uri $page)
    
        Prune page from this navigation.
        When a page is pruned its children pages are reattached to the first non-pruneable ancestor page.
        
        :param Omeka_Navigation_Page_Mvc|Omeka_Navigation_Page_Uri $page:  The page to prune

    .. php:method:: getOtherPages(array|null $excludePageUids)
    
        Returns an array of all pages from navigation that
        lack a uid in $excludePageUids
        
        :param array|null $excludePageUids:  The list uids for pages to exclude
        :returns: array The array of other pages.

    .. php:method:: getPageByUid(String $pageUid, Zend_Navigation_Container $container)
    
        Returns the navigation page associated with uid.
        It searches all descendant pages of this navigation  
        If not page is associated, then it returns null.
        
        :param String $pageUid: The uid of the page
        :param Zend_Navigation_Container $container: The container within which to search for the page. By default, it uses this navigation.
        :returns: Omeka_Zend_Navigation_Page_Uri|Omeka_Navigation_Page_Mvc|null

    .. php:method:: createPageUid(String $href)
    
        Returns the unique id for the page, which can be used to determine whether it can be added to the navigation
        
        :param String $href: The href of the page.
        :returns: String

    .. php:method:: removePageRecursive(Zend_Navigation_Page $page, Zend_Navigation_Container $parentContainer, boolean $reattach = )
    
        Recursively removes the given page from the parent container, including all subpages
        
        :param Zend_Navigation_Page $page: The page to remove from the parent container and all its subpages.
        :param Zend_Navigation_Container $parentContainer: The parent container (by default it is this navigation) from which to remove the page from its subpages
        :param boolean $reattach: Whether the subpages of the $page should be reattached to $parentContainer
        :returns: boolean Whether the page was removed

    .. php:method:: getNavigationOptionValueForInstall(String $optionName)
    
        Returns the option value associated with the default navigation during installation
        
        :param String $optionName: The option name for a stored navigation object.
        :returns: String The option value associated with the default navigation during installation. If no option is found for the option name, then it returns an empty string.

    .. php:method:: _normalizePageRecursive($page, $pageOptions = Array)
    
        Normalizes a page and its subpages so it can be added
        
        :param unknown $page: 
        :param unknown $pageOptions:  The options to set during normalization for every page and subpage
        :returns: Omeka_Navigation_Page_Uri|Omeka_Navigation_Page_Mvc|null The normalized page

    .. php:method:: _convertZendToOmekaNavigationPage(Zend_Navigation_Page $page, string $subclassPostfix)
    
        Converts a Zend_Navigation_Page subclass object to a corresponding Omeka object
        
        :param Zend_Navigation_Page $page: The page to convert
        :param string $subclassPostfix: The postfix of the subclass.  Must be 'Uri' or 'Mvc'
        :returns: Omeka_Navigation_Page_Uri|Omeka_Navigation_Page_Mvc The converted page

    .. php:method:: _conditionalReplaceValueInArray(array $array, string $childKey, string $targetKey, mixed $oldValue, mixed $newValue)
    
        Returns an nested associative array such that all array elements have replaced an key value to 
        a new key value only if it is equal to a specific old key value.
        
        :param array $array: The associative array
        :param string $childKey: The associative array
        :param string $targetKey: The target key whose value can be replaced
        :param mixed $oldValue: The old value of the element associated with the target key used to determine if the value should be changed
        :param mixed $newValue: The new value of the element associated with the target key
        :returns: array The replaced associative array