Updated ngAria API Docs and Developer Guide

[marcysutton]

This PR contains updates to the ngAria API documentation as well as the Developer Guide.

@caitp @btford the more thorough examples and explanations are in the Developer Guide: is there enough detail in the API doc portion?

[caitp]

So, we can have runnable examples in the docs pages, there are examples of this, eg https://github.com/angular/angular.js/blob/master/src/Angular.js#L664-L698 which will be rendered as an iframe with a little mini-application, it's kinda nice.

I think it would be good to do something like this with the ngAria examples (and maybe also include a little snippet informing people how to enable accessibility features to try them with).

The content itself looks great, I just feel like the "show and tell" style examples are better for people

[marcysutton]

@caitp great! I'll work those in, thanks for the prompt suggestion!

[marcysutton]

@caitp the thing to look at with ngAria is the attributes it spits out... I wrote a directive that prints the affected markup, but I think it's less clear if the directive itself is exposed to developers. See this code:

<style>
  md-checkbox {
    background-color: black;
    color: white;
  }
  pre {
    white-space: pre-wrap;
  }
</style>
<div print-markup>
<form>
<md-checkbox ng-model="user.subscribe" required>
  Fake Checkbox
</md-checkbox>
</form>
<div id="output"></div>
</div>
<script>
angular.module('ngAria_ngModelExample', ['ngAria'])
.directive('printMarkup', function() {
  return {
    restrict: 'A',
    link: function($scope, $el, $attrs) {
      var form = $el[0].querySelector('form');
      $el[0].querySelector('#output').innerHTML = '<pre>' +
        form.innerHTML.replace(/&/g, '&amp;').replace(/</g, '&lt;') +
      '</pre>';
    }
  }
});
</script>

Which outputs:

Fake Checkbox
 <md-checkbox ng-model="user.subscribe" required="" class="ng-pristine ng-untouched ng-valid" tabindex="0">
   Fake Checkbox
 </md-checkbox>

Is there any precedent for including directives that aren't shown in the example?

[marcysutton]

@caitp @btford I added a few runnable examples to the Developer Guide. I didn't add them for every directive...that seemed like overkill. I'll defer to you on whether the live examples I added are actually useful. I have an outstanding question about how the runnable examples are set up––see my previous comment. I can always revert those two to plain HTML if that means we can get this thing merged in sooner.

One issue: the "ngClick and ngDblclick" section in the Developer Guide for some reason won't produce HTML from Markdown. I can't figure out why. The accompanying heading prints out "###Example" no matter what.

Thanks!

[caitp]

The show-attrs directive doesn't seem to be working in this one when I run it

[marcysutton]

@caitp thanks for the great feedback! I hooked up the checkboxes and made the two examples a little more thorough. I think it will be helpful to see an accessible custom control in action (like <div role="checkbox">). Let me know if you think this is good to go!

[caitp]

Very cool! It's getting there --- the last thing is that innerText is no longer functional in firefox, so it might be wise to just use jQuery.text() instead --- to make the showAttrs directive work properly in multiple browsers.

Other than that, looks awesome

[marcysutton]

Ahh! I didn't realize jQuery was an option. I'm just fixing the keyboard accessibility and I'll have an update shortly.

[marcysutton]

Alright @caitp, I posted an update using textContent instead of innerText. Does that work? jQuery is not loaded on that page by default, as far as I can tell (without extensive snooping).

[caitp]

Alright @caitp, I posted an update using textContent instead of innerText. Does that work? jQuery is not loaded on that page by default, as far as I can tell (without extensive snooping).

jqLite is there if jQuery isn't --- but it doesn't matter a whole lot, it's fine either way. Could probably make it a bit smaller using jquery instead of pure DOM apis though.
I will try it in FF and land if it looks good.

Do you guys think material is stable enough at this point to be used for the docs app? It would be really nice to showcase it in the angularjs docs. Might be worth filing a separate issue to track doing that if people agree with me that it's a good idea.

[caitp]

So, the second demo is still broken in FF, I haven't dug in to figure out why, but it seems to be working well on Chromium --- might just be a gecko bug. It should be reproducible for them once the docs are landed, so I'll land it now

[marcysutton]

@caitp I just pushed an update, there were multiple keypress events bound. Maybe that fixed it.

As far as Material goes, as soon as we have an official distribution channel we will be able to discuss that. There have been breaking changes in the past 2 milestones, so I personally don't think we're there yet. But, a project incorporating Material into the Angular docs would take time, so I'm sure by the time it is finished the API will be stabilized.

[caitp]

Yup, the fix looks good now :)