docs(drag-drop): add docs and live examples #12794

crisbeto · 2018-08-22T20:47:57Z

Adds live examples and a readme for the CDK drag&drop.

jelbourn

Some text revision suggestions for grammar, passive voice, and brevity.

jelbourn · 2018-08-23T23:20:19Z

src/cdk/drag-drop/drag-drop.md

@@ -1 +1,127 @@
-# TODO
+The `@angular/cdk/drag-drop` module provides you with a way to easily and declaratively create
+drag&drop interfaces, with support for free dragging, sorting within a list, transferring items


So, fun grammar rules around "drag and drop":

When used as an adjective, it should be hyphenated: ...the drag-and-drop features...

When describing an action, it's not hyphenated: ...allows you to drag and drop...

jelbourn · 2018-08-23T23:24:44Z

src/cdk/drag-drop/drag-drop.md

+in addition to horizontal lists and locking along an axis.
+
+### Getting started
+To get started, you have to include the `DragDropModule` in your app's imports and add the


Start by importing `DragDropModule` into the `NgModule` where you want to use drag-and-drop features. You can now add the `cdkDrag` directive to elements to make them draggable. When outside of a `<cdk-drop>` element, draggable elements can be freely moved around the page. You can add `<cdk-drop>` elements to constrain where elements may be dropped.

jelbourn · 2018-08-23T23:49:36Z

src/cdk/drag-drop/drag-drop.md

+
+<!-- example(cdk-drag-drop-overview) -->
+
+### Sorting


Sorting -> Reordering lists

jelbourn · 2018-08-23T23:55:12Z

src/cdk/drag-drop/drag-drop.md

+as the user is dragging. Note that the CDK won't change the data for you, which means that you'll
+have to listen for the `dropped` event and re-arrange the date yourself once the user is done
+dragging. There are some provided utilities like the `moveItemInArray` and `transferArrayItem`
+functions that make it easier to manipulate your data.


Adding `<cdk-drop>` around a set of `cdkDrag` elements groups the draggables into a reorderable collection. Items will automatically rearrange as an element moves. Note that this will *not* update your data model; you can listen to the `dropped` event to update the data model once the user finishes dragging.

I'm wondering if we should expose the moveItemInArray and transferArrayItem functions publicly. I worry that people will start to think that it's the only way to update their model, and then start filing issues requesting things like handling async updates.

I see what you mean, but hopefully people will realize that they're just dealing with arrays. I added the functions since some things like move an item inside an array aren't trivial one-liners.

jelbourn · 2018-08-23T23:55:47Z

src/cdk/drag-drop/drag-drop.md

+
+<!-- example(cdk-drag-drop-sorting) -->
+
+### Sorting between lists


"Sorting between lists" -> "Transferring items between lists"

jelbourn · 2018-08-24T00:10:15Z

src/cdk/drag-drop/drag-drop.md

+* `.cdk-drag-placeholder` - This is element that will be shown instead of the real element as it's
+    being dragged inside a `cdk-drop`. By default this will look exactly like the element that is
+    being sorted.
+* `.cdk-drop-dragging` - A class that is added to `cdk-drop` while the user is dragging an item.


This would probably be good as a table

jelbourn · 2018-08-24T00:11:33Z

src/cdk/drag-drop/drag-drop.md

+<!-- example(cdk-drag-drop-handle) -->
+
+### Customizing the preview element
+By default, when the user starts dragging an item inside a sortable list, the CDK will create a


I would omit the css class here since it's mentioned above.

When a `cdkDrag` element is picked up, it will create a preview element visible while dragging. By default, this will be a clone of the original element positioned next to the user's cursor. This preview can be customized, though, by providing a custom template via `*cdkDragPreview`:

jelbourn · 2018-08-24T00:15:33Z

src/cdk/drag-drop/drag-drop.md

+
+<!-- example(cdk-drag-drop-handle) -->
+
+### Customizing the preview element


"Customizing the drag preview"

jelbourn · 2018-08-24T00:19:54Z

src/cdk/drag-drop/drag-drop.md

+
+### List orientation
+The `cdk-drop` component defaults to sorting lists vertically, however you can make a list that is
+sorted horizontally by setting the `orientation` input to `horizontal`:


The `cdk-drop` component assumes that lists are vertical by default. This can be changed by setting the `orientation` property to `"horizontal".

jelbourn · 2018-08-24T00:20:47Z

src/cdk/drag-drop/drag-drop.md

+<!-- example(cdk-drag-drop-horizontal-sorting) -->
+
+### Restricting movement along an axis
+By default, the CDK allows the user to move the drag preview around freely in both the X and Y axis,


By default, `cdkDrag` allows free movement in all directions. To restrict dragging to a specific axis, you can set `cdkDragLockAxis` on `cdkDrag` or `lockAxis` on `<cdk-drop>` to either `"x"` or `"y"`.

Adds live examples and a readme for the CDK drag&drop.

crisbeto · 2018-08-24T18:08:17Z

I've incorporated the feedback @jelbourn.

jelbourn

LGTM

ngbot · 2018-08-25T15:19:44Z

I see that you just added the pr: merge ready label, but the following checks are still failing:
status "continuous-integration/travis-ci/pr" is failing

If you want your PR to be merged, it has to pass all the CI checks.

If you can't get the PR to a green state due to flakes or broken master, please try rebasing to master and/or restarting the CI job. If that fails and you believe that the issue is not due to your change, please contact the caretaker and ask for help.

angular-automatic-lock-bot · 2019-09-09T12:02:28Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

crisbeto added docs This issue is related to documentation pr: merge safe target: major This PR is targeted for the next major release labels Aug 22, 2018

crisbeto assigned jelbourn Aug 22, 2018

crisbeto requested review from amcdnl and jelbourn as code owners August 22, 2018 20:47

googlebot added the cla: yes PR author has agreed to Google's Contributor License Agreement label Aug 22, 2018

crisbeto force-pushed the drag-drop-docs branch from f99a068 to b244465 Compare August 23, 2018 18:36

jelbourn reviewed Aug 24, 2018

View reviewed changes

docs(drag-drop): add docs and live examples

ba0742d

Adds live examples and a readme for the CDK drag&drop.

crisbeto force-pushed the drag-drop-docs branch from b244465 to ba0742d Compare August 24, 2018 18:07

jelbourn approved these changes Aug 25, 2018

View reviewed changes

jelbourn added pr: lgtm action: merge The PR is ready for merge by the caretaker labels Aug 25, 2018

jelbourn merged commit c8ae9fd into angular:master Aug 25, 2018

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 9, 2019


		<!-- example(cdk-drag-drop-sorting) -->

		### Sorting between lists


		<!-- example(cdk-drag-drop-handle) -->

		### Customizing the preview element

docs(drag-drop): add docs and live examples #12794

docs(drag-drop): add docs and live examples #12794

Uh oh!

Conversation

crisbeto commented Aug 22, 2018

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crisbeto commented Aug 24, 2018

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

ngbot bot commented Aug 25, 2018

Uh oh!

angular-automatic-lock-bot bot commented Sep 9, 2019

Uh oh!

Uh oh!