custom-context-menu

Custom Context Menu

Create custom styled, unlimited nested Context Menues on your site. No dependencies. Less than 2kB (gzipped and minified).

Content

1. Installation
2. Usage
   • Nested Context Menues
3. Documentation
4. Contribution

Installation

1. Using the NPM or Yarn:

   $ npm install custom-context-menu --save
   

   $ yarn add custom-context-menu
   

2. Standalone

   Download the preferable version of this package and include the cm.js file as an external script:

   <script src="cm.js"></script>
   

Usage

All you have to do in order to get your custom context menu working is just invoke the new ContextMenu() constructor passing to it the target element as a first argument and an object of parameters as a second one:

new ContextMenu(document, {
    transfer: false, // do not transfer the Context Menu if it doesn't fit on the page. Istead, draw it right in the corner
    overlay: true, // use overlay so the user can't interact with the rest of the page while the Context Menu is opened
    defaultOnAlt: false, // pretend the default (browser's) Context Menu to be opened even if user was holding the `alt` key when invoked the Context Menu
    noRecreate: true, // do not open another Context Menu after the first one has been closed via rightclick

    items: [ // the items of your menu
        { // each item is an object
            title: "Menu Item",
            function: function() {
                alert("It's alive!");
            },
        }

        "divider", // except of "special", ones

        {
            title: "Another Menu Item", // the text of the item displayed on the page
            function: makeSomethingAwesome // and a function that is gonna take place when the user picked an item
        }
    ]
});

The only mandatory property that is must present in the params object (the second argument passed to the ContextMenu constructor) is items, that is an array of items your context menu consists of.

You can assign this invokation to the variable:

var fallbackContextMenu = new ContextMenu(document, {
    // params
});

In this case you'll be able to reassign certain params and to manually close the context menu:

fallbackContextMenu.params.transfer = true;
fallbackContextMenu.params.defaultOnAlt = true;

fallbackContextMenu.close();

Learn more about target and params. There is also more about the items.

Nested Context Menues

This tool allows you to create nested context menues. Unlimited amount of nested context menues to be exact. All you have to do to make one menu item open another context menu is just make it's function propery equal to the ContextSubMenu instance:

var subMenu = new ContextSubMenu({
    // params
});

new ContextMenu(document, {
    items: [
        {
            title: "Nested Context Menu",
            function: subMenu// here is where the magic happens
        }
    ]
});

or you can even invoke the constructor right on the fly:

new ContextMenu(document, {
    items: [
        {
            title: "Nested Context Menu",
            function: new ContextSubMenu({
                // params
            })
        }
    ]
});

The main difference between ContextMenu and ContextSubMenu constructors is that the first one takes 2 arguments, while the second one takes only one argument - the object, containing params for the submenu. This difference is due to the fact that we exactly know which element causes the submenu to be opened (we can't say the same about the "usual" context menu - the rightclick can happen anywhere on the page).

Notice also, that the ContextSubMenu has it's own list of params (nevertheless some of them a common).

Here is the other example. This time there is the submenu in the submenu. Take a look, everything is straitforward, just as you might have been expected:

new ContextMenu(document, {
    items: [
        {
            title: "Nested Context Menu",
            function: new ContextSubMenu({
                items: [
                    {
                        title: "Even deeper nested Context Menu",
                        function: new ContextSubMenu({
                            // params
                        })
                    }
                ]
            })
        }
    ]
});

But don't forget the main rule: do not make things more complicated than it's needed. It's unlikely that the users of your site will thank you for the 10-level deep nesting of the context menu. By the way, ths doesn't even look pretty in the code, does it?

Documentation

You can find all the documentation at this tool's site (not yet to be honest). There you can learn everything from the target elements to the styling and animation.

Contribution

I don't currently have any contribution manifest nor styleguides. Nevertheless, I'm open for any kind of contribution you can offer. So don't be shy to open an issue or to make a pull request :sparkles:. Also, you can always contact me if you are unsure about what you can do to make this project better.