Docs updates

Starting to document the new drag and drop stuff

editions/tw5.com/tiddlers/concepts/Order of Tagged Tiddlers.tid

@@ -1,5 +1,5 @@
 created: 20150124125646000
-modified: 20150917193522589
+modified: 20170328161702062
 tags: Tagging
 title: Order of Tagged Tiddlers
 type: text/vnd.tiddlywiki
@@ -14,3 +14,5 @@ When ~TiddlyWiki generates a list of the tiddlers that have a particular tag (e.
 # In each remaining tiddler <<.place T>>, look for a <<.field list-after>> field. If this has a tiddler title as its value, place tiddler <<.place T>> just <<.em after>> that one.
 
 # If any tiddlers still remain, place them at the end of the list in ascending alphabetical order of title. The difference between capital and lowercase letters is ignored.
+
+The ordering of tiddlers with a particular tag can be directly modified using drag and drop within a tag pill dropdown. The underlying [[list-tagged-draggable Macro]] can also be used elsewhere.

editions/tw5.com/tiddlers/features/Drag and Drop.tid

@@ -0,0 +1,29 @@
+created: 20170328143119836
+modified: 20170328173846754
+tags: Features
+title: Drag and Drop
+type: text/vnd.tiddlywiki
+
+~TiddlyWiki uses drag and drop to power two separate features:
+
+* [[Importing Tiddlers]] into ~TiddlyWiki 
+* Manipulating tiddlers within a ~TiddlyWiki 
+
+Tiddler manipulation via drag and drop is supported by the core user interface in the following contexts:
+
+* Entries in the "Open" tab of the sidebar can be reordered by drag and drop; new tiddlers can be opened by dragging their titles into the list
+* Entries within a tag pill dropdown can be reordered by drag and drop; new tiddlers can be assigned the tag by dragging their titles into the list
+* Entries in the [[control panel|$:/ControlPanel]] "Appearance"/"Toolbars" tab can be reordered by drag and drop. (Less usefully, new entries can be added to the toolbars by dragging their titles into the list)
+
+All tiddler links are draggable by default. They can be dragged within a browser window for manipulating tiddlers, or dragged to a different browser window to initiate an [[import operation|Importing Tiddlers]]
+
+Tag pills are also draggable, and are equivalent to simultaneously dragging all of the individual tiddlers carrying the tag.
+
+Some common scenarios for drag and drop tiddler manipulation are available as reusable macros:
+
+* [[list-links-draggable Macro]] for reordering the entries in a tiddler ListField
+* [[list-tagged-draggable Macro]] for reordering the tiddlers that carry a specified tag
+
+See DragAndDropMechanism for details of how to use the low level drag and drop primitives to build more complex interactions.
+
+The standard HTML 5 drag and drop APIs used by ~TiddlyWiki are not generally available on mobile browsers on smartphones or tablets. The [[Mobile Drag And Drop Shim Plugin]] adds an open source library that implements partial support on many mobile browsers, including iOS and Android.

editions/tw5.com/tiddlers/features/ImportTiddlers.tid

@@ -1,12 +0,0 @@
-created: 20130825162000000
-modified: 20170317133552128
-tags: Features
-title: ImportTiddlers
-type: text/vnd.tiddlywiki
-
-You can import content into a TiddlyWiki file in several ways:
-
-* Use the {{$:/core/images/import-button}} ''import'' button (under the ''Tools'' tab in the sidebar) to select a local file
-* Drag and drop files from Windows Explorer or OS X Finder etc. into the TiddlyWiki browser window
-* Paste content directly from the clipboard using the menu or keyboard shortcut (control-V or command-V)
-** Currently supported in Chrome, Firefox and Edge (but not Internet Explorer)

editions/tw5.com/tiddlers/features/Importing Tiddlers.tid

@@ -0,0 +1,26 @@
+created: 20130825162000000
+modified: 20170328160211362
+tags: Features
+title: Importing Tiddlers
+type: text/vnd.tiddlywiki
+
+You can import tiddlers into a ~TiddlyWiki from external files or directly from another ~TiddlyWiki.
+
+!! Importing content from external files
+
+There are several ways to import content from external files:
+
+* Use the {{$:/core/images/import-button}} ''import'' button (under the ''Tools'' tab in the sidebar) to select a local file
+* Drag and drop files from Windows Explorer or OS X Finder etc. into the TiddlyWiki browser window
+* Paste content directly from the clipboard using the menu or keyboard shortcut (<kbd>ctrl-V</kbd> or <kbd>cmd-V</kbd>)
+** Currently supported in Chrome, Firefox and Edge (but not Internet Explorer)
+
+Most files are imported as individual tiddlers. The exceptions are:
+
+* ''.html'' files that are recognised as a ~TiddlyWiki file are parsed to extract the tiddlers within them
+* ''.json'' files are parsed to extract the tiddlers within them. They can be created by [[exporting them|How to export tiddlers]] from another ~TiddlyWiki. ~TiddlyWiki accepts JSON files that contain either a single tiddler fields object, or an array of tiddler fields objects
+
+!! Importing content from other ~TiddlyWiki browser windows
+
+Tiddlers can be imported from other ~TiddlyWiki browser windows via [[Drag and Drop]]. Drag a tiddler link or tag from one ~TiddlyWiki browser window to another. Dragging a link will import a single tiddler while dragging a tag pill will import all of the tiddlers that carry that tag.
+

editions/tw5.com/tiddlers/macros/examples/list-links-draggable Macro (Examples).tid

@@ -0,0 +1,7 @@
+created: 20170328211011767
+modified: 20170328211211799
+tags: [[list-links-draggable Macro]] [[Macro Examples]]
+title: list-links-draggable Macro (Examples)
+type: text/vnd.tiddlywiki
+
+<$macrocall $name=".example" n="1" eg="""<<list-links-draggable tiddler:"Days of the Week">>"""/>

editions/tw5.com/tiddlers/macros/list-links-draggable Macro.tid

@@ -0,0 +1,29 @@
+caption: list-links-draggable
+created: 20170328204925306
+modified: 20170328210923128
+tags: Macros [[Core Macros]]
+title: list-links-draggable Macro
+type: text/vnd.tiddlywiki
+
+The <<.def list-links-draggable>> [[macro|Macros]] renders the links in a ListField of a tiddler as a list that can be reordered via [[drag and drop|Drag and Drop]].
+
+!! Parameters
+
+;tiddler
+: The title of the tiddler containing the list
+;field
+: The name of the field containing the list (defaults to `list`)
+;type
+: The element tag to use for the list wrapper (defaults to `ul`)
+;subtype
+: The element tag to use for the list items (defaults to `li`)
+;class
+: Optional space separated classes to add to the wrapper element
+;itemTemplate
+: Optional title of a tiddler to use as the template for rendering list items.
+
+If the `itemTemplate` parameter is not provided then the list items are rendered as simple links.
+
+Within the item template, the [[currentTiddler Variable]] refers to the current list item.
+
+<<.macro-examples "list-links-draggable">>

editions/tw5.com/tiddlers/mechanisms/DragAndDropMechanism.tid

@@ -0,0 +1,37 @@
+created: 20170328161210552
+modified: 20170328204148733
+tags: [[Importing Tiddlers]] [[Drag and Drop]] Mechanisms
+title: DragAndDropMechanism
+type: text/vnd.tiddlywiki
+
+This tiddler discusses the internal mechanisms that are used to implement drag and drop features in ~TiddlyWiki. See [[Drag and Drop]] for a general description of the features.
+
+<<.warning """
+~TiddlyWiki uses the [[standard HTML 5 drag and drop APIs|https://www.w3.org/TR/2010/WD-html5-20101019/dnd.html]]. However, this is an area that is rightly notorious for cross-browser compatibility problems. Therefore, some features that you might expect to work won't necessarily work in all browsers. In particular, 
+""">>
+
+The following widgets are concerned with drag and drop features:
+
+* The DraggableWidget creates a draggable element that represents one or more tiddlers for dragging
+** The ButtonWidget and LinkWidget incorporate the functionality of the DraggableWidget
+* The DroppableWidget creates an area into which tiddlers can be dragged to trigger customisable actions
+* The DropzoneWidget handles importing external tiddlers from files or by drag and drop from another browser window
+
+The general sequence of a drag and drop operation is as follows:
+
+# The user clicks down and drags the pointer on a draggable element such as the DraggableWidget, ButtonWidget or LinkWidget
+# The draggable element moves with the mouse pointer until the click is released
+# Moving the pointer over droppable elements such as the DroppableWidget displays a highlight indicating that the item can be dropped
+# The configured actions are performed if the drag ends on a droppable element
+
+There is an additional complexity in the shape of "[[drop effects|https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API/Drag_operations#drageffects]]":
+
+* The available effects and their meanings are:
+** ''move'': the item will be moved from the source location to the the drop location
+** ''copy'': the item will be copied from the source location to the the drop location
+** ''link'': some form of relationship or connection will be created between the source and drop locations
+* Draggable items can indicate which effects are allowed when they are dragged
+* Browsers choose which effect to use from those allowed, typically according to modifier keys:
+** the ''control'' key switches to a link operation
+** the ''shift'' key switches to a move operation
+* Droppable items can indicate which effects they will accept

editions/tw5.com/tiddlers/plugins/Mobile Drag And Drop Shim Plugin.tid

@@ -0,0 +1,7 @@
+created: 20170328173820802
+modified: 20170328174328792
+tags: OfficialPlugins
+title: Mobile Drag And Drop Shim Plugin
+type: text/vnd.tiddlywiki
+
+The Mobile Drag And Drop Shim Plugin provides a "shim" that enables HTML 5 compatible drag and drop operations on mobile browsers, including iOS and Android. The shim was created by Tim Ruffles and is published at https://github.com/timruffles/ios-html5-drag-drop-shim.

editions/tw5.com/tiddlers/plugins/SaveTrail Plugin.tid

@@ -1,7 +1,7 @@
 created: 20170210074840860
-modified: 20170210075100387
+modified: 20170328173912704
 tags: OfficialPlugins
-title: SaveTrailPlugin
+title: SaveTrail Plugin
 type: text/vnd.tiddlywiki
 
 This plugin causes TiddlyWiki to continuously download (as a JSON file) the contents of any tiddler that is manually changed by any of several means:

editions/tw5.com/tiddlers/plugins/Twitter Plugin.tid

@@ -1,7 +1,7 @@
 created: 20170227223209558
-modified: 20170227223706297
+modified: 20170328173919702
 tags: OfficialPlugins
-title: TwitterPlugin
+title: Twitter Plugin
 type: text/vnd.tiddlywiki
 
 This plugin adds a `<$twitter>` widget that can embed a variety of entities from twitter.com:

editions/tw5.com/tiddlers/styleguide/Typography.tid

@@ -1,7 +1,6 @@
 created: 20141226192500000
 modified: 20150117152559000
 title: Typography
-tags: documenting
 
 Use the [[documentation macros|Documentation Macros]] to keep the text maintainable in the face of change.
 

editions/tw5.com/tiddlers/widgets/BrowseWidget.tid

@@ -1,12 +1,13 @@
-title: BrowseWidget
-created: 201310241419
-modified: 20141202155353547
-tags: Widgets
 caption: browse
+created: 20131024141900000
+modified: 20170328173406681
+tags: Widgets
+title: BrowseWidget
+type: text/vnd.tiddlywiki
 
 ! Introduction
 
-The browse widget displays an HTML file browser button that allows the user to choose one or more files to import. It sends a [[WidgetMessage: tm-import-tiddlers]] carrying a JSON representation of the tiddlers imported from the files up through its parents. This message usually trapped by the NavigatorWidget which adds the tiddlers to the store and updates the story to display them.
+The browse widget displays an HTML file browser button that allows the user to choose one or more files to import. It sends a [[WidgetMessage: tm-import-tiddlers]] carrying a JSON representation of the tiddlers imported from the files up through its parents. This message is usually handled by the NavigatorWidget which adds the tiddlers to the store and updates the story to display them.
 
 ! Content and Attributes
 

editions/tw5.com/tiddlers/widgets/DropzoneWidget.tid

@@ -1,8 +1,9 @@
-title: DropzoneWidget
-created: 201310241419
-modified: 201310300837
-tags: Widgets
 caption: dropzone
+created: 20131024141900000
+modified: 20170328173334805
+tags: Widgets
+title: DropzoneWidget
+type: text/vnd.tiddlywiki
 
 ! Introduction
 

editions/tw5.com/tiddlers/widgets/LinkWidget.tid

@@ -1,8 +1,9 @@
-title: LinkWidget
-created: 201310241419
-modified: 20150228144334000
-tags: Widgets
 caption: link
+created: 20131024141900000
+modified: 20170328172846359
+tags: Widgets
+title: LinkWidget
+type: text/vnd.tiddlywiki
 
 The `link` widget generates links to tiddlers. (Use the HTML `<a>` element to generate external links).
 
@@ -16,7 +17,7 @@ The `link` widget generates links to tiddlers. (Use the HTML `<a>` element to ge
 |draggable |"yes" to enable the link to be draggable (defaults to "yes") |
 |tag |Optional tag to override the default "a" element |
 
-The content of the link widget is rendered within the `<a>` tag.
+The content of the link widget is rendered within the `<a>` tag. The draggable functionality is equivalent to using the DraggableWidget with the ''tiddler'' attribute set to the link target.
 
 The default value of the tooltip attribute is supplied by the <<.vlink tv-wikilink-tooltip>> variable.
 

editions/tw5.com/tiddlers/workingwithtw/Sharing your tiddlers with others.tid

@@ -1,5 +1,5 @@
 created: 20140908163900000
-modified: 20160610074043190
+modified: 20170328142732658
 tags: Learning
 title: Sharing your tiddlers with others
 type: text/vnd.tiddlywiki
@@ -11,6 +11,6 @@ There are a number of ways that people can share tiddlers:
 **A link to the URL of the file itself
 **A permalink ({{$:/core/images/permalink-button}}) to a specific tiddler (see [[PermaLinks]])
 **A permaview ({{$:/core/images/permaview-button}}) link of all the currently open tiddlers (see [[PermaView]])
-*You can grab tiddlers from ~TiddlyWikis that others have published online by clicking on a link to the tiddler within their file, and then dragging and dropping the link into your own file. An import tiddler will appear, and you can click to import the tiddler or tiddlers to your file. (see [[ImportTiddlers]])
+*You can grab tiddlers from ~TiddlyWikis that others have published online by clicking on a link to the tiddler within their file, and then dragging and dropping the link into your own file. An import tiddler will appear, and you can click to import the tiddler or tiddlers to your file (see [[Importing Tiddlers]])
 * You can [[share a Dropbox link to your TiddlyWiki|Sharing a TiddlyWiki on Dropbox]]
 * You can [[export tiddlers|How to export tiddlers]] ({{$:/core/images/export-button}}) in a variety of formats including text, static HTML, comma separated values (ie spreadsheet compatible)