Unclear documentation about snackbar usage on documentation website

Bug, feature request, or proposal:

Documentation: Snackbar component is unclear, and its Plunker code example is not running

Details:

1. It seems the Snackbar component documentation on website does not describe fully about how to open snackbar from component and what to do with MdSnackBarRef in API Reference tab while they are mentioned in Overview tab

2. Plunker example in Examples tab of Snackbar component is not working. Reproduce steps:

   • Initial Plunker example when clicking Edit in Plunker: https://plnkr.co/edit/mH5Hh14TZAD3WH2AlU2x?p=preview
   • Click Pizza Party button, the snackbar does not appear

   Notes:

   • Developer need to add PizzaPartyComponent in declarations and entryComponents of ngModule in main.ts file, plus create new template snack-bar-component-example-snack.html and component stylesheet snack-bar-component-example-snack.css for PizzaPartyComponent.
   • Plunker example: https://plnkr.co/edit/IVRsaVTFRiaHIHGXnhAw?p=preview

3. The documentation does not describe how to execute the action of a component itself if that component is opened in snackbar. In the project source code, I’ve found that to execute the dismiss snackbar action when open snack bar from open method you guys did this:

• Create a self-reference with MdSnackBarRef of the content component: In class SimpleSnackBar, there is snackBarRef: MdSnackBarRef<SimpleSnackBar> property. To be able to dismiss snackbar, SimpleSnackBar component has to call dismiss() method, which in turn calls the _action() method of snackBarRef.
• In open method of MdSnackBar:

open(message: string, action = '', config: MdSnackBarConfig = {}): MdSnackBarRef<SimpleSnackBar> {
    config.announcementMessage = message;
    let simpleSnackBarRef = this.openFromComponent(SimpleSnackBar, config);
    simpleSnackBarRef.instance.snackBarRef = simpleSnackBarRef;
    simpleSnackBarRef.instance.message = message;
    simpleSnackBarRef.instance.action = action;
    return simpleSnackBarRef;
}

At line 4, the snackBarRef of instance SimpleSnackBar of simpleSnackBarRef was assigned to simpleSnackBarRef itself. Therefore, the snackbar component was able to close.

If I want to create a snackbar from a component with a dismiss/arbitrary button, then I have to do the same with my code. However, there is no instruction to do that with openFromComponent method. I think this should be documented clearer so developer can do that from looking at the documentation, not have to dig into the source code. Plunker example: https://plnkr.co/edit/rOql4ebj2d5ynQpzutUW?p=preview

Which versions of Angular, Material, OS, browsers are affected?

Material: 2.0.0-beta1

[pleszczy]

This is a good suggestion. I had to go through the sources of openFromComponent to find out information that should have been in the documentation or in the examples.

[mtpultz]

Docs don’t seem to indicate how to distinguish between action and dismiss using openFromComponent. The only way seems to be to directly invoke the private method _action since both will trigger dismiss.

Might be worth adding to the example code in the docs that the custom component (in this case SimpleSnackBar) should contain onAction and onDismiss methods for invoking this.snackBarRef._action() and this.snackBarRef.dismiss(); to trigger the associated Observable responses.

Seems wrong to use the private method _action, but there isn’t any other available method.

@Component({
  selector: 'app-simple-snackbar',
  templateUrl: './simple-snackbar.component.html',
  styleUrls: ['./simple-snackbar.component.scss']
})
export class SimpleSnackBarComponent {
  public snackBarRef: MdSnackBarRef<SimpleSnackBarComponent>;
  public message: string;
  public action: string;

  public onAction() { this.snackBarRef._action(); }
  public onDismiss() { this.snackBarRef.dismiss(); }
}

<div>
  <p>
    {{ message }}
  </p>

  <button md-button
          color="accent"
          (click)="onAction()">{{ action }}</button>

  <button md-button
          color="accent"
          (click)="onDismiss()">{{ dismiss }}</button>

</div>

Now, subscriptions are propagated through the reference:

const snackBarRef = this.open(...).onAction().subscribe(() => { 
  console.log('action was explicitly clicked');
});
const snackBarRef = this.open(...).afterDismissed().subscribe(() => {  
  console.log('regardless of how the snackbar has been dismissed');
});

This would be over documentation if written into the docs, but would be a good addition to the example code where action or dismiss responses could be bound to template to display a boolean indicating which occurred like other examples in the docs provide.