Skip to content

Commit

Permalink
docs: add scrollview examples + add headings modifier surface
Browse files Browse the repository at this point in the history
  • Loading branch information
@thuongvu
thuongvu committed Jun 4, 2014
1 parent e574667 commit 4ea11ad
Show file tree
Hide file tree
Showing 8 changed files with 342 additions and 43 deletions.
135 changes: 122 additions & 13 deletions dist/famous-angular.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1070,6 +1070,9 @@ angular.module('famous.angular')
* ```
* @example
The order of transforms matter
------------------------------
* You can specify the order of transforms by nesting modifiers. For instance, if you translate an element and then rotate it, the result will be different than if you had rotated it and then translated it.
* ```html
Expand All @@ -1086,8 +1089,12 @@ angular.module('famous.angular')
* </fa-modifier>
* ```
Values for fa-modifier attributes
---------------------------------
Fa-modifier properties, (such as faRotate, faScale, etc) can be bound to number/arrays, object properties defined on the scope, function references, and sometimes a transitionable object.
Number/Array values
-------------------
* @example
* fa-modifier properties can be bound to number/array values.
* html:
Expand All @@ -1097,6 +1104,8 @@ Fa-modifier properties, (such as faRotate, faScale, etc) can be bound to number/
* </fa-modifier>
* ```
Object properties on the scope
------------------------------
* @example
*fa-modifier properties can be bound to object properties defined on the scope.
* html:
Expand All @@ -1105,24 +1114,24 @@ Fa-modifier properties, (such as faRotate, faScale, etc) can be bound to number/
* <fa-surface fa-background-color="'red'"></fa-surface>
* </fa-modifier>
* ```
*controller:
* ```javascript
$scope.boxObject = {
* origin: [.4, .4],
* size: [50, 50]
* }
* ```
Functions
---------
* @example
* fa-modifier properties can be bound to a function on the scope that returns a value.
* Fa-modifier properties can be bound to a function on the scope that returns a value.
html
* ```html
* <fa-modifier fa-origin="genBoxOrigin">
* <fa-surface fa-background-color="'red'"></fa-surface>
* </fa-modifier>
* ```
Controller
* ```javascript
* $scope.getX = function() {
* return .2;
Expand All @@ -1135,22 +1144,24 @@ Controller
* };
* ```
Transitionable objects & .get()
-------------------------------
@example
For some modifier properties, (faOpacity, faSize, faOrigin, faAlign) you can bind them to a Transitionable object directly.
In the example below, we instantiate transitionable objects to change translate and opacity values inside $scope.box.
The value of fa-opacity is bound to box.opacity on the scope, a transitionable object.
For other properties that do not accept transitionable objects directly, they may be found to a function reference. You can create a transitionable object, and then bind the transitionable's .get() method to the modifier. .get() is a method that all transitionables have, and it returns the interpolated state of the transition, either a number or an object.
For other properties that do not accept transitionable objects directly, they may be found to a function reference.
You can create a transitionable object, and then bind the transitionable's .get() method to the modifier.
All transitionables have a .get() method that returns the interpolated state of the transition at a current time, returning either a number or an object.
In the view, we bind fa-translate to box.translate.get(), a function that will return a value.
A click on the surface invokes the animateBox function on the controller, which will trigger the transition between the initial state to the state specified with the transitionable's .set() method.
* Html
* ```html
* <fa-modifier fa-translate="box.translate.get()" fa-size="[100, 100]" fa-opacity="box.opacity">
* <fa-surface fa-click="animateBox()" fa-background-color="'red'"></fa-surface>
* </fa-modifier>
* ```
* Controller
* ```javascript
* var Transitionable = $famous['famous/transitions/Transitionable'];
* $scope.box = {
Expand All @@ -1163,13 +1174,14 @@ Controller
* };
* ```
Animating properties
--------------------
* @example
* Remember that Famous surfaces are styled with position:absolute, and their positions are defined by matrix3d webkit transforms. Modifiers are to be used to hold onto size, transform, origin, and opacity states, and also to be animated.
* As per vanilla Famous, you should animate properties of modifiers, such as transform, align, opacity, etc, rather than on the surface itself, as modifiers are responsible for layout and visibility.
* html:
* ```html
*<fa-modifier fa-rotate-z="boxA.rotate.get()">
* <fa-surface fa-click="animateBoxA()" fa-background-color="'red'">rotate -> translate</fa-surface>
* <fa-modifier fa-rotate-z="boxA.rotate.get()">
* <fa-surface fa-click="animateBoxA()" fa-background-color="'red'"></fa-surface>
* </fa-modifier>
* ```
Expand Down Expand Up @@ -1557,11 +1569,14 @@ angular.module('famous.angular')
* ```
@example
Scroll View + 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 Scroll View) 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.
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 Scroll View using fa-pipe-from.
This will enable scrolling by connecting input events from the surfaces to the Scroll View.
Expand All @@ -1584,11 +1599,15 @@ angular.module('famous.angular')
* </fa-scroll-view>
* ```
To specify (optional) configurable options for the Scroll View, pass in an object on the scope.
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,
Expand All @@ -1599,6 +1618,93 @@ A full list of configurable options for Scroll View may be found at https://famo
* };
* ```
Scroll View 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 (scrollView in this case).
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
<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>
* ```
* ```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 scroll view with ng-repeated views, and one with two explicitly created views), one can can nest a Scroll View within another Scroll View.
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 Scroll View.
In the example below, the outer scroll view contains two explictly created views. One of those views contains a scroll view with sub-views created through an ngRepeat directive.
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
<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>
* ```
* ```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')
Expand Down Expand Up @@ -1742,7 +1848,10 @@ $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}];
*Common Problems
*---------------
You may expect to animate properties such as size or originProperties related to layout and visibility belong on the modifier, while surfaces are roughly equivalent to "divs".
Properties on surfaces vs modifiers
-----------------------------------
You may expect to animate properties such as size or origin. However, with Famous, properties related to layout and visibility belong on the modifier, and the surface should be nested below the modifier.
While you can specify fa-size as well as some other layout/visibility properties on surfaces themselves, it is not recommended.
This is not best practice:
Expand Down
26 changes: 15 additions & 11 deletions docs/unstable/directive/faModifier/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -310,7 +310,8 @@ to values (e.g. `fa-translate="[15, 20, 1]"`, Famo.us Transitionable objects, or



<h2 id="example">Example</h2><p>You can specify the order of transforms by nesting modifiers. For instance, if you translate an element and then rotate it, the result will be different than if you had rotated it and then translated it. </p>
<h2 id="example">Example</h2><h2 id="the-order-of-transforms-matter">The order of transforms matter</h2>
<p>You can specify the order of transforms by nesting modifiers. For instance, if you translate an element and then rotate it, the result will be different than if you had rotated it and then translated it. </p>
<pre><code class="lang-html">&lt;fa-modifier fa-translate=&quot;[100, 100]&quot;&gt;
&lt;fa-modifier fa-rotate-z=&quot;.6&quot; fa-size=&quot;[100, 100]&quot;&gt;
&lt;fa-surface fa-background-color=&quot;red&quot;&gt;translate --&gt; rotate&lt;/fa-surface&gt;
Expand All @@ -322,28 +323,29 @@ to values (e.g. `fa-translate="[15, 20, 1]"`, Famo.us Transitionable objects, or
&lt;fa-surface class=&quot;red&quot;&gt;&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;
&lt;/fa-modifier&gt;</code></pre>
<h2 id="values-for-fa-modifier-attributes">Values for fa-modifier attributes</h2>
<p>Fa-modifier properties, (such as faRotate, faScale, etc) can be bound to number/arrays, object properties defined on the scope, function references, and sometimes a transitionable object.</p>
<h2 id="number-array-values">Number/Array values</h2>
<p>fa-modifier properties can be bound to number/array values.
html:</p>
<pre><code class="lang-html"> &lt;fa-modifier fa-origin=&quot;[.5,.5]&quot; fa-size=&quot;[100, 100]&quot; fa-rotate=&quot;.3&quot;&gt;
&lt;fa-surface fa-background-color=&quot;&#39;red&#39;&quot;&gt;&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>
<h2 id="object-properties-on-the-scope">Object properties on the scope</h2>
<p>fa-modifier properties can be bound to object properties defined on the scope.
html:</p>
<pre><code class="lang-html">&lt;fa-modifier fa-origin=&quot;boxObject.origin&quot; fa-size=&quot;boxObject.size&quot;&gt;
&lt;fa-surface fa-background-color=&quot;&#39;red&#39;&quot;&gt;&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>
<p>controller:</p>
<pre><code class="lang-javascript"> $scope.boxObject = {
origin: [.4, .4],
size: [50, 50]
}</code></pre>
<p>fa-modifier properties can be bound to a function on the scope that returns a value.</p>
<p>html</p>
<h2 id="functions">Functions</h2>
<p>Fa-modifier properties can be bound to a function on the scope that returns a value.</p>
<pre><code class="lang-html">&lt;fa-modifier fa-origin=&quot;genBoxOrigin&quot;&gt;
&lt;fa-surface fa-background-color=&quot;&#39;red&#39;&quot;&gt;&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>
<p>Controller</p>
<pre><code class="lang-javascript">$scope.getX = function() {
return .2;
};
Expand All @@ -353,17 +355,18 @@ $scope.getY = function() {
$scope.genBoxOrigin = function() {
return [$scope.getX(), $scope.getY()];
};</code></pre>
<h2 id="transitionable-objects-get-">Transitionable objects &amp; .get()</h2>
<p>For some modifier properties, (faOpacity, faSize, faOrigin, faAlign) you can bind them to a Transitionable object directly.
In the example below, we instantiate transitionable objects to change translate and opacity values inside $scope.box.
The value of fa-opacity is bound to box.opacity on the scope, a transitionable object.</p>
<p> For other properties that do not accept transitionable objects directly, they may be found to a function reference. You can create a transitionable object, and then bind the transitionable&#39;s .get() method to the modifier. .get() is a method that all transitionables have, and it returns the interpolated state of the transition, either a number or an object.
<p> For other properties that do not accept transitionable objects directly, they may be found to a function reference.
You can create a transitionable object, and then bind the transitionable&#39;s .get() method to the modifier.
All transitionables have a .get() method that returns the interpolated state of the transition at a current time, returning either a number or an object.
In the view, we bind fa-translate to box.translate.get(), a function that will return a value.
A click on the surface invokes the animateBox function on the controller, which will trigger the transition between the initial state to the state specified with the transitionable&#39;s .set() method.</p>
<p>Html</p>
<pre><code class="lang-html">&lt;fa-modifier fa-translate=&quot;box.translate.get()&quot; fa-size=&quot;[100, 100]&quot; fa-opacity=&quot;box.opacity&quot;&gt;
&lt;fa-surface fa-click=&quot;animateBox()&quot; fa-background-color=&quot;&#39;red&#39;&quot;&gt;&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>
<p>Controller</p>
<pre><code class="lang-javascript">var Transitionable = $famous[&#39;famous/transitions/Transitionable&#39;];
$scope.box = {
translate: new Transitionable([200,200,0]),
Expand All @@ -373,10 +376,11 @@ $scope.box = {
$scope.box.translate.set([0, 100, 0], {duration: 500, curve: &#39;easeInOut&#39;});
$scope.box.opacity.set(1, {duration: 500, curve: &#39;easeInOut&#39;});
};</code></pre>
<h2 id="animating-properties">Animating properties</h2>
<p>Remember that Famous surfaces are styled with position:absolute, and their positions are defined by matrix3d webkit transforms. Modifiers are to be used to hold onto size, transform, origin, and opacity states, and also to be animated.
As per vanilla Famous, you should animate properties of modifiers, such as transform, align, opacity, etc, rather than on the surface itself, as modifiers are responsible for layout and visibility.<br>html:</p>
<pre><code class="lang-html">&lt;fa-modifier fa-rotate-z=&quot;boxA.rotate.get()&quot;&gt;
&lt;fa-surface fa-click=&quot;animateBoxA()&quot; fa-background-color=&quot;&#39;red&#39;&quot;&gt;rotate -&gt; translate&lt;/fa-surface&gt;
As per vanilla Famous, you should animate properties of modifiers, such as transform, align, opacity, etc, rather than on the surface itself, as modifiers are responsible for layout and visibility. </p>
<pre><code class="lang-html"> &lt;fa-modifier fa-rotate-z=&quot;boxA.rotate.get()&quot;&gt;
&lt;fa-surface fa-click=&quot;animateBoxA()&quot; fa-background-color=&quot;&#39;red&#39;&quot;&gt;&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>


Expand Down
Loading

0 comments on commit 4ea11ad

Please sign in to comment.