MediaWiki:Imelesstay.jsay

Note: After publishing, you may have to bypass your browser's cache to see the changes.

• Firefox / Safari: Hold Shift while clicking Reload, or press either Ctrl-F5 or Ctrl-R (⌘-R on a Mac)
• Google Chrome: Press Ctrl-Shift-R (⌘-Shift-R on a Mac)
• Edge: Hold Ctrl while clicking Refresh, or press Ctrl-F5.

/*
===============================================================================
EXUVIA WIKI - SIDEBAR DROPDOWN MENUS
===============================================================================

This script converts sidebar entries into expandable dropdown menus.

The sidebar is structured like this:

    ** Locations
    *** Continents
    *** Kingdoms
    *** Towns

    ** Religions
    *** The Valor
    *** The Brumal

The script automatically detects this structure.

You do NOT need to add anything to this JavaScript when creating another
dropdown.

For example, adding this to MediaWiki:Sidebar:

    ** Organizations
    *** The Theurgic Knights
    *** ZIMS
    *** YCCC

will automatically create:

    Organizations
        The Theurgic Knights
        ZIMS
        YCCC


===============================================================================
*/


/*
===============================================================================
1. WAIT FOR THE PAGE TO FINISH LOADING
===============================================================================

MediaWiki may load this script before the sidebar has finished being created.

$( function () { ... } );

waits until the page is ready before running the code.

===============================================================================
*/

$( function () {


    /*
    ===========================================================================
    2. FIND THE TIMeless SIDEBAR
    ===========================================================================

    #mw-site-navigation

    is the main navigation area used by Timeless.

    ===========================================================================
    */

    var sidebar = $( '#mw-site-navigation' );


    /*
    If the sidebar cannot be found, stop.

    This prevents JavaScript errors.

    ===========================================================================
    */

    if ( !sidebar.length ) {
        return;
    }


    /*
    ===========================================================================
    3. FIND SIDEBAR SECTIONS
    ===========================================================================

    Timeless puts groups of sidebar links inside "portal" elements.

    We examine every portal separately.

    ===========================================================================
    */

    sidebar.find( '.portal' ).each( function () {

        var portal = $( this );


        /*
        =======================================================================
        4. FIND THE SIDEBAR LIST
        =======================================================================

        Sidebar links are normally contained inside a <ul>.

        ===========================================================================
        */

        var list = portal.find( 'ul' ).first();


        /*
        If there isn't a list, there is nothing to modify.

        ===========================================================================
        */

        if ( !list.length ) {
            return;
        }


        /*
        =======================================================================
        5. LOOK AT EVERY SIDEBAR ITEM
        =======================================================================

        Each sidebar entry is normally an <li>.

        We examine each one to determine whether it should become a dropdown.

        ===========================================================================
        */

        list.children( 'li' ).each( function () {

            var item = $( this );


            /*
            ===================================================================
            6. LOOK FOR CHILD ITEMS
            ===================================================================

            A normal sidebar entry looks like:

                <li>
                    <a>Locations</a>
                </li>

            A dropdown entry needs another list underneath it:

                <li>
                    <a>Locations</a>

                    <ul>
                        <li>
                            <a>Continents</a>
                        </li>
                    </ul>
                </li>

            If the <li> contains another <ul>, it has children.

            ===================================================================
            */

            var childMenu = item.children( 'ul' );


            /*
            ===================================================================
            7. IGNORE NORMAL LINKS
            ===================================================================

            If there isn't a child menu, this is just a normal sidebar link.

            For example:

                ** About
                ** Contact

            Those remain normal links.

            ===================================================================
            */

            if ( !childMenu.length ) {
                return;
            }


            /*
            ===================================================================
            8. FIND THE TOP-LEVEL LINK
            ===================================================================

            This is the link that currently says something like:

                Locations

            We are going to turn this into a button.

            ===========================================================================
            */

            var mainLink = item.children( 'a' );


            /*
            ===================================================================
            9. SAFETY CHECK
            ===================================================================

            If no link exists, there is nothing to turn into a dropdown button.

            ===================================================================
            */

            if ( !mainLink.length ) {
                return;
            }


            /*
            ===================================================================
            10. PREVENT THE MAIN LINK FROM NAVIGATING
            ===================================================================

            The user specifically wants:

                Clicking Locations = open/close menu

            NOT:

                Clicking Locations = go to a Locations page

            preventDefault() prevents the browser from following the link.

            ===================================================================
            */

            mainLink.on( 'click', function ( event ) {

                event.preventDefault();


                /*
                ===============================================================
                11. OPEN OR CLOSE THE DROPDOWN
                ===============================================================

                slideToggle() does exactly what is wanted:

                    closed → open

                    open → closed

                150 means the animation lasts approximately 150 milliseconds.

                ===============================================================
                */

                childMenu.stop( true, true ).slideToggle( 150 );


                /*
                ===============================================================
                12. ACCESSIBILITY INFORMATION
                ===============================================================

                aria-expanded tells screen readers whether the menu is open.

                ===============================================================
                */

                var isOpen = childMenu.is( ':visible' );

                mainLink.attr(
                    'aria-expanded',
                    isOpen ? 'true' : 'false'
                );

            });


            /*
            ===================================================================
            13. MARK THE LINK AS A DROPDOWN
            ===================================================================

            aria-haspopup tells accessibility software that this element
            controls another menu.

            ===================================================================
            */

            mainLink.attr( 'aria-haspopup', 'true' );

            mainLink.attr( 'aria-expanded', 'false' );


            /*
            ===================================================================
            14. ADD A DROPDOWN ARROW
            ===================================================================

            This adds a small visual arrow after the title.

                Locations ▼

            The arrow itself does not affect navigation.

            ===================================================================
            */

            mainLink.append(
                $( '<span>' )
                    .addClass( 'exuvia-dropdown-arrow' )
                    .text( ' ▼' )
            );


            /*
            ===================================================================
            15. HIDE THE CHILDREN WHEN THE PAGE LOADS
            ===================================================================

            Dropdowns start closed.

            The user can open them by clicking the title.

            ===================================================================
            */

            childMenu.hide();


            /*
            ===================================================================
            16. GIVE THE DROPDOWN A CLASS
            ===================================================================

            This lets the CSS identify these menus.

            ===================================================================
            */

            childMenu.addClass( 'exuvia-dropdown-menu' );


            /*
            ===================================================================
            17. MARK THE PARENT ITEM
            ===================================================================

            This gives the parent <li> a class.

            It can be useful for CSS later.

            ===================================================================
            */

            item.addClass( 'exuvia-dropdown-parent' );

        });

    });

} );