Very confusing sentences around preventDefault

[sonic1981]

Current Behavior

On the page https://guides.emberjs.com/v3.8.0/templates/actions/ there is the following text:

By default, the {{action}} helper prevents the default browser action of the DOM event. If you want to allow the browser action, you can stop Ember from preventing it.

For example, if you have a normal link tag and want the link to bring the user to another page in addition to triggering an ember action when clicked, you can use preventDefault=false:

<a href="newPage.htm" {{action "logClick" preventDefault=false}}>Go</a>

With preventDefault=false omitted, if the user clicked on the link, Ember.js will trigger the action, but the user will remain on the current page.

With preventDefault=false present, if the user clicked on the link, Ember.js will trigger the action and the user will be directed to the new page.

This is extremely confusing. I actually had to knockup a test program to understand what it was trying to say. TBF, this functionality is very confusing also but lets park that

Possible Solution

Illustrate this using examples:

By default, the {{action}} helper prevents the default browser action of the DOM event. So the following standard link:

<a href="newPage.htm" {{action "logClick"}}>Go</a>

Clicking on this link does not go to newPage.htm because the action has overridden this functionality. This is the default behaviour for Ember.

You can override this behaviour and make this work more like a standard non-ember anchor tag by using the preventDefault=false overload of the action on a a tag. For example:

<a href="newPage.htm" {{action "logClick" preventDefault=false}}>Go</a>

This still triggers the logClick action but then we also go to newPage.htm. .

You can specify preventDefault=true and this reverts to the standard Ember functionality (see previous example).

[locks]

Tracking issue in PR, since it is not possible to transfer issues across organizations. Thanks for the help!