Pre-1.0 <md-dialog> breaking change

[asyncliz]

<md-dialog> has an upcoming breaking change to align its API with the native <dialog> element before our 1.0 launch.

Here is an example of a simple dialog with the new API.

<md-dialog>
  <div slot="headline">A simple dialog</div>
  <form id="form" method="dialog" slot="content">
    This is a dialog with text content.
  </form>
  <div slot="actions">
    <md-text-button form="form" value="close">Close</md-text-button>
    <md-text-button form="form" value="ok">OK</md-text-button>
  </div>
</md-dialog>

Follow these steps to upgrade:

1. Use a single slot="content" root instead of default content.

  <md-dialog>
+   <div slot="content">
      <p>Dialog content</p>
      <p>Additional content</p>
+   </div>
  </md-dialog>

2. Use a single slot="actions" root instead of multiple slot="footer" elements.

  <md-dialog>
-   <button slot="footer">Close</button>
-   <button slot="footer">OK</button>
+   <div slot="actions">
+     <md-text-button>Close</md-text-button>
+     <md-text-button>OK</md-text-button>
+   </div>
  </md-dialog>

3. Use a single slot="headline" and slot="icon" instead of slot="header", slot="headline-prefix", and slot="headline-suffix" elements.

  <md-dialog>
-   <div slot="headline-prefix"><md-icon>event</md-icon></div>
-   <div slot="headline">Dialog title</div>
-   <div slot="headline-suffix">
-     <md-icon-button>close</md-icon-button>
-   </div>
+   <div slot="icon"><md-icon>event</md-icon></div>
+   <div slot="headline">
+     <span style="flex: 1">Dialog title</span>
+     <md-icon-button>close</md-icon-button>
+   </div>
    <div slot="content">
      <p>Dialog content</p>
      <p>Additional content</p>
    </div>
  </md-dialog>

4. Use the autofocus attribute instead of dialog-focus. The first focusable child will be focused if none have autofocus.

  <md-dialog>
    <div slot="content">Content</div>
    <div slot="actions">
      <md-text-button>Close</md-text-button>
-     <md-text-button dialog-focus>OK</md-text-button>
+     <md-text-button autofocus>OK</md-text-button>
    </div>
  </md-dialog>

4. Use <form method="dialog"> to semantically handle closing instead of dialog-action. Add a value="return-value" attribute to determine which button closed the dialog (read with dialog.returnValue).

 <md-dialog>
-   <div slot="content">Content</div>
+   <form slot="content" id="form-id" method="dialog">Content</form>
    <div slot="actions">
-     <md-text-button dialog-action="close">Close</md-text-button>
-     <md-text-button dialog-action="ok">OK</md-text-button>
+     <md-text-button form="form-id" value="close">Close</md-text-button>
+     <md-text-button form="form-id" value="ok">OK</md-text-button>
    </div>
  </md-dialog>

5. Remove footerHidden. If there are no slotted actions, it will not be shown.

- <md-dialog footer-hidden>
+ <md-dialog>
    <div slot="content">Content</div>
  </md-dialog>

6. Listen to open and close events instead of opening and closing. Both events are cancelable. The opened and closed events still fire.

 <md-dialog 
-  @opening=${this.checkIfShouldOpen}
+  @open=${this.checkIfShouldOpen}
   @opened=${this.handleOpened}
-  @closing=${this.checkIfShouldClose}
+  @close=${this.checkIfShouldClose}
   @closed=${this.handleClosed}
 >...</md-dialog>

7. Use CSS margin to change the layout spacing of a dialog instead of custom properties. Use margin on the <md-dialog> itself to change its position on the screen.

 <style>
-  md-dialog {
-    --md-dialog-container-block-padding: 16px;
-    --md-dialog-container-block-padding: 16px;
-    --md-dialog-container-inset-block-start: 64px;
-  }
+  md-dialog {
+    margin-top: 64px;
+  }
+
+  [slot="content"] {
+    margin: 16px;
+  }
 </style>

[treeder]

What's the best way to close the dialog now when a user clicks ok or cancel button in actions slot? Doesn't auto close anymore like it did with dialog-actions even if I use the form method="dialog" thing.

[asyncliz]

Add a id="form-id" attribute to your form and reference it with form="form-id" attributes on the buttons ("form-id" can be anything).

Why? By default in HTML, buttons must be children of a <form> to submit it. Buttons that aren't children can reference the form they submit with a form="id-ref" attribute.

This allows form buttons to be in separate sections of a page than the <form> itself, which is useful for styling.

That's the declarative way to handle closing. However, adding click listeners and closing with dialog.close() or dialog.open = false are just as good!

[treeder]

Should returnValue work without having a form? Doesn't appear to.

[asyncliz]

Not automatically, no. If not using a form and declarative setup, you can programmatically open, close, and customize the return value for dialogs