From fdf27c8e02fcbe0591329d5dfcfb29eee3f58759 Mon Sep 17 00:00:00 2001
From: Adam Wagner <wbadam@users.noreply.github.com>
Date: Wed, 22 Feb 2017 10:41:12 +0200
Subject: Add javadoc warning and example for criteria scripts (#8643)

* Add javadoc warning and example for criteria scripts (#8521)
---
 .../com/vaadin/event/dnd/DropTargetExtension.java  | 42 ++++++++++++++++++++++
 1 file changed, 42 insertions(+)

(limited to 'server/src')

diff --git a/server/src/main/java/com/vaadin/event/dnd/DropTargetExtension.java b/server/src/main/java/com/vaadin/event/dnd/DropTargetExtension.java
index 4fdd606eb5..e6f1fe1214 100644
--- a/server/src/main/java/com/vaadin/event/dnd/DropTargetExtension.java
+++ b/server/src/main/java/com/vaadin/event/dnd/DropTargetExtension.java
@@ -83,6 +83,22 @@ public class DropTargetExtension<T extends AbstractComponent> extends
      * Sets criteria to allow dragover event on the current drop target. The
      * script executes when dragover event happens and stops the event in case
      * the script returns {@code false}.
+     * <p>
+     * <b>IMPORTANT:</b> Construct the criteria script carefully and do not
+     * include untrusted sources such as user input. Always keep in mind that
+     * the script is executed on the client as is.
+     * <p>
+     * Example:
+     * <pre>
+     *     target.setDropCriteria(
+     *         // If dragged source contains a URL, allow it to be dragged over
+     *         "if (event.dataTransfer.types.includes('text/uri-list')) {" +
+     *         "    return true;" +
+     *         "}" +
+     *
+     *         // Otherwise cancel the event"
+     *         "return false;");
+     * </pre>
      *
      * @param criteriaScript
      *         JavaScript to be executed when dragover event happens or {@code
@@ -94,10 +110,36 @@ public class DropTargetExtension<T extends AbstractComponent> extends
         }
     }
 
+    /**
+     * Returns the criteria for allowing dragover event on the current drop
+     * target.
+     *
+     * @return JavaScript that executes when dragover event happens.
+     */
+    public String getDragOverCriteria() {
+        return getState(false).dragOverCriteria;
+    }
+
     /**
      * Sets criteria to allow drop event on the current drop target. The script
      * executes when drop event happens and stops the event in case the script
      * returns {@code false}.
+     * <p>
+     * <b>IMPORTANT:</b> Construct the criteria script carefully and do not
+     * include untrusted sources such as user input. Always keep in mind that
+     * the script is executed on the client as is.
+     * <p>
+     * Example:
+     * <pre>
+     *     target.setDropCriteria(
+     *         // If dragged source contains a URL, allow it to be dropped
+     *         "if (event.dataTransfer.types.includes('text/uri-list')) {" +
+     *         "    return true;" +
+     *         "}" +
+     *
+     *         // Otherwise cancel the event"
+     *         "return false;");
+     * </pre>
      *
      * @param criteriaScript
      *         JavaScript to be executed when drop event happens or {@code null}
-- 
cgit v1.2.3