mathiasbynens / jquery-details Goto Github PK

World’s first <details>/<summary> polyfill™

License: GNU General Public License v2.0

JavaScript 46.57% HTML 53.43%

jquery-details's Introduction

`<details>`/`<summary>` jQuery plugin

This plugin polyfills <details>/<summary> HTML elements and adds the appropriate ARIA annotations for optimal accessibility. More information can be found in my blog post on the subject.

Demo & Examples

http://mathiasbynens.be/demo/html5-details-jquery

Example Usage

In its simplest form:

// Polyfill a given set of elements
$('details').details();

The plugin will automatically detect browser support and act accordingly. If other parts of your code need to know whether <details>/<summary> are supported or not, use $.fn.details.support:

// Detect whether `<details>`/`<summary>` are natively supported
console.log($.fn.details.support ? 'Native support' : 'No native support');
// Conditionally add a classname to the `html` element, based on native support
$('html').addClass($.fn.details.support ? 'details' : 'no-details');

The plugin will provide open.details and close.details events for you to use:

$('details').on({
 'open.details': function() {
    console.log('opened');
  },
  'close.details': function() {
    console.log('closed');
  }
});

Any handlers bound to these events will fire even in browsers that natively support <details>.

Since both events live under the details namespace, you can easily unbind all handlers that are specific to this plugin:

$('details').off('.details');

Notes

The plugin doesn’t require you to add any CSS to your document. It will add a class="open" to any open <details> elements though (in addition to the open attribute), so you can very easily target these using CSS if you want.

This plugin includes my noSelect jQuery plugin.

This plugin automatically feature tests for native <details>/<summary> support and only enables the fallback when it’s necessary. You don’t have to write any feature tests yourself.

This plugin requires jQuery 1.9+. For a version that works with jQuery 1.8 or older, see v0.0.6. For a version that works with jQuery 1.6 or older, see v0.0.1.

This fallback works in all A-grade browsers, including IE6. It will only be executed if the <details> element is not natively supported in the browser. If it isn’t, and JavaScript is disabled, all elements will still be visible to the user.

While the plugin has a certain level of support for <details> elements without a <summary>, it should be noted that omitting the <summary> element results in invalid HTML, and prevents the custom open.details/close.details events from firing in browsers that natively support <details>. Don’t do this!

License

This plugin is dual licensed under the MIT and GPL licenses, just like jQuery itself.

– Mathias

jquery-details's People

Contributors

Stargazers

Watchers

jquery-details's Issues

Can this be animated?

I tried the following:

$(function() {
  $('details').details().on({
    'open.details': function() {
      $(this).contents(':not(summary)').slideDown();
    },

    'close.details': function() {
      $(this).contents(':not(summary)').slideUp();
    }
  });
});

Which animates (if a little weirdly) on open, but not on close because the hide call from the plugin comes before the animate can finish. I'm wondering if there is a better way to do this? Thanks.

Add to jsDeliver

Great plugin. While native browser implementations are growing, there is a good chance native aria semantics will not be properly defined, so I like your explicit aria state definitions. Have you considered adding your plugin to jsDelivr for free CDN support? https://github.com/jimaek/jsdelivr Be glad to do it for you.

Don’t auto-insert <summary> when there isn’t one already

http://www.whatwg.org/specs/web-apps/current-work/multipage/interactive-elements.html#the-details-element:

If there is no child summary element, the user agent should provide its own legend (e.g. “Details”).

Chrome (the only browser with a working <details> implementation) does just that — provide a text legend saying “Details”. This is just a text node, not a child of a summary element.

Consider matching this behavior.

(I hope the spec will change this in the future: https://www.w3.org/Bugs/Public/show_bug.cgi?id=15455)

Add ARIA annotation

http://mathiasbynens.be/notes/html5-details-jquery#comment-7

[Question] Is this available via npm or other version control?

I'd like to add this via version control/asset management, but npm can't seem to find it.

Toggling States Doesn't Work?

Trying to close all other details elements when one is opened, "accordion-style". Have tried this in Chrome:

$('details').details();
$('nav li > details').on('open.details', function() {
    var details = $(this);
    details.parent().siblings().find('details').details('close');
});

as well as the same with .trigger('close.details') and triggerHandler('close.details'). Is this a bug or am I doing something wrong?

[enhancement] Add missing bower.json.

Hey, maintainer(s) of mathiasbynens/jquery-details!

We at VersionEye are working hard to keep up the quality of the bower's registry.

We just finished our initial analysis of the quality of the Bower.io registry:

7530 - registered packages, 224 of them doesnt exists anymore;

We analysed 7306 existing packages and 1070 of them don't have bower.json on the master branch ( that's where a Bower client pulls a data ).

Sadly, your library mathiasbynens/jquery-details is one of them.

Can you spare 15 minutes to help us to make Bower better?

Just add a new file bower.json and change attributes.

{
  "name": "mathiasbynens/jquery-details",
  "version": "1.0.0",
  "main": "path/to/main.css",
  "description": "please add it",
  "license": "Eclipse",
  "ignore": [
    ".jshintrc",
    "**/*.txt"
  ],
  "dependencies": {
    "<dependency_name>": "<semantic_version>",
    "<dependency_name>": "<Local_folder>",
    "<dependency_name>": "<package>"
  },
  "devDependencies": {
    "<test-framework-name>": "<version>"
  }
}

Read more about bower.json on the official spefication and nodejs semver library has great examples of proper versioning.

NB! Please validate your bower.json with jsonlint before commiting your updates.

Thank you!

Timo,
twitter: @versioneye
email: [email protected]
VersionEye - no more legacy software!

doesn't work in IE

when calling details on the jQuery object I get "Unexpected call to method or property access."

Edit: Forgot to include the JS in the head tag not the body

Consider setting the `open` property as well

We’re already setting the attribute, even adding a className — might as well set the property as well.

Demo page is broken

Your demo page is pulling in jQuery 1.9 from the Google CDN. As a result, once you've clicked on an element, you can no longer change its state. Elements which start closed can be opened once and never closed again; elements which start open can be closed once and never opened again.

This seems to be related to the changes around attr/prop handling:
http://jquery.com/upgrade-guide/1.9/#attr-versus-prop-

The following two changes seem to fix the problem:

Line 35: (toggleOpen)
Replace: var isOpen = typeof $details.attr('open') == 'string',
With: var isOpen = $details.prop('open'),

Line 125:
Add: $details.prop('open', typeof $details.attr('open') == 'string');
Before: toggleOpen($details, $detailsSummary, $detailsNotSummary);

Unable to copy text wrapped in the summary

Because of the .noSelect() in line 129 users will be unable to select and copy/paste text in the summary.
I guess this is done to enable keyboard accessability in accordance to WAI?

side-note: i have also chosen to prevent bubble from all $("summary *") and added a toggle-element as the only trigger. (my desired mod of default summary behaviour)

Broken in jQuery 1.10.x

Allow toggling `open` state

LedgeT describes a use case here:

I have a responsive design that requires the details to be closed in one view but open in another. Is it possible to do this based on changing the parent class?

E.g. $(el).details('toggle'); would toggle the open attribute and property, as well as class="open".

Maybe also $(el).details('open') and $(el).details('close').

This could also trigger event handlers:

$el.details();
$el.on('open.details', function() {
  console.log('open');
}).on('close.details', function() {
  console.log('close');
});
$el.details('open'); // opens the element and triggers `open.details`

Support nested <details> elements

Styles

If I don't include styles inside your demo page and make a $('details').details(); this plugin doesn't work in Firefox 21 and Chrome 26. (Although Chrome has native support)

If i include that styles, plugin works in Chrome natively. Plugin works in Firefox but with creating two boxes even I didn't open the details by clicking arrow. All of the details/summary parts have two big boxes around them which makes page unreadable.

Set open attr, not just prop

The spec defines an "open" attribute for showing the details as open/closed -- but only a prop is set by this fill-in, relying on a class fallback for selection/styling

text inputs in summary are non-functional

If an or similar focus-requiring element is a child of a

, it will become unusable. I'm presuming this is because the details' click handler unconditionally redirects focus to the

itself.

Relatedly, checkboxes, radio buttons and selects more-or-less work normally, but also toggle the details state when used.

Demo page doesn't work in IE9

I tried this demo page:
http://mathiasbynens.be/demo/html5-details-jquery

But it doesn't work in IE9.
My user agent is:
Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0; MAAU; MAAU)