From 610191b5444152e78aa129ea0c12d9ae5aea7629 Mon Sep 17 00:00:00 2001 From: thuongvu Date: Wed, 11 Jun 2014 17:23:56 -0700 Subject: [PATCH] docs: edit scrollview touchend move start view --- dist/famous-angular.js | 587 +++++++++++------- docs/unstable/directive/faApp/index.md | 6 +- docs/unstable/directive/faClick/index.md | 22 +- docs/unstable/directive/faIndex/index.md | 1 + docs/unstable/directive/faRenderNode/index.md | 37 +- docs/unstable/directive/faScrollView/index.md | 148 +++-- docs/unstable/directive/faTouchend/index.md | 54 +- docs/unstable/directive/faTouchmove/index.md | 60 +- docs/unstable/directive/faTouchstart/index.md | 59 +- docs/unstable/directive/faView/index.md | 39 +- famous-angular-docs | 2 +- src/scripts/directives/fa-app.js | 8 +- src/scripts/directives/fa-click.js | 29 +- src/scripts/directives/fa-index.js | 1 + src/scripts/directives/fa-render-node.js | 1 + src/scripts/directives/fa-scrollview.js | 284 +++++---- src/scripts/directives/fa-touchend.js | 75 ++- src/scripts/directives/fa-touchmove.js | 80 ++- src/scripts/directives/fa-touchstart.js | 79 ++- src/scripts/directives/fa-view.js | 30 +- 20 files changed, 982 insertions(+), 620 deletions(-) diff --git a/dist/famous-angular.js b/dist/famous-angular.js index 45584152..eed85846 100644 --- a/dist/famous-angular.js +++ b/dist/famous-angular.js @@ -914,12 +914,18 @@ angular.module('famous.angular') * Declaring multiple fa-app's within a page is permitted, but each new one incurs a penalty to performance, and `fa-app`'s should definitely not be declared within an ng-repeat. * * ### Fa-app must be declared with a height & width - * The element fa-app is declared within must have a height and width styling, declared inline or as a css declaration in an external stylesheet. + * The element `fa-app` is declared within must have a set height and width styling, declared inline or as a css declaration in an external stylesheet. * ```html * * * * ``` + * If `fa-app` is declared as an attribute of another element, that element must be a `display:block` element, such as a `div` or `p`. + * ```html + *
+ * + *
+ * ``` */ angular.module('famous.angular') @@ -1023,7 +1029,8 @@ angular.module('famous.angular') * * ``` * @example - * `Fa-click` is most commonly used on a `fa-surface`'. Internally, a Famous Surface has a `".on()"` method that binds a callback function to an event type handled by that Surface. + * ### Fa-click on an fa-surface + * `Fa-click` can be used on an `fa-surface`. Internally, a Famous Surface has a `.on()` method that binds a callback function to an event type handled by that Surface. * The function expression bound to `fa-click` is bound to that `fa-surface`'s click eventHandler, and when the `fa-surface` is clicked, the function expression will be called. * * ```html @@ -1037,6 +1044,32 @@ angular.module('famous.angular') * console.log($event); * }; * ``` + * ### Fa-click on an fa-view + * `Fa-click` may be used on an `fa-view`. The function expression bound to `fa-click` will be bound to the `fa-view`'s internal `_eventInput`, the aggregation point of all events received by the `fa-view`. When it receives a `click` event, it will call the function expression bound to `fa-click`. + * + * In the example below, the `fa-surface` pipes its Surface events to an instantied Famous Event Handler called `myEvents`. + * `Fa-view` pipes from `myEvents`, receiving all events piped by the `fa-surface`. + * + * When a click event occurs on the `fa-surface`, it is piped to the `fa-view`. + * `fa-click` defines a callback function in which to handle click events, and when it receives a click event, it calls `myClickHandler()`. + * ```html + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.myEvents = new EventHandler(); + * + * $scope.myClickHandler = function($event) { + * console.log($event); + * console.log("fa-view receives the click event from the fa-surface, and calls myClickHandler defined on fa-click"); + * }; + * ``` */ angular.module('famous.angular') @@ -1425,6 +1458,7 @@ angular.module('famous.angular') * In this example below, a Scroll View is created with two nested `fa-view`'s, both of which have an `fa-index` of 0 and 1, respectively. * * If `fa-index` is declared explicitly, it will override any default order of `fa-view`'s declared in html. + * If `fa-views` are created with an ng-repeat, they are automatically assigned the $index property, unless explicitly set. * The `fa-view` with the blue background color appears after the one with the red background because its `fa-index` is set to 1. * * `fa-scroll-view` accepts another directive called `fa-start-index` as an attribute, which determines which `fa-view` the Scroll View displays by default. @@ -2159,6 +2193,7 @@ angular.module('famous.angular') * * * ``` + * @example * `Fa-render-node` can wrap a custom-made widget or any renderable component from Famous and allow it to be inserted in the Render Tree. * * All Famous widgets, such as a Scroll View, a Sequential Layout, or a Header-footer-layout, are extended Famous Views. @@ -2269,144 +2304,152 @@ angular.module('famous.angular') * * * ``` - - @example - - ScrollView + Events + ng-repeat - --------------------------------- - In the example below, fa-scrollview displays a collection of nested fa-views generated by an ng-repeat directive. - In Famous, events are used to move information between widgets (such as ScrollView) and nested views. - When a nested view needs to trigger higher-order app behavior within another view (such as a widget), the best practice is to pass data via events. - - Input events are captured on surfaces, and it is up the developer to specify where the events will broadcast and receive events by piping. - To use a scroll view, create a Famous EventHandler on the scope, pipe the surface events to the event handler using fa-pipe-to, and then pipe that event handler to the ScrollView using fa-pipe-from. - This will enable scrolling by connecting input events from the surfaces to the Scroll View. - -* ```javascript -* var EventHandler = $famous['famous/core/EventHandler']; -* $scope.eventHandler = new EventHandler(); -* -* $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; -* ``` - -* ```html -* -* -* -* -*
{{item.content}}
-* -* -* -* -* ``` - -To specify (optional) configurable options for the Scroll View, pass in an object on the scope. -Notable options include clipSize, which specifies the size of the area in pixels that the ScrollView will display content in, and direction, which specifies whether the nested views will scroll horizontally or vertically (1 is vertical, 0 is horizontal). -A full list of configurable options for Scroll View may be found at https://famo.us/docs/0.2.0/views/Scrollview/. - -* ```javascript -* var EventHandler = $famous['famous/core/EventHandler']; -* $scope.eventHandler = new EventHandler(); -* $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; -* -* $scope.options = { -* myScrollView: { -* clipSize: 568, -* paginated: true, -* speedLimit: 5, -* direction: 1, -* } -* }; -* ``` - -ScrollView with explicitly created views ------------------------------------------ -In this example below, a scrollview is created with two nested fa-view's, both of which have an fa-index of 0 and 1, respectively. -Fa-index determines the order of which the surfaces appear in the sequential view. -If fa-index is declared explicitly, it will override any default order of elements declared in html. -As in the example below, the fa-view with the blue background color appears after the one with the red background because its fa-index is set to 1. -If fa-views are created with an ng-repeat, they are automatically assigned the $index property, unless explicitly set. - -The scrollView directive accepts another directive called fa-start-index as an attribute, and this determines which view the scrollView displays by default. -Fa-start-index will not affect the sequential order of the layout; the view with the red background will be layed out first, followed by the view with the blue background. -With this attribute set to 1, the scroll view will display the view with the index of 1, which is the view with the blue background color. - -* ```html - - - - - - - - - - - - -* ``` - -* ```javascript -* var EventHandler = $famous['famous/core/EventHandler']; -* $scope.eventHandler = new EventHandler(); -* $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; -* -$scope.options = { - scrollViewTwo: { - direction: 0 - } -}; -* ``` - -Multiple scroll views ---------------------- -Combining both approaches above (a scrollview with ng-repeated views, and one with two explicitly created views), one can can nest a ScrollView within another ScrollView. -A Scroll View is a widget that displays a collection of views sequentially - it is agnostic about the views that are inside of it; it only requires that events are piped from surfaces to the ScrollView. - -In the example below, the outer scrollview contains two explictly created views. One of those views contains a scrollview with sub-views created through an ngRepeat directive. -The outer ScrollView is passed an option for its direction to be horizontal (0), and the inner ScrollView is passed an option for a vertical direction (1). - -* ```html - - - - - - - - - - - - - -
{{item.content}}
- - - - - - - -* ``` - -* ```javascript -* var EventHandler = $famous['famous/core/EventHandler']; -* $scope.eventHandler = new EventHandler(); -* $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; -* - $scope.options = { - scrollViewOuter: { - direction: 0, - paginated: true - }, - scrollViewInner :{ - direction: 1 - } - }; -* ``` - + * + * @example + * ### Scroll View + Events + ng-repeat + * In the example below, `fa-scroll-view` displays a collection of nested `fa-views` generated by ng-repeat. + * In Famous, events are not propagated from these nested `fa-view`'s to its parent `fa-scroll-view`. + * + * When a nested View needs to trigger higher-order app behavior within another View (such as a Scroll View), the best practice is to pass data via Famous Events. + * + * To use a Scroll View, create an instance of a Famous Event Handler on the scope. Pipe all Surface events to the event handler using `fa-pipe-to`, and then specify that the Scroll View will receive events from that specific event handler using `fa-pipe-from`. + * + * Input events (like click) are captured on Surfaces, and piping must be used to specify where the events will broadcast and be received. + * This will enable scrolling by connecting input events from the `fa-surface`s to the `fa-scroll-view`, otherwise the Scroll View will not receive mousewheel events. + * + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.eventHandler = new EventHandler(); + * + * $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; + * ``` + * ```html + * + * + * + * + * + * + * + * + * ``` + * + * To specify (optional) configurable options for the Scroll View, bind an object on the scope to the `fa-options` attribute on `fa-scroll-view`. + * Notable options include `clipSize`, which specifies the size of the area in pixels to display content in, and `direction`, which specifies whether the nested views will scroll horizontally or vertically (1 is vertical, 0 is horizontal). + * A full list of configurable options for Scroll View may be found at https://famo.us/docs/0.2.0/views/Scrollview/. + * + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.eventHandler = new EventHandler(); + * $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; + * + * $scope.options = { + * myScrollView: { + * clipSize: 568, + * paginated: true, + * speedLimit: 5, + * direction: 1, + * } + * }; + * ``` + * + * ### Scroll View with explicitly created views + * `Fa-index` determines the order of which the surfaces appear in the sequential view. + * In this example below, a Scroll View is created with two nested `fa-view`'s, both of which have an `fa-index` of 0 and 1, respectively. + * + * If `fa-index` is declared explicitly, it will override any default order of `fa-view`'s declared in html. + * If `fa-views` are created with an ng-repeat, they are automatically assigned the $index property, unless explicitly set. + * The `fa-view` with the blue background color appears after the one with the red background because its `fa-index` is set to 1. + * + * `fa-scroll-view` accepts another directive called `fa-start-index` as an attribute, which determines which `fa-view` the Scroll View displays by default. + * `Fa-start-index` will not affect the sequential order of the layout; the `fa-view` with the red background will be layed out first, followed by the one with the blue background. + * By setting `fa-start-index` to 1, the Scroll View will display the View with the index of 1 by default, "starting" at the index of 1, which is the View with the blue background color. + * + * ```html + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.eventHandler = new EventHandler(); + * $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; + * + * $scope.options = { + * scrollViewTwo: { + * direction: 0 + * } + * }; + * ``` + * + * ### Combining multiple Scroll Views + * + * Combining both approaches above (a Scroll View with ng-repeated views, and one with explicitly created views), one can can nest a Scroll View within another Scroll View. + * A Scroll View is a Famous widget that displays a collection of views sequentially; it is agnostic about the Views that are inside of it; it only requires that events are piped from Surfaces to the ScrollView. + * + * In the example below, the outer Scroll View contains two explictly created Views. One of those Views contains another Scroll View with sub-views created through an ngRepeat. + * The outer Scroll View is passed an option for its `direction` to be `horizontal (0)`, and the inner Scroll View is passed an option for a `vertical direction (1)`. + * + * ```html + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
{{item.content}}
+ * + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.eventHandler = new EventHandler(); + * $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; + * + * $scope.options = { + * scrollViewOuter: { + * direction: 0, + * paginated: true + * }, + * scrollViewInner :{ + * direction: 1 + * } + * }; + * ``` */ angular.module('famous.angular') @@ -2925,29 +2968,58 @@ angular.module('famous.angular') * * * ``` - -Note: For testing purposes during development, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation - -##Example -Upon a touchend event firing, fa-touchend will evaluate the expression bound to it. - -Touchstart fires once upon first touch; touchmove fires as the touch point is moved along a touch surface; touchend fires upon release of the touch point. - -```html - - - -``` - -```javascript -var touchEndCounter = 0; -$scope.touchEnd = function($event) { - touchEndCounter++; - console.log($event); - console.log("touchEnd: " + touchEndCounter); -}; -qqq - + * + * Note: For testing purposes during development, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation + * + * @example + * Upon a touchend event firing, fa-touchend will evaluate the expression bound to it. + * + * Touchstart fires once upon first touch; touchend fires as the touch point is moved along a touch surface; touchend fires upon release of the touch point. + * + * ### Fa-touchend on an fa-surface + * `Fa-touchend` can be used on an `fa-surface`. Internally, a Famous Surface has a `.on()` method that binds a callback function to an event type handled by that Surface. + * The function expression bound to `fa-touchend` is bound to that `fa-surface`'s touchend eventHandler, and when touchend fires, the function expression will be called. + * + * ```html + * + * + * + * ``` + * ```javascript + * var touchEndCounter = 0; + * $scope.touchEnd = function($event) { + * touchEndCounter++; + * console.log($event); + * console.log("touchEnd: " + touchEndCounter); + * }; + * ``` + * + * ### Fa-touchend on an fa-view + * `Fa-touchend` may be used on an `fa-view`. The function expression bound to `fa-touchend` will be bound to the `fa-view`'s internal `_eventInput`, the aggregation point of all events received by the `fa-view`. When it receives a `touchend` event, it will call the function expression bound to `fa-touchend`. + * + * In the example below, the `fa-surface` pipes its Surface events to an instantied Famous Event Handler called `myEvents`. + * `Fa-view` pipes from `myEvents`, receiving all events piped by the `fa-surface`. + * + * When a touchend event occurs on the `fa-surface`, it is piped to the `fa-view`. + * `fa-touchend` defines a callback function in which to handle touchend events, and when it receives a touchend event, it calls `touchEnd()`. + * ```html + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.myEvents = new EventHandler(); + * + * $scope.touchEnd = function($event) { + * console.log($event); + * console.log("fa-view receives the touchend event from the fa-surface, and calls $scope.touchEnd bound to fa-touchend"); + * }; + * ``` */ angular.module('famous.angular') @@ -2992,31 +3064,61 @@ angular.module('famous.angular') * * * ``` - -Note: For testing purposes during development, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation - -##Example -Upon a touchmove event firing, fa-touchmove will evaluate the expression bound to it. - -Touchstart fires once upon first touch; touchmove fires as the touch point is moved along a touch surface, until release of the touch point. -The rate of which touchmove events fire is implementation-defined by browser and hardware. -Upon each firing, fa-touchmove evaluates the expression bound to it. - -```html - - - -``` - -```javascript -var touchMoveCounter = 0; -$scope.touchMove = function($event) { - touchMoveCounter++; - console.log($event); - console.log("touchMove: " + touchMoveCounter); -}; -``` - + * + * Note: For development purposes, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation + * + * @example + * Upon a touchmove event firing, `fa-touchmove` will evaluate the expression bound to it. + * + * touchmove fires once upon first touch; touchmove fires as the touch point (finger) is moved along a touch surface, until release of the touch point. + * The rate of which touchmove events fire is implementation-defined by browser and hardware. + * `fa-touchmove` evaluates the expression bound to it upon each firing of touchmove. + * + * ### Fa-touchmove on an fa-surface + * `Fa-touchmove`can be used on an `fa-surface`. Internally, a Famous Surface has a `.on()` method that binds a callback function to an event type handled by that Surface. + * The function expression bound to `fa-touchmove` is bound to that `fa-surface`'s touchmove eventHandler, and when touchmove fires, the function expression will be called. + * + * ```html + * + * + * + * ``` + * ```javascript + * var touchMoveCounter = 0; + * $scope.touchMove = function($event) { + * touchMoveCounter++; + * console.log($event); + * console.log("touchMove: " + touchMoveCounter); + * }; + * ``` + * + * ### Fa-touchmove on an fa-view + * `Fa-touchmove` may be used on an `fa-view`. The function expression bound to `fa-touchmove` will be bound to the `fa-view`'s internal `_eventInput`, the aggregation point of all events received by the `fa-view`. When it receives a `touchmove` event, it will call the function expression bound to `fa-touchmove`. + * + * In the example below, the `fa-surface` pipes its Surface events to an instantied Famous Event Handler called `myEvents`. + * `Fa-view` pipes from `myEvents`, receiving all events piped by the `fa-surface`. + * + * When a touchmove event occurs on the `fa-surface`, it is piped to the `fa-view`. + * `fa-touchmove` defines a callback function in which to handle touchmove events, and when it receives a touchmove event, it calls `touchMove()`. + * + * ```html + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.myEvents = new EventHandler(); + * + * $scope.touchMove = function($event) { + * console.log($event); + * console.log("fa-view receives the touchmove event from the fa-surface, and calls $scope.touchMove bound to fa-touchmove"); + * }; + * ``` */ angular.module('famous.angular') @@ -3060,30 +3162,61 @@ angular.module('famous.angular') * * * ``` - -Note: For testing purposes during development, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation - -##Example -Upon a touchstart event firing, fa-touchstart will evaluate the expression bound to it. - -Touchstart fires once when a touch point (finger) is first placed upon the touch surface. -If the touch point moves or releases touch, it will not fire a touchstart. -If the touch point is placed upon the touch surface again, it will fire another touchstart event. - -```html - - - -``` -```javascript - var touchStartCounter = 0; - $scope.touchStart = function($event) { - touchStartCounter++; - console.log($event); - console.log("touchStart: " + touchStartCounter); - }; -``` -*/ + * + * Note: For development purposes, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation + * + * @example + * Upon a `touchstart` event firing, `fa-touchstart` will evaluate the expression bound to it. + * + * Touchstart fires once when a touch point (finger) is first placed upon the touch surface. + * If the touch point moves or releases touch, it will not fire another touchstart; touchstart fires once upon the first touch. + * If the touch point is placed upon the touch surface again, it will fire another touchstart event. + * + * ### Fa-touchstart on an fa-surface + * `Fa-touchstart` can be used on an `fa-surface`. Internally, a Famous Surface has a `.on()` method that binds a callback function to an event type handled by that Surface. + * The function expression bound to `fa-touchstart` is bound to that `fa-surface`'s touchstart eventHandler, and when touchstart fires, the function expression will be called. + * + * ```html + * + * + * + * ``` + * ```javascript + * var touchStartCounter = 0; + * $scope.touchStart = function($event) { + * touchStartCounter++; + * console.log($event); + * console.log("touchStart: " + touchStartCounter); + * }; + * ``` + * + * ### Fa-touchstart on an fa-view + * `Fa-touchstart` may be used on an `fa-view`. The function expression bound to `fa-touchstart` will be bound to the `fa-view`'s internal `_eventInput`, the aggregation point of all events received by the `fa-view`. When it receives a `touchstart` event, it will call the function expression bound to `fa-touchstart`. + * + * In the example below, the `fa-surface` pipes its Surface events to an instantied Famous Event Handler called `myEvents`. + * `Fa-view` pipes from `myEvents`, receiving all events piped by the `fa-surface`. + * + * When a touchstart event occurs on the `fa-surface`, it is piped to the `fa-view`. + * `fa-touchstart` defines a callback function in which to handle touchstart events, and when it receives a touchstart event, it calls `touchStart()`. + * ```html + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.myEvents = new EventHandler(); + * + * $scope.touchStart = function($event) { + * console.log($event); + * console.log("fa-view receives the touchstart event from the fa-surface, and calls $scope.touchStart bound to fa-touchstart"); + * }; + * ``` + */ angular.module('famous.angular') .directive('faTouchstart', ['$parse', '$famousDecorator', function ($parse, $famousDecorator) { @@ -3126,25 +3259,35 @@ angular.module('famous.angular') * * * ``` - * A Famous View is a Render Node that has its own input EventHandler and output EventHandler. - * It may consist of many Modifier & Surfaces a complex set of event handlers. - * A View's input eventHandler is the aggregation point of all events coming into the View, and then the View can handle all of those events in ways specified. + * @example + * A Famous View is used for encapsulating many Modifiers and Surfaces together. Internally, it is a Render Node that has its own input EventHandler (`_eventInput`) and output EventHandler (`_eventOutput`). + * It does not map to DOM elements, but rather, it is an empty Render Node that can be extended by a developer. + * A View's input eventHandler is the aggregation point of all events coming into the View, and from there, the View can listen for specific events and handle them. * - * For example, a Scroll View is a Famous View that has been extended with certain sets of behavior. - * When a surface within a Scroll View receives an event (such as mouse scroll), and these events are piped to the Scroll View, these events go through the Scroll View's input EventHandler and are handled by the Scroll View. + * A more concrete example is a Scroll View: it is a Famous View that has been extended with certain sets of behavior to handle events such as a mouse scroll. + * In the example below, when an `fa-surface` within an `fa-scroll-view` propagates an event (such as mouse scroll), these events are piped to the Scroll View (through `fa-pipe-to`). These events go through the Scroll View's `_eventInput` (using `fa-pipe-from`). From there, the Scroll View has pre-defined event handlers to handle these events. + * + * Famous Views are a way to encapsulate large event systems with renderables (Surfaces & Modifiers). * *```html - * + * * * - * + * * * - * + * *``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.myEventHandler = new EventHandler(); + * ``` + * + * ### Event propagation within & between Views + * In the Famous event model, an `fa-view` nested within another `fa-view` does not automatically propagate its events to its parent. + * Not even an `fa-surface` nested inside an `fa-view` propagates its events to the `fa-view`. All events to an `fa-view` must be piped explicitly. * - *This brings up another important note: in the Famous event model, an fa-view nested within another fa-view does not automatically propagate its events to its parent. - *For a longer discussion on Famous-Angular events, go to fa-pipe-from/fa-pipe-to in the docs. + * For a more thorough discussion on Famous-Angular events, go to fa-pipe-from/fa-pipe-to in the docs. */ angular.module('famous.angular') diff --git a/docs/unstable/directive/faApp/index.md b/docs/unstable/directive/faApp/index.md index 4dd32156..8d846c74 100644 --- a/docs/unstable/directive/faApp/index.md +++ b/docs/unstable/directive/faApp/index.md @@ -71,10 +71,14 @@ it is inside of a fa-surface directive.

Nesting an fa-app within another fa-app is possible, and the use case of this approach would be for css content overflow. Declaring multiple fa-app's within a page is permitted, but each new one incurs a penalty to performance, and fa-app's should definitely not be declared within an ng-repeat.

Fa-app must be declared with a height & width

-

The element fa-app is declared within must have a height and width styling, declared inline or as a css declaration in an external stylesheet.

+

The element fa-app is declared within must have a set height and width styling, declared inline or as a css declaration in an external stylesheet.

<fa-app style="width: 320px; height: 568px;">
    <!-- other fa- scene graph components -->
 </fa-app>
+

If fa-app is declared as an attribute of another element, that element must be a display:block element, such as a div or p.

+
<div fa-app style="width: 320px; height: 568px;">
+  <!-- other fa- scene graph components -->
+</div>
diff --git a/docs/unstable/directive/faClick/index.md b/docs/unstable/directive/faClick/index.md index 1830a92e..c1f4ed40 100644 --- a/docs/unstable/directive/faClick/index.md +++ b/docs/unstable/directive/faClick/index.md @@ -88,7 +88,8 @@ click. (TODO:href="https://docs.angularjs.org/guide/expression#-eve -

Example

Fa-click is most commonly used on a fa-surface'. Internally, a Famous Surface has a ".on()" method that binds a callback function to an event type handled by that Surface. +

Example

Fa-click on an fa-surface

+

Fa-click can be used on an fa-surface. Internally, a Famous Surface has a .on() method that binds a callback function to an event type handled by that Surface. The function expression bound to fa-click is bound to that fa-surface's click eventHandler, and when the fa-surface is clicked, the function expression will be called. 

<fa-modifier fa-size="[100, 100]">
   <fa-surface fa-click="myClickHandler($event)" fa-background-color="'red'"></fa-surface>
@@ -97,6 +98,25 @@ click. (TODO:href="https://docs.angularjs.org/guide/expression#-eve
   console.log("click");
   console.log($event);
 };
+

Fa-click on an fa-view

+

Fa-click may be used on an fa-view. The function expression bound to fa-click will be bound to the fa-view's internal _eventInput, the aggregation point of all events received by the fa-view. When it receives a click event, it will call the function expression bound to fa-click.

+

In the example below, the fa-surface pipes its Surface events to an instantied Famous Event Handler called myEvents. +Fa-view pipes from myEvents, receiving all events piped by the fa-surface.

+

When a click event occurs on the fa-surface, it is piped to the fa-view.
fa-click defines a callback function in which to handle click events, and when it receives a click event, it calls myClickHandler().

+
<fa-view fa-click="myClickHandler($event)" fa-pipe-from="myEvents">
+  <fa-modifier fa-size="[100, 100]">
+    <fa-surface fa-pipe-to="myEvents"
+                fa-background-color="'orange'">
+    </fa-surface>
+  </fa-modifier>
+</fa-view>
+
var EventHandler = $famous['famous/core/EventHandler'];
+$scope.myEvents = new EventHandler();
+
+$scope.myClickHandler = function($event) {
+  console.log($event);
+  console.log("fa-view receives the click event from the fa-surface, and calls myClickHandler defined on fa-click");
+};
diff --git a/docs/unstable/directive/faIndex/index.md b/docs/unstable/directive/faIndex/index.md index e2f12639..9d689584 100644 --- a/docs/unstable/directive/faIndex/index.md +++ b/docs/unstable/directive/faIndex/index.md @@ -64,6 +64,7 @@ order is desired, then the index value must be assigned/overridden using the faI

Example

Fa-index determines the order of which the surfaces appear in the sequential view. In this example below, a Scroll View is created with two nested fa-view's, both of which have an fa-index of 0 and 1, respectively.

If fa-index is declared explicitly, it will override any default order of fa-view's declared in html. +If fa-views are created with an ng-repeat, they are automatically assigned the $index property, unless explicitly set. The fa-view with the blue background color appears after the one with the red background because its fa-index is set to 1.

fa-scroll-view accepts another directive called fa-start-index as an attribute, which determines which fa-view the Scroll View displays by default. Fa-start-index will not affect the sequential order of the layout; the fa-view with the red background will be layed out first, followed by the one with the blue background. diff --git a/docs/unstable/directive/faRenderNode/index.md b/docs/unstable/directive/faRenderNode/index.md index dce4e7ac..80d94ff7 100644 --- a/docs/unstable/directive/faRenderNode/index.md +++ b/docs/unstable/directive/faRenderNode/index.md @@ -49,26 +49,28 @@ It allows you to pass a reference to an arbitrary render node from your controll ``` -`Fa-render-node` can wrap a custom-made widget or any renderable component from Famous and allow it to be inserted in the Render Tree. + + -All Famous widgets, such as a Scroll View, a Sequential Layout, or a Header-footer-layout, are extended Famous Views. -`Fa-render-node` allows a developer to create & extend their own Famous View, and use it within their own Famous-Angular app. + -In the example below, a Famous View is instantiated on the scope; a Modifier is added to it, and then a Surface is added below. -This approach of creating a View and adding renderables to it with the `.add()` method is more in line with a "vanilla Famous" approach than a declarative approach with Famous-Angular. -In the html view, an `fa-render-node` is declared, with an `fa-node` attribute of the name of the View created on the scope, resulting in this custom, newly-created View appearing on the page. -```javascript -var View = $famous['famous/core/View']; -var Modifier = $famous['famous/core/Modifier']; -var Surface = $famous['famous/core/Surface']; -var Transform = $famous['famous/core/Transform']; +

Example

Fa-render-node can wrap a custom-made widget or any renderable component from Famous and allow it to be inserted in the Render Tree.

+

All Famous widgets, such as a Scroll View, a Sequential Layout, or a Header-footer-layout, are extended Famous Views. +Fa-render-node allows a developer to create & extend their own Famous View, and use it within their own Famous-Angular app.

+

In the example below, a Famous View is instantiated on the scope; a Modifier is added to it, and then a Surface is added below. +This approach of creating a View and adding renderables to it with the .add() method is more in line with a "vanilla Famous" approach than a declarative approach with Famous-Angular.

+

In the html view, an fa-render-node is declared, with an fa-node attribute of the name of the View created on the scope, resulting in this custom, newly-created View appearing on the page.

+
var View = $famous['famous/core/View'];
+var Modifier = $famous['famous/core/Modifier'];
+var Surface = $famous['famous/core/Surface'];
+var Transform = $famous['famous/core/Transform'];
 
 $scope.masterView = new View();
 
-var _surf = new Surface({properties: {backgroundColor: 'red'}});
-_surf.setContent("I'm a surface");
+var _surf = new Surface({properties: {backgroundColor: 'red'}});
+_surf.setContent("I'm a surface");
 
 var _mod = new Modifier();
 
@@ -82,14 +84,7 @@ $scope.masterView.add(_mod).add(_surf);
 ```javascript
 
 ```html
-
-```
-  
-  
-
-  
-
-
+<fa-render-node fa-node="masterView" id="render"></fa-render-node>
diff --git a/docs/unstable/directive/faScrollView/index.md b/docs/unstable/directive/faScrollView/index.md index ea056934..6e24dabb 100644 --- a/docs/unstable/directive/faScrollView/index.md +++ b/docs/unstable/directive/faScrollView/index.md @@ -58,13 +58,13 @@ and will allow you to scroll through them with mousewheel or touch events. -

Example

ScrollView + Events + ng-repeat

-

In the example below, fa-scrollview displays a collection of nested fa-views generated by an ng-repeat directive. - In Famous, events are used to move information between widgets (such as ScrollView) and nested views. - When a nested view needs to trigger higher-order app behavior within another view (such as a widget), the best practice is to pass data via events.

-

Input events are captured on surfaces, and it is up the developer to specify where the events will broadcast and receive events by piping. - To use a scroll view, create a Famous EventHandler on the scope, pipe the surface events to the event handler using fa-pipe-to, and then pipe that event handler to the ScrollView using fa-pipe-from. - This will enable scrolling by connecting input events from the surfaces to the Scroll View.

+

Example

Scroll View + Events + ng-repeat

+

In the example below, fa-scroll-view displays a collection of nested fa-views generated by ng-repeat. +In Famous, events are not propagated from these nested fa-view's to its parent fa-scroll-view.

+

When a nested View needs to trigger higher-order app behavior within another View (such as a Scroll View), the best practice is to pass data via Famous Events.

+

To use a Scroll View, create an instance of a Famous Event Handler on the scope. Pipe all Surface events to the event handler using fa-pipe-to, and then specify that the Scroll View will receive events from that specific event handler using fa-pipe-from.

+

Input events (like click) are captured on Surfaces, and piping must be used to specify where the events will broadcast and be received. +This will enable scrolling by connecting input events from the fa-surfaces to the fa-scroll-view, otherwise the Scroll View will not receive mousewheel events.

var EventHandler = $famous['famous/core/EventHandler'];
 $scope.eventHandler = new EventHandler();
 
@@ -72,14 +72,15 @@ $scope.list = [{content: "famous"}, {content: "angular"}, {c
 
<fa-scroll-view fa-pipe-from="eventHandler" fa-options="options.myScrollView">
     <fa-view ng-repeat="item in list">
        <fa-modifier id="{{'listItem' + $index}}" fa-translate="[0, 0, 0]" fa-size="[300, 300]">
-         <fa-surface fa-pipe-to="eventHandler" fa-size="[undefined, undefined]" fa-background-color="'red'">
-           <div>{{item.content}}</div>
+         <fa-surface fa-pipe-to="eventHandler"
+                     fa-size="[undefined, undefined]" 
+                     fa-background-color="'red'">
          </fa-surface>
        </fa-modifier>
     </fa-view> 
- </fa-scroll-view>

-
To specify (optional) configurable options for the Scroll View, pass in an object on the scope.
-Notable options include clipSize, which specifies the size of the area in pixels that the ScrollView will display content in, and direction, which specifies whether the nested views will scroll horizontally or vertically (1 is vertical, 0 is horizontal).
+</fa-scroll-view>
+

To specify (optional) configurable options for the Scroll View, bind an object on the scope to the fa-options attribute on fa-scroll-view. +Notable options include clipSize, which specifies the size of the area in pixels to display content in, and direction, which specifies whether the nested views will scroll horizontally or vertically (1 is vertical, 0 is horizontal). A full list of configurable options for Scroll View may be found at https://famo.us/docs/0.2.0/views/Scrollview/.

var EventHandler = $famous['famous/core/EventHandler'];
 $scope.eventHandler = new EventHandler();
@@ -93,27 +94,33 @@ $scope.options = {
     direction: 1,
   }
 };
-

ScrollView with explicitly created views

-

In this example below, a scrollview is created with two nested fa-view's, both of which have an fa-index of 0 and 1, respectively. -Fa-index determines the order of which the surfaces appear in the sequential view. -If fa-index is declared explicitly, it will override any default order of elements declared in html. -As in the example below, the fa-view with the blue background color appears after the one with the red background because its fa-index is set to 1. -If fa-views are created with an ng-repeat, they are automatically assigned the $index property, unless explicitly set.

-

The scrollView directive accepts another directive called fa-start-index as an attribute, and this determines which view the scrollView displays by default. -Fa-start-index will not affect the sequential order of the layout; the view with the red background will be layed out first, followed by the view with the blue background. -With this attribute set to 1, the scroll view will display the view with the index of 1, which is the view with the blue background color.

-
  <fa-scroll-view fa-pipe-from="eventHandler" fa-options="options.scrollViewTwo" fa-start-index="1">
-    <fa-view fa-index="1">
-      <fa-modifier fa-size="[320, 320]">
-          <fa-surface fa-background-color="'blue'" fa-pipe-to="eventHandler"></fa-surface>
-        </fa-modifier>
-    </fa-view>
-    <fa-view fa-index="0">
-      <fa-modifier fa-size="[320, 320]">
-          <fa-surface fa-background-color="'red'" fa-pipe-to="eventHandler"></fa-surface>
-        </fa-modifier>
-    </fa-view>
-   </fa-scroll-view>
+

Scroll View with explicitly created views

+

Fa-index determines the order of which the surfaces appear in the sequential view. +In this example below, a Scroll View is created with two nested fa-view's, both of which have an fa-index of 0 and 1, respectively.

+

If fa-index is declared explicitly, it will override any default order of fa-view's declared in html. +If fa-views are created with an ng-repeat, they are automatically assigned the $index property, unless explicitly set. +The fa-view with the blue background color appears after the one with the red background because its fa-index is set to 1.

+

fa-scroll-view accepts another directive called fa-start-index as an attribute, which determines which fa-view the Scroll View displays by default. +Fa-start-index will not affect the sequential order of the layout; the fa-view with the red background will be layed out first, followed by the one with the blue background. +By setting fa-start-index to 1, the Scroll View will display the View with the index of 1 by default, "starting" at the index of 1, which is the View with the blue background color.

+
<fa-app style="width: 320px; height: 568px;"> 
+ <fa-scroll-view fa-pipe-from="eventHandler" fa-options="options.scrollViewTwo" fa-start-index="1">
+   <fa-view fa-index="1">
+     <fa-modifier fa-size="[320, 320]">
+         <fa-surface fa-pipe-to="eventHandler" 
+                     fa-background-color="'blue'">
+         </fa-surface>
+       </fa-modifier>
+   </fa-view>
+   <fa-view fa-index="0">
+     <fa-modifier fa-size="[320, 320]">
+         <fa-surface fa-pipe-to="eventHandler" 
+                     fa-background-color="'red'">
+         </fa-surface>
+       </fa-modifier>
+   </fa-view>
+  </fa-scroll-view>   
+</fa-app>
var EventHandler = $famous['famous/core/EventHandler'];
 $scope.eventHandler = new EventHandler();
 $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}];
@@ -123,45 +130,50 @@ $scope.options = {
     direction: 0
   }
 };
-

Multiple scroll views

-

Combining both approaches above (a scrollview with ng-repeated views, and one with two explicitly created views), one can can nest a ScrollView within another ScrollView. -A Scroll View is a widget that displays a collection of views sequentially - it is agnostic about the views that are inside of it; it only requires that events are piped from surfaces to the ScrollView.

-

In the example below, the outer scrollview contains two explictly created views. One of those views contains a scrollview with sub-views created through an ngRepeat directive. -The outer ScrollView is passed an option for its direction to be horizontal (0), and the inner ScrollView is passed an option for a vertical direction (1).

-
<fa-scroll-view fa-pipe-from="eventHandler" fa-options="options.scrollViewOuter">
-
-  <fa-view fa-index="0" id="sideBar">
-    <fa-modifier fa-size="[320, 320]" id="sideBarMod">
-        <fa-surface fa-background-color="'blue'" fa-pipe-to="eventHandler" fa-size="[undefined, undefined]"></fa-surface>
-      </fa-modifier>
-  </fa-view>
-
-  <fa-view fa-index="1" id="main">
-    <fa-scroll-view fa-pipe-from="eventHandler" fa-options="options.scrollViewInner">
-      <fa-view ng-repeat="item in list">
-         <fa-modifier fa-size="[300, 300]" id="{{'item' + $index + 'Mod'}}">
-           <fa-surface fa-pipe-to="eventHandler" fa-size="[undefined, undefined]" fa-background-color="'red'">
-             <div>{{item.content}}</div>
-           </fa-surface>
-         </fa-modifier>
-      </fa-view> 
-    </fa-scroll-view>  
-  </fa-view>
-
- </fa-scroll-view>
+

Combining multiple Scroll Views

+

Combining both approaches above (a Scroll View with ng-repeated views, and one with explicitly created views), one can can nest a Scroll View within another Scroll View. +A Scroll View is a Famous widget that displays a collection of views sequentially; it is agnostic about the Views that are inside of it; it only requires that events are piped from Surfaces to the ScrollView.

+

In the example below, the outer Scroll View contains two explictly created Views. One of those Views contains another Scroll View with sub-views created through an ngRepeat. +The outer Scroll View is passed an option for its direction to be horizontal (0), and the inner Scroll View is passed an option for a vertical direction (1).

+
<fa-app style="width: 320px; height: 568px;"> 
+  <fa-scroll-view fa-pipe-from="eventHandler" fa-options="options.scrollViewOuter">
+    <fa-view fa-index="0" id="sideBar">
+      <fa-modifier fa-size="[320, 320]" id="sideBarMod">
+          <fa-surface fa-pipe-to="eventHandler" 
+                      fa-background-color="'blue'"
+                      fa-size="[undefined, undefined]">
+          </fa-surface>
+        </fa-modifier>
+    </fa-view>
+
+    <fa-view fa-index="1" id="main">
+      <fa-scroll-view fa-pipe-from="eventHandler" fa-options="options.scrollViewInner">
+        <fa-view ng-repeat="item in list">
+           <fa-modifier fa-size="[300, 300]" id="{{'item' + $index + 'Mod'}}">
+             <fa-surface fa-pipe-to="eventHandler"
+                         fa-size="[undefined, undefined]"
+                         fa-background-color="'red'">
+               <div>{{item.content}}</div>
+             </fa-surface>
+           </fa-modifier>
+        </fa-view> 
+      </fa-scroll-view>  
+    </fa-view>
+  </fa-scroll-view>   
+</fa-app>
var EventHandler = $famous['famous/core/EventHandler'];
 $scope.eventHandler = new EventHandler();
 $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}];
 
-  $scope.options = {
-    scrollViewOuter: {
-      direction: 0,
-      paginated: true
-    },
-    scrollViewInner :{
-      direction: 1
-    }
-  };
+$scope.options = { + scrollViewOuter: { + direction: 0, + paginated: true + }, + scrollViewInner :{ + direction: 1 + } +}; diff --git a/docs/unstable/directive/faTouchend/index.md b/docs/unstable/directive/faTouchend/index.md index e032ed72..90d9fde2 100644 --- a/docs/unstable/directive/faTouchend/index.md +++ b/docs/unstable/directive/faTouchend/index.md @@ -49,26 +49,6 @@ This directive allows you to specify custom behavior after an element that - - -``` - -```javascript -var touchEndCounter = 0; -$scope.touchEnd = function($event) { - touchEndCounter++; - console.log($event); - console.log("touchEnd: " + touchEndCounter); -}; -qqq

API

@@ -109,5 +89,39 @@ qqq +

Example

Upon a touchend event firing, fa-touchend will evaluate the expression bound to it.

+

Touchstart fires once upon first touch; touchend fires as the touch point is moved along a touch surface; touchend fires upon release of the touch point.

+

Fa-touchend on an fa-surface

+

Fa-touchend can be used on an fa-surface. Internally, a Famous Surface has a .on() method that binds a callback function to an event type handled by that Surface. +The function expression bound to fa-touchend is bound to that fa-surface's touchend eventHandler, and when touchend fires, the function expression will be called.

+
<fa-modifier fa-size="[100, 100]">
+  <fa-surface fa-touchend="touchEnd($event)" fa-background-color="'red'"></fa-surface>
+</fa-modifier>
+
var touchEndCounter = 0;
+$scope.touchEnd = function($event) {
+  touchEndCounter++;
+  console.log($event);
+  console.log("touchEnd: " + touchEndCounter);
+};
+

Fa-touchend on an fa-view

+

Fa-touchend may be used on an fa-view. The function expression bound to fa-touchend will be bound to the fa-view's internal _eventInput, the aggregation point of all events received by the fa-view. When it receives a touchend event, it will call the function expression bound to fa-touchend.

+

In the example below, the fa-surface pipes its Surface events to an instantied Famous Event Handler called myEvents. +Fa-view pipes from myEvents, receiving all events piped by the fa-surface.

+

When a touchend event occurs on the fa-surface, it is piped to the fa-view.
fa-touchend defines a callback function in which to handle touchend events, and when it receives a touchend event, it calls touchEnd().

+
<fa-view fa-touchend="touchEnd($event)" fa-pipe-from="myEvents">
+  <fa-modifier fa-size="[100, 100]">
+    <fa-surface fa-pipe-to="myEvents"
+                fa-background-color="'orange'">
+    </fa-surface>
+  </fa-modifier>
+</fa-view>
+
var EventHandler = $famous['famous/core/EventHandler'];
+$scope.myEvents = new EventHandler();
+
+$scope.touchEnd = function($event) {
+  console.log($event);
+  console.log("fa-view receives the touchend event from the fa-surface, and calls $scope.touchEnd bound to fa-touchend");
+};
+ diff --git a/docs/unstable/directive/faTouchmove/index.md b/docs/unstable/directive/faTouchmove/index.md index cdfd5719..7b594c67 100644 --- a/docs/unstable/directive/faTouchmove/index.md +++ b/docs/unstable/directive/faTouchmove/index.md @@ -48,29 +48,7 @@ This directive allows you to specify custom behavior when an element is ``` -Note: For testing purposes during development, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation - -##Example -Upon a touchmove event firing, fa-touchmove will evaluate the expression bound to it. - -Touchstart fires once upon first touch; touchmove fires as the touch point is moved along a touch surface, until release of the touch point. -The rate of which touchmove events fire is implementation-defined by browser and hardware. -Upon each firing, fa-touchmove evaluates the expression bound to it. - -```html - - - -``` - -```javascript -var touchMoveCounter = 0; -$scope.touchMove = function($event) { - touchMoveCounter++; - console.log($event); - console.log("touchMove: " + touchMoveCounter); -}; -``` +Note: For development purposes, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation

API

@@ -111,5 +89,41 @@ $scope.touchMove = function($event) { +

Example

Upon a touchmove event firing, fa-touchmove will evaluate the expression bound to it.

+

touchmove fires once upon first touch; touchmove fires as the touch point (finger) is moved along a touch surface, until release of the touch point. +The rate of which touchmove events fire is implementation-defined by browser and hardware. +fa-touchmove evaluates the expression bound to it upon each firing of touchmove.

+

Fa-touchmove on an fa-surface

+

Fa-touchmovecan be used on an fa-surface. Internally, a Famous Surface has a .on() method that binds a callback function to an event type handled by that Surface. + The function expression bound to fa-touchmove is bound to that fa-surface's touchmove eventHandler, and when touchmove fires, the function expression will be called.

+
<fa-modifier fa-size="[100, 100]">
+  <fa-surface fa-touchmove="touchMove($event)" fa-background-color="'red'"></fa-surface>
+</fa-modifier>
+
var touchMoveCounter = 0;
+$scope.touchMove = function($event) {
+  touchMoveCounter++;
+  console.log($event);
+  console.log("touchMove: " + touchMoveCounter);
+};
+

Fa-touchmove on an fa-view

+

Fa-touchmove may be used on an fa-view. The function expression bound to fa-touchmove will be bound to the fa-view's internal _eventInput, the aggregation point of all events received by the fa-view. When it receives a touchmove event, it will call the function expression bound to fa-touchmove.

+

In the example below, the fa-surface pipes its Surface events to an instantied Famous Event Handler called myEvents. +Fa-view pipes from myEvents, receiving all events piped by the fa-surface.

+

When a touchmove event occurs on the fa-surface, it is piped to the fa-view.
fa-touchmove defines a callback function in which to handle touchmove events, and when it receives a touchmove event, it calls touchMove().

+
<fa-view fa-touchmove="touchMove($event)" fa-pipe-from="myEvents">
+  <fa-modifier fa-size="[100, 100]">
+    <fa-surface fa-pipe-to="myEvents"
+                fa-background-color="'orange'">
+    </fa-surface>
+  </fa-modifier>
+</fa-view>
+
var EventHandler = $famous['famous/core/EventHandler'];
+$scope.myEvents = new EventHandler();
+
+$scope.touchMove = function($event) {
+  console.log($event);
+  console.log("fa-view receives the touchmove event from the fa-surface, and calls $scope.touchMove bound to fa-touchmove");
+};
+ diff --git a/docs/unstable/directive/faTouchstart/index.md b/docs/unstable/directive/faTouchstart/index.md index abd43715..72d482c3 100644 --- a/docs/unstable/directive/faTouchstart/index.md +++ b/docs/unstable/directive/faTouchstart/index.md @@ -48,28 +48,7 @@ This directive allows you to specify custom behavior when an element is ``` -Note: For testing purposes during development, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation - -##Example -Upon a touchstart event firing, fa-touchstart will evaluate the expression bound to it. - -Touchstart fires once when a touch point (finger) is first placed upon the touch surface. -If the touch point moves or releases touch, it will not fire a touchstart. -If the touch point is placed upon the touch surface again, it will fire another touchstart event. - -```html - - - -``` -```javascript - var touchStartCounter = 0; - $scope.touchStart = function($event) { - touchStartCounter++; - console.log($event); - console.log("touchStart: " + touchStartCounter); - }; -``` +Note: For development purposes, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation

API

@@ -110,5 +89,41 @@ If the touch point is placed upon the touch surface again, it will fire another +

Example

Upon a touchstart event firing, fa-touchstart will evaluate the expression bound to it.

+

Touchstart fires once when a touch point (finger) is first placed upon the touch surface. +If the touch point moves or releases touch, it will not fire another touchstart; touchstart fires once upon the first touch. +If the touch point is placed upon the touch surface again, it will fire another touchstart event.

+

Fa-touchstart on an fa-surface

+

Fa-touchstart can be used on an fa-surface. Internally, a Famous Surface has a .on() method that binds a callback function to an event type handled by that Surface. + The function expression bound to fa-touchstart is bound to that fa-surface's touchstart eventHandler, and when touchstart fires, the function expression will be called.

+
<fa-modifier fa-size="[100, 100]">
+  <fa-surface fa-touchstart="touchStart($event)" fa-background-color="'red'"></fa-surface>
+</fa-modifier>
+
  var touchStartCounter = 0;
+  $scope.touchStart = function($event) {
+    touchStartCounter++;
+    console.log($event);
+    console.log("touchStart: " + touchStartCounter);
+  };
+

Fa-touchstart on an fa-view

+

Fa-touchstart may be used on an fa-view. The function expression bound to fa-touchstart will be bound to the fa-view's internal _eventInput, the aggregation point of all events received by the fa-view. When it receives a touchstart event, it will call the function expression bound to fa-touchstart.

+

In the example below, the fa-surface pipes its Surface events to an instantied Famous Event Handler called myEvents. +Fa-view pipes from myEvents, receiving all events piped by the fa-surface.

+

When a touchstart event occurs on the fa-surface, it is piped to the fa-view.
fa-touchstart defines a callback function in which to handle touchstart events, and when it receives a touchstart event, it calls touchStart().

+
<fa-view fa-touchstart="touchStart($event)" fa-pipe-from="myEvents">
+  <fa-modifier fa-size="[100, 100]">
+    <fa-surface fa-pipe-to="myEvents"
+                fa-background-color="'orange'">
+    </fa-surface>
+  </fa-modifier>
+</fa-view>
+
var EventHandler = $famous['famous/core/EventHandler'];
+$scope.myEvents = new EventHandler();
+
+$scope.touchStart = function($event) {
+  console.log($event);
+  console.log("fa-view receives the touchstart event from the fa-surface, and calls $scope.touchStart bound to fa-touchstart");
+};
+ diff --git a/docs/unstable/directive/faView/index.md b/docs/unstable/directive/faView/index.md index 7313556f..d3b897b1 100644 --- a/docs/unstable/directive/faView/index.md +++ b/docs/unstable/directive/faView/index.md @@ -48,25 +48,6 @@ Use an `` surrounded by a `` in order to affect the View's ``` -A Famous View is a Render Node that has its own input EventHandler and output EventHandler. -It may consist of many Modifier & Surfaces a complex set of event handlers. -A View's input eventHandler is the aggregation point of all events coming into the View, and then the View can handle all of those events in ways specified. - -For example, a Scroll View is a Famous View that has been extended with certain sets of behavior. -When a surface within a Scroll View receives an event (such as mouse scroll), and these events are piped to the Scroll View, these events go through the Scroll View's input EventHandler and are handled by the Scroll View. - -```html - - - - - - - -``` - -This brings up another important note: in the Famous event model, an fa-view nested within another fa-view does not automatically propagate its events to its parent. -For a longer discussion on Famous-Angular events, go to fa-pipe-from/fa-pipe-to in the docs. @@ -74,5 +55,25 @@ For a longer discussion on Famous-Angular events, go to fa-pipe-from/fa-pipe-to +

Example

A Famous View is used for encapsulating many Modifiers and Surfaces together. Internally, it is a Render Node that has its own input EventHandler (_eventInput) and output EventHandler (_eventOutput). +It does not map to DOM elements, but rather, it is an empty Render Node that can be extended by a developer. +A View's input eventHandler is the aggregation point of all events coming into the View, and from there, the View can listen for specific events and handle them.

+

A more concrete example is a Scroll View: it is a Famous View that has been extended with certain sets of behavior to handle events such as a mouse scroll. +In the example below, when an fa-surface within an fa-scroll-view propagates an event (such as mouse scroll), these events are piped to the Scroll View (through fa-pipe-to). These events go through the Scroll View's _eventInput (using fa-pipe-from). From there, the Scroll View has pre-defined event handlers to handle these events.

+

Famous Views are a way to encapsulate large event systems with renderables (Surfaces & Modifiers).

+
<fa-scroll-view fa-pipe-from="myEventHandler">
+  <fa-view>
+    <fa-modifier fa-size="[320, 320]">
+        <fa-surface fa-pipe-to="myEventHandler"></fa-surface>
+      </fa-modifier>
+  </fa-view>
+</fa-scroll-view>
+
var EventHandler = $famous['famous/core/EventHandler'];
+$scope.myEventHandler = new EventHandler();
+

Event propagation within & between Views

+

In the Famous event model, an fa-view nested within another fa-view does not automatically propagate its events to its parent. +Not even an fa-surface nested inside an fa-view propagates its events to the fa-view. All events to an fa-view must be piped explicitly.

+

For a more thorough discussion on Famous-Angular events, go to fa-pipe-from/fa-pipe-to in the docs.

+ diff --git a/famous-angular-docs b/famous-angular-docs index 50ad8adc..35f2e43f 160000 --- a/famous-angular-docs +++ b/famous-angular-docs @@ -1 +1 @@ -Subproject commit 50ad8adc83ff2bb87bb39fec1f6ad15a2bb488f2 +Subproject commit 35f2e43f4d4c27ca3c04ec4fab918ff39f436129 diff --git a/src/scripts/directives/fa-app.js b/src/scripts/directives/fa-app.js index 833f3bc3..1f97b8de 100644 --- a/src/scripts/directives/fa-app.js +++ b/src/scripts/directives/fa-app.js @@ -35,12 +35,18 @@ * Declaring multiple fa-app's within a page is permitted, but each new one incurs a penalty to performance, and `fa-app`'s should definitely not be declared within an ng-repeat. * * ### Fa-app must be declared with a height & width - * The element fa-app is declared within must have a height and width styling, declared inline or as a css declaration in an external stylesheet. + * The element `fa-app` is declared within must have a set height and width styling, declared inline or as a css declaration in an external stylesheet. * ```html * * * * ``` + * If `fa-app` is declared as an attribute of another element, that element must be a `display:block` element, such as a `div` or `p`. + * ```html + *
+ * + *
+ * ``` */ angular.module('famous.angular') diff --git a/src/scripts/directives/fa-click.js b/src/scripts/directives/fa-click.js index b707a1d2..f07abd1d 100644 --- a/src/scripts/directives/fa-click.js +++ b/src/scripts/directives/fa-click.js @@ -15,7 +15,8 @@ * * ``` * @example - * `Fa-click` is most commonly used on a `fa-surface`'. Internally, a Famous Surface has a `".on()"` method that binds a callback function to an event type handled by that Surface. + * ### Fa-click on an fa-surface + * `Fa-click` can be used on an `fa-surface`. Internally, a Famous Surface has a `.on()` method that binds a callback function to an event type handled by that Surface. * The function expression bound to `fa-click` is bound to that `fa-surface`'s click eventHandler, and when the `fa-surface` is clicked, the function expression will be called. * * ```html @@ -29,6 +30,32 @@ * console.log($event); * }; * ``` + * ### Fa-click on an fa-view + * `Fa-click` may be used on an `fa-view`. The function expression bound to `fa-click` will be bound to the `fa-view`'s internal `_eventInput`, the aggregation point of all events received by the `fa-view`. When it receives a `click` event, it will call the function expression bound to `fa-click`. + * + * In the example below, the `fa-surface` pipes its Surface events to an instantied Famous Event Handler called `myEvents`. + * `Fa-view` pipes from `myEvents`, receiving all events piped by the `fa-surface`. + * + * When a click event occurs on the `fa-surface`, it is piped to the `fa-view`. + * `fa-click` defines a callback function in which to handle click events, and when it receives a click event, it calls `myClickHandler()`. + * ```html + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.myEvents = new EventHandler(); + * + * $scope.myClickHandler = function($event) { + * console.log($event); + * console.log("fa-view receives the click event from the fa-surface, and calls myClickHandler defined on fa-click"); + * }; + * ``` */ angular.module('famous.angular') diff --git a/src/scripts/directives/fa-index.js b/src/scripts/directives/fa-index.js index 2dd61b37..98339374 100644 --- a/src/scripts/directives/fa-index.js +++ b/src/scripts/directives/fa-index.js @@ -24,6 +24,7 @@ * In this example below, a Scroll View is created with two nested `fa-view`'s, both of which have an `fa-index` of 0 and 1, respectively. * * If `fa-index` is declared explicitly, it will override any default order of `fa-view`'s declared in html. + * If `fa-views` are created with an ng-repeat, they are automatically assigned the $index property, unless explicitly set. * The `fa-view` with the blue background color appears after the one with the red background because its `fa-index` is set to 1. * * `fa-scroll-view` accepts another directive called `fa-start-index` as an attribute, which determines which `fa-view` the Scroll View displays by default. diff --git a/src/scripts/directives/fa-render-node.js b/src/scripts/directives/fa-render-node.js index 0ad0736d..0447e327 100644 --- a/src/scripts/directives/fa-render-node.js +++ b/src/scripts/directives/fa-render-node.js @@ -13,6 +13,7 @@ * * * ``` + * @example * `Fa-render-node` can wrap a custom-made widget or any renderable component from Famous and allow it to be inserted in the Render Tree. * * All Famous widgets, such as a Scroll View, a Sequential Layout, or a Header-footer-layout, are extended Famous Views. diff --git a/src/scripts/directives/fa-scrollview.js b/src/scripts/directives/fa-scrollview.js index ce432b11..f7a56e34 100644 --- a/src/scripts/directives/fa-scrollview.js +++ b/src/scripts/directives/fa-scrollview.js @@ -16,144 +16,152 @@ * * * ``` - - @example - - ScrollView + Events + ng-repeat - --------------------------------- - In the example below, fa-scrollview displays a collection of nested fa-views generated by an ng-repeat directive. - In Famous, events are used to move information between widgets (such as ScrollView) and nested views. - When a nested view needs to trigger higher-order app behavior within another view (such as a widget), the best practice is to pass data via events. - - Input events are captured on surfaces, and it is up the developer to specify where the events will broadcast and receive events by piping. - To use a scroll view, create a Famous EventHandler on the scope, pipe the surface events to the event handler using fa-pipe-to, and then pipe that event handler to the ScrollView using fa-pipe-from. - This will enable scrolling by connecting input events from the surfaces to the Scroll View. - -* ```javascript -* var EventHandler = $famous['famous/core/EventHandler']; -* $scope.eventHandler = new EventHandler(); -* -* $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; -* ``` - -* ```html -* -* -* -* -*
{{item.content}}
-* -* -* -* -* ``` - -To specify (optional) configurable options for the Scroll View, pass in an object on the scope. -Notable options include clipSize, which specifies the size of the area in pixels that the ScrollView will display content in, and direction, which specifies whether the nested views will scroll horizontally or vertically (1 is vertical, 0 is horizontal). -A full list of configurable options for Scroll View may be found at https://famo.us/docs/0.2.0/views/Scrollview/. - -* ```javascript -* var EventHandler = $famous['famous/core/EventHandler']; -* $scope.eventHandler = new EventHandler(); -* $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; -* -* $scope.options = { -* myScrollView: { -* clipSize: 568, -* paginated: true, -* speedLimit: 5, -* direction: 1, -* } -* }; -* ``` - -ScrollView with explicitly created views ------------------------------------------ -In this example below, a scrollview is created with two nested fa-view's, both of which have an fa-index of 0 and 1, respectively. -Fa-index determines the order of which the surfaces appear in the sequential view. -If fa-index is declared explicitly, it will override any default order of elements declared in html. -As in the example below, the fa-view with the blue background color appears after the one with the red background because its fa-index is set to 1. -If fa-views are created with an ng-repeat, they are automatically assigned the $index property, unless explicitly set. - -The scrollView directive accepts another directive called fa-start-index as an attribute, and this determines which view the scrollView displays by default. -Fa-start-index will not affect the sequential order of the layout; the view with the red background will be layed out first, followed by the view with the blue background. -With this attribute set to 1, the scroll view will display the view with the index of 1, which is the view with the blue background color. - -* ```html - - - - - - - - - - - - -* ``` - -* ```javascript -* var EventHandler = $famous['famous/core/EventHandler']; -* $scope.eventHandler = new EventHandler(); -* $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; -* -$scope.options = { - scrollViewTwo: { - direction: 0 - } -}; -* ``` - -Multiple scroll views ---------------------- -Combining both approaches above (a scrollview with ng-repeated views, and one with two explicitly created views), one can can nest a ScrollView within another ScrollView. -A Scroll View is a widget that displays a collection of views sequentially - it is agnostic about the views that are inside of it; it only requires that events are piped from surfaces to the ScrollView. - -In the example below, the outer scrollview contains two explictly created views. One of those views contains a scrollview with sub-views created through an ngRepeat directive. -The outer ScrollView is passed an option for its direction to be horizontal (0), and the inner ScrollView is passed an option for a vertical direction (1). - -* ```html - - - - - - - - - - - - - -
{{item.content}}
- - - - - - - -* ``` - -* ```javascript -* var EventHandler = $famous['famous/core/EventHandler']; -* $scope.eventHandler = new EventHandler(); -* $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; -* - $scope.options = { - scrollViewOuter: { - direction: 0, - paginated: true - }, - scrollViewInner :{ - direction: 1 - } - }; -* ``` - + * + * @example + * ### Scroll View + Events + ng-repeat + * In the example below, `fa-scroll-view` displays a collection of nested `fa-views` generated by ng-repeat. + * In Famous, events are not propagated from these nested `fa-view`'s to its parent `fa-scroll-view`. + * + * When a nested View needs to trigger higher-order app behavior within another View (such as a Scroll View), the best practice is to pass data via Famous Events. + * + * To use a Scroll View, create an instance of a Famous Event Handler on the scope. Pipe all Surface events to the event handler using `fa-pipe-to`, and then specify that the Scroll View will receive events from that specific event handler using `fa-pipe-from`. + * + * Input events (like click) are captured on Surfaces, and piping must be used to specify where the events will broadcast and be received. + * This will enable scrolling by connecting input events from the `fa-surface`s to the `fa-scroll-view`, otherwise the Scroll View will not receive mousewheel events. + * + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.eventHandler = new EventHandler(); + * + * $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; + * ``` + * ```html + * + * + * + * + * + * + * + * + * ``` + * + * To specify (optional) configurable options for the Scroll View, bind an object on the scope to the `fa-options` attribute on `fa-scroll-view`. + * Notable options include `clipSize`, which specifies the size of the area in pixels to display content in, and `direction`, which specifies whether the nested views will scroll horizontally or vertically (1 is vertical, 0 is horizontal). + * A full list of configurable options for Scroll View may be found at https://famo.us/docs/0.2.0/views/Scrollview/. + * + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.eventHandler = new EventHandler(); + * $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; + * + * $scope.options = { + * myScrollView: { + * clipSize: 568, + * paginated: true, + * speedLimit: 5, + * direction: 1, + * } + * }; + * ``` + * + * ### Scroll View with explicitly created views + * `Fa-index` determines the order of which the surfaces appear in the sequential view. + * In this example below, a Scroll View is created with two nested `fa-view`'s, both of which have an `fa-index` of 0 and 1, respectively. + * + * If `fa-index` is declared explicitly, it will override any default order of `fa-view`'s declared in html. + * If `fa-views` are created with an ng-repeat, they are automatically assigned the $index property, unless explicitly set. + * The `fa-view` with the blue background color appears after the one with the red background because its `fa-index` is set to 1. + * + * `fa-scroll-view` accepts another directive called `fa-start-index` as an attribute, which determines which `fa-view` the Scroll View displays by default. + * `Fa-start-index` will not affect the sequential order of the layout; the `fa-view` with the red background will be layed out first, followed by the one with the blue background. + * By setting `fa-start-index` to 1, the Scroll View will display the View with the index of 1 by default, "starting" at the index of 1, which is the View with the blue background color. + * + * ```html + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.eventHandler = new EventHandler(); + * $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; + * + * $scope.options = { + * scrollViewTwo: { + * direction: 0 + * } + * }; + * ``` + * + * ### Combining multiple Scroll Views + * + * Combining both approaches above (a Scroll View with ng-repeated views, and one with explicitly created views), one can can nest a Scroll View within another Scroll View. + * A Scroll View is a Famous widget that displays a collection of views sequentially; it is agnostic about the Views that are inside of it; it only requires that events are piped from Surfaces to the ScrollView. + * + * In the example below, the outer Scroll View contains two explictly created Views. One of those Views contains another Scroll View with sub-views created through an ngRepeat. + * The outer Scroll View is passed an option for its `direction` to be `horizontal (0)`, and the inner Scroll View is passed an option for a `vertical direction (1)`. + * + * ```html + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
{{item.content}}
+ * + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.eventHandler = new EventHandler(); + * $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}]; + * + * $scope.options = { + * scrollViewOuter: { + * direction: 0, + * paginated: true + * }, + * scrollViewInner :{ + * direction: 1 + * } + * }; + * ``` */ angular.module('famous.angular') diff --git a/src/scripts/directives/fa-touchend.js b/src/scripts/directives/fa-touchend.js index a2c01e5e..0f815097 100644 --- a/src/scripts/directives/fa-touchend.js +++ b/src/scripts/directives/fa-touchend.js @@ -13,29 +13,58 @@ * * * ``` - -Note: For testing purposes during development, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation - -##Example -Upon a touchend event firing, fa-touchend will evaluate the expression bound to it. - -Touchstart fires once upon first touch; touchmove fires as the touch point is moved along a touch surface; touchend fires upon release of the touch point. - -```html - - - -``` - -```javascript -var touchEndCounter = 0; -$scope.touchEnd = function($event) { - touchEndCounter++; - console.log($event); - console.log("touchEnd: " + touchEndCounter); -}; -qqq - + * + * Note: For testing purposes during development, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation + * + * @example + * Upon a touchend event firing, fa-touchend will evaluate the expression bound to it. + * + * Touchstart fires once upon first touch; touchend fires as the touch point is moved along a touch surface; touchend fires upon release of the touch point. + * + * ### Fa-touchend on an fa-surface + * `Fa-touchend` can be used on an `fa-surface`. Internally, a Famous Surface has a `.on()` method that binds a callback function to an event type handled by that Surface. + * The function expression bound to `fa-touchend` is bound to that `fa-surface`'s touchend eventHandler, and when touchend fires, the function expression will be called. + * + * ```html + * + * + * + * ``` + * ```javascript + * var touchEndCounter = 0; + * $scope.touchEnd = function($event) { + * touchEndCounter++; + * console.log($event); + * console.log("touchEnd: " + touchEndCounter); + * }; + * ``` + * + * ### Fa-touchend on an fa-view + * `Fa-touchend` may be used on an `fa-view`. The function expression bound to `fa-touchend` will be bound to the `fa-view`'s internal `_eventInput`, the aggregation point of all events received by the `fa-view`. When it receives a `touchend` event, it will call the function expression bound to `fa-touchend`. + * + * In the example below, the `fa-surface` pipes its Surface events to an instantied Famous Event Handler called `myEvents`. + * `Fa-view` pipes from `myEvents`, receiving all events piped by the `fa-surface`. + * + * When a touchend event occurs on the `fa-surface`, it is piped to the `fa-view`. + * `fa-touchend` defines a callback function in which to handle touchend events, and when it receives a touchend event, it calls `touchEnd()`. + * ```html + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.myEvents = new EventHandler(); + * + * $scope.touchEnd = function($event) { + * console.log($event); + * console.log("fa-view receives the touchend event from the fa-surface, and calls $scope.touchEnd bound to fa-touchend"); + * }; + * ``` */ angular.module('famous.angular') diff --git a/src/scripts/directives/fa-touchmove.js b/src/scripts/directives/fa-touchmove.js index a8ae5b5a..35fa1eba 100644 --- a/src/scripts/directives/fa-touchmove.js +++ b/src/scripts/directives/fa-touchmove.js @@ -13,31 +13,61 @@ * * * ``` - -Note: For testing purposes during development, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation - -##Example -Upon a touchmove event firing, fa-touchmove will evaluate the expression bound to it. - -Touchstart fires once upon first touch; touchmove fires as the touch point is moved along a touch surface, until release of the touch point. -The rate of which touchmove events fire is implementation-defined by browser and hardware. -Upon each firing, fa-touchmove evaluates the expression bound to it. - -```html - - - -``` - -```javascript -var touchMoveCounter = 0; -$scope.touchMove = function($event) { - touchMoveCounter++; - console.log($event); - console.log("touchMove: " + touchMoveCounter); -}; -``` - + * + * Note: For development purposes, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation + * + * @example + * Upon a touchmove event firing, `fa-touchmove` will evaluate the expression bound to it. + * + * touchmove fires once upon first touch; touchmove fires as the touch point (finger) is moved along a touch surface, until release of the touch point. + * The rate of which touchmove events fire is implementation-defined by browser and hardware. + * `fa-touchmove` evaluates the expression bound to it upon each firing of touchmove. + * + * ### Fa-touchmove on an fa-surface + * `Fa-touchmove`can be used on an `fa-surface`. Internally, a Famous Surface has a `.on()` method that binds a callback function to an event type handled by that Surface. + * The function expression bound to `fa-touchmove` is bound to that `fa-surface`'s touchmove eventHandler, and when touchmove fires, the function expression will be called. + * + * ```html + * + * + * + * ``` + * ```javascript + * var touchMoveCounter = 0; + * $scope.touchMove = function($event) { + * touchMoveCounter++; + * console.log($event); + * console.log("touchMove: " + touchMoveCounter); + * }; + * ``` + * + * ### Fa-touchmove on an fa-view + * `Fa-touchmove` may be used on an `fa-view`. The function expression bound to `fa-touchmove` will be bound to the `fa-view`'s internal `_eventInput`, the aggregation point of all events received by the `fa-view`. When it receives a `touchmove` event, it will call the function expression bound to `fa-touchmove`. + * + * In the example below, the `fa-surface` pipes its Surface events to an instantied Famous Event Handler called `myEvents`. + * `Fa-view` pipes from `myEvents`, receiving all events piped by the `fa-surface`. + * + * When a touchmove event occurs on the `fa-surface`, it is piped to the `fa-view`. + * `fa-touchmove` defines a callback function in which to handle touchmove events, and when it receives a touchmove event, it calls `touchMove()`. + * + * ```html + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.myEvents = new EventHandler(); + * + * $scope.touchMove = function($event) { + * console.log($event); + * console.log("fa-view receives the touchmove event from the fa-surface, and calls $scope.touchMove bound to fa-touchmove"); + * }; + * ``` */ angular.module('famous.angular') diff --git a/src/scripts/directives/fa-touchstart.js b/src/scripts/directives/fa-touchstart.js index 773ee2fe..e03b7122 100644 --- a/src/scripts/directives/fa-touchstart.js +++ b/src/scripts/directives/fa-touchstart.js @@ -13,30 +13,61 @@ * * * ``` - -Note: For testing purposes during development, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation - -##Example -Upon a touchstart event firing, fa-touchstart will evaluate the expression bound to it. - -Touchstart fires once when a touch point (finger) is first placed upon the touch surface. -If the touch point moves or releases touch, it will not fire a touchstart. -If the touch point is placed upon the touch surface again, it will fire another touchstart event. - -```html - - - -``` -```javascript - var touchStartCounter = 0; - $scope.touchStart = function($event) { - touchStartCounter++; - console.log($event); - console.log("touchStart: " + touchStartCounter); - }; -``` -*/ + * + * Note: For development purposes, enable mobile emulation: https://developer.chrome.com/devtools/docs/mobile-emulation + * + * @example + * Upon a `touchstart` event firing, `fa-touchstart` will evaluate the expression bound to it. + * + * Touchstart fires once when a touch point (finger) is first placed upon the touch surface. + * If the touch point moves or releases touch, it will not fire another touchstart; touchstart fires once upon the first touch. + * If the touch point is placed upon the touch surface again, it will fire another touchstart event. + * + * ### Fa-touchstart on an fa-surface + * `Fa-touchstart` can be used on an `fa-surface`. Internally, a Famous Surface has a `.on()` method that binds a callback function to an event type handled by that Surface. + * The function expression bound to `fa-touchstart` is bound to that `fa-surface`'s touchstart eventHandler, and when touchstart fires, the function expression will be called. + * + * ```html + * + * + * + * ``` + * ```javascript + * var touchStartCounter = 0; + * $scope.touchStart = function($event) { + * touchStartCounter++; + * console.log($event); + * console.log("touchStart: " + touchStartCounter); + * }; + * ``` + * + * ### Fa-touchstart on an fa-view + * `Fa-touchstart` may be used on an `fa-view`. The function expression bound to `fa-touchstart` will be bound to the `fa-view`'s internal `_eventInput`, the aggregation point of all events received by the `fa-view`. When it receives a `touchstart` event, it will call the function expression bound to `fa-touchstart`. + * + * In the example below, the `fa-surface` pipes its Surface events to an instantied Famous Event Handler called `myEvents`. + * `Fa-view` pipes from `myEvents`, receiving all events piped by the `fa-surface`. + * + * When a touchstart event occurs on the `fa-surface`, it is piped to the `fa-view`. + * `fa-touchstart` defines a callback function in which to handle touchstart events, and when it receives a touchstart event, it calls `touchStart()`. + * ```html + * + * + * + * + * + * + * ``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.myEvents = new EventHandler(); + * + * $scope.touchStart = function($event) { + * console.log($event); + * console.log("fa-view receives the touchstart event from the fa-surface, and calls $scope.touchStart bound to fa-touchstart"); + * }; + * ``` + */ angular.module('famous.angular') .directive('faTouchstart', ['$parse', '$famousDecorator', function ($parse, $famousDecorator) { diff --git a/src/scripts/directives/fa-view.js b/src/scripts/directives/fa-view.js index 416b245d..dc4e07dc 100644 --- a/src/scripts/directives/fa-view.js +++ b/src/scripts/directives/fa-view.js @@ -13,25 +13,35 @@ * * * ``` - * A Famous View is a Render Node that has its own input EventHandler and output EventHandler. - * It may consist of many Modifier & Surfaces a complex set of event handlers. - * A View's input eventHandler is the aggregation point of all events coming into the View, and then the View can handle all of those events in ways specified. + * @example + * A Famous View is used for encapsulating many Modifiers and Surfaces together. Internally, it is a Render Node that has its own input EventHandler (`_eventInput`) and output EventHandler (`_eventOutput`). + * It does not map to DOM elements, but rather, it is an empty Render Node that can be extended by a developer. + * A View's input eventHandler is the aggregation point of all events coming into the View, and from there, the View can listen for specific events and handle them. * - * For example, a Scroll View is a Famous View that has been extended with certain sets of behavior. - * When a surface within a Scroll View receives an event (such as mouse scroll), and these events are piped to the Scroll View, these events go through the Scroll View's input EventHandler and are handled by the Scroll View. + * A more concrete example is a Scroll View: it is a Famous View that has been extended with certain sets of behavior to handle events such as a mouse scroll. + * In the example below, when an `fa-surface` within an `fa-scroll-view` propagates an event (such as mouse scroll), these events are piped to the Scroll View (through `fa-pipe-to`). These events go through the Scroll View's `_eventInput` (using `fa-pipe-from`). From there, the Scroll View has pre-defined event handlers to handle these events. + * + * Famous Views are a way to encapsulate large event systems with renderables (Surfaces & Modifiers). * *```html - * + * * * - * + * * * - * + * *``` + * ```javascript + * var EventHandler = $famous['famous/core/EventHandler']; + * $scope.myEventHandler = new EventHandler(); + * ``` + * + * ### Event propagation within & between Views + * In the Famous event model, an `fa-view` nested within another `fa-view` does not automatically propagate its events to its parent. + * Not even an `fa-surface` nested inside an `fa-view` propagates its events to the `fa-view`. All events to an `fa-view` must be piped explicitly. * - *This brings up another important note: in the Famous event model, an fa-view nested within another fa-view does not automatically propagate its events to its parent. - *For a longer discussion on Famous-Angular events, go to fa-pipe-from/fa-pipe-to in the docs. + * For a more thorough discussion on Famous-Angular events, go to fa-pipe-from/fa-pipe-to in the docs. */ angular.module('famous.angular')