Skip to content

Commit

Permalink
docs: edit faSurface
Browse files Browse the repository at this point in the history
  • Loading branch information
@thuongvu
thuongvu committed Jun 11, 2014
1 parent 4ceb446 commit 540b39b
Show file tree
Hide file tree
Showing 4 changed files with 220 additions and 158 deletions.
156 changes: 88 additions & 68 deletions dist/famous-angular.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2607,80 +2607,100 @@ angular.module('famous.angular')
* Here's some data-bound content '{{myScopeVariable}}'
* </fa-surface>
* ```
*@example
* ```html
*<fa-modifier fa-size="[960, undefined]">
* <fa-surface fa-size="[undefined, undefined]">
* <div ng-include src=" 'views/animations.html' "></div>
* </fa-surface>
* </fa-modifier>
* ```
A simple ng-repeat of surfaces may look like this:
*@example
* ```html
<fa-modifier ng-repeat="item in list" fa-size="[100, 100]" fa-translate="[0, $index * 75, 0]">
<fa-surface fa-size="[undefined, undefined]">
{{item.content}}
</fa-surface>
</fa-modifier>
* ```
* ```javascript
$scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}];
* ```
*Common Problems
*---------------
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:
*@example
*
* @example
* An `fa-surface` can use an ng-include to compile an external HTML fragment:
* ```html
* <fa-modifier fa-size="[960, undefined]">
* <fa-surface fa-size="[undefined, undefined]">
* <div ng-include src=" 'views/animations.html' "></div>
* </fa-surface>
* </fa-modifier>
* ```
*
* A simple ng-repeat of surfaces can be implemented like this:
* ```html
<fa-surface fa-size="[100, 100]"></fa-surface>
* <fa-modifier ng-repeat="item in list" fa-size="[100, 100]" fa-translate="[0, $index * 75, 0]">
* <fa-surface fa-size="[undefined, undefined]">
* {{item.content}}
* </fa-surface>
* </fa-modifier>
* ```
Whereas this is the preferred approach:
*@example
*
* ```javascript
* $scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}];
* ```
*
* ##Common Confusions
* ### Properties on surfaces vs modifiers
* With Famous, properties related to layout and visibility belong on a Modifier. A Surface should be added below a Modifier on the Render Tree, as Modifiers affect everything below them.
*
* You may be tempted to set the `fa-origin` or another layout property on an fa-surface, and discover that it does not work:
* ```html
<fa-modifier fa-size="[100, 100]">
<fa-surface fa-size="[undefined, undefined]">
</fa-surface>
</fa-modifier>
* <fa-surface fa-origin="[.5, 0]">This will not change the origin.</fa-surface>
* ```
*
* While you can specify `fa-size` on surfaces themselves, it is not recommended.
* This is not best practice:
* ```html
* <fa-surface fa-size="[100, 100]"></fa-surface>
* ```
*
* Whereas this is the preferred approach:
* ```html
* <fa-modifier fa-size="[100, 100]">
* <fa-surface fa-size="[undefined, undefined]">
* </fa-surface>
* </fa-modifier>
* ```
*
* You may also omit `fa-size="[undefined, undefined]"` on the surface and the surface will fill to the size of the modifier, in this case, `[100, 100]`.
*
* In Famous' Render Tree, Modifiers modify all the nodes (other Modifiers and Surfaces) below them. By setting the `fa-surface`'s `fa-size` to `[undefined, undefined]`, it will inherit from the `fa-modifier`'s `fa-size` of `[100, 100]`.
*
* `Fa-surfaces` also cannot have an `fa-size`, assigned to a function, as is in the case of modifiers, which can take number/array or a function.
* For example, this will not work:
* ```html
* <fa-surface fa-size="sizeForBoxFunction"></fa-surface>
* ```
* ```javascript
* $scope.sizeForBoxFunction = function() {
* return [75, 75];
* };
* ```
* To reiterate, the best practice to animate or set any layout/visibilty properties of a surface is to do so on a modifier that affects the Surface. The purpose of a Surface is to contain HTML content, whether rendered from a template, or data-bound with {{}}'s.
* <fa-modifier fa-size="[100, 100]">
* <fa-surface fa-background-color="'red'"></fa-surface>
* </fa-modifier>
*
* ### fa-color & fa-background-color
* The exceptions are `fa-color` and `fa-background-color`: these two properties are passed through the `.setProperties()` method available on Famous Surfaces.
* Take note that they accept a string in the html view. If you do not enclose them in quotation marks, Angular will evaluate it as an object on the scope, but surrounding it with quotation marks will specify it as a string expression.
* ```html
* <fa-modifier fa-size="[200, 50]">
* <fa-surface fa-background-color="'orange'" fa-color="'#fff'">
* This text should be white.
* </fa-surface>
* </fa-modifier>
* ```
*
* ### ng-class
* Ng-Class works on `fa-surface`s:
* ```html
* <fa-modifier fa-size="[150, 50]">
* <fa-surface fa-background-color="'blue'" ng-class="{strike: applyStrike}">
* Strikethrough!
* <input type="checkbox" ng-model="applyStrike"></input>
* </fa-surface>
* </fa-modifier>
* ```
* ```css
* .strike {
* text-decoration: line-through;
* }
* ```
You may also omit fa-size="[undefined, undefined]" on the surface and the surface will still fill the size of the modifier, in this case, [100, 100].
In Famous' Render Tree, modifiers modify all the nodes below them. By setting the fa-surface's fa-size to [undefined, undefined], it will inherit from the fa-modifier's fa-size of [100, 100].
Fa-surfaces also cannot have an fa-size/fa-rotate/etc, assigned to a function, as is in the case of modifiers, which can take number/array or a function, and sometimes a transitionable object.
For example, this will not work:
*@example
* ```html
<fa-surface fa-size="sizeForBoxFunction"></fa-surface>
* ```
* ```javascript
* $scope.sizeForBoxFunction = function() {
* return [75, 75];
* }
* ```
To reiterate, the best practice to set any layout/visibilty properties of a surface is to do so on a modifier that affects the surface. Whereas a surface is for containing HTML content, whether rendered from a template, or data-bound with {{}}'s.
*<fa-modifier fa-size="[100, 100]">
* <fa-surface fa-background-color="'red'"></fa-surface>
* </fa-modifier>
*/



angular.module('famous.angular')
.config(['$provide', '$animateProvider', function($provide, $animateProvider) {
// Hook into the animation system to emit ng-class syncers to surfaces
Expand Down
64 changes: 43 additions & 21 deletions docs/unstable/directive/faSurface/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,41 +60,63 @@ ngIncludes or custom (vanilla Angular) directives.



<h2 id="example">Example</h2><pre><code class="lang-html">&lt;fa-modifier fa-size=&quot;[960, undefined]&quot;&gt;
&lt;fa-surface fa-size=&quot;[undefined, undefined]&quot;&gt;
&lt;div ng-include src=&quot; &#39;views/animations.html&#39; &quot;&gt;&lt;/div&gt;
&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>
<p>A simple ng-repeat of surfaces may look like this:</p>
<h2 id="example">Example</h2><p>An <code>fa-surface</code> can use an ng-include to compile an external HTML fragment:</p>
<pre><code class="lang-html">&lt;fa-modifier fa-size=&quot;[960, undefined]&quot;&gt;
&lt;fa-surface fa-size=&quot;[undefined, undefined]&quot;&gt;
&lt;div ng-include src=&quot; &#39;views/animations.html&#39; &quot;&gt;&lt;/div&gt;
&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>
<p>A simple ng-repeat of surfaces can be implemented like this:</p>
<pre><code class="lang-html">&lt;fa-modifier ng-repeat=&quot;item in list&quot; fa-size=&quot;[100, 100]&quot; fa-translate=&quot;[0, $index * 75, 0]&quot;&gt;
&lt;fa-surface fa-size=&quot;[undefined, undefined]&quot;&gt;
{{item.content}}
&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>
&lt;/fa-modifier&gt;</code></pre>
<pre><code class="lang-javascript">$scope.list = [{content: &quot;famous&quot;}, {content: &quot;angular&quot;}, {content: &quot;rocks!&quot;}];</code></pre>
<h2 id="common-problems">Common Problems</h2>
<h2 id="properties-on-surfaces-vs-modifiers">Properties on surfaces vs modifiers</h2>
<p>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.</p>
<p>This is not best practice:</p>
<h2 id="common-confusions">Common Confusions</h2>
<h3 id="properties-on-surfaces-vs-modifiers">Properties on surfaces vs modifiers</h3>
<p>With Famous, properties related to layout and visibility belong on a Modifier. A Surface should be added below a Modifier on the Render Tree, as Modifiers affect everything below them.</p>
<p>You may be tempted to set the <code>fa-origin</code> or another layout property on an fa-surface, and discover that it does not work:</p>
<pre><code class="lang-html">&lt;fa-surface fa-origin=&quot;[.5, 0]&quot;&gt;This will not change the origin.&lt;/fa-surface&gt;</code></pre>
<p>While you can specify <code>fa-size</code> on surfaces themselves, it is not recommended.
This is not best practice:</p>
<pre><code class="lang-html">&lt;fa-surface fa-size=&quot;[100, 100]&quot;&gt;&lt;/fa-surface&gt;</code></pre>
<p>Whereas this is the preferred approach:</p>
<p>Whereas this is the preferred approach: </p>
<pre><code class="lang-html">&lt;fa-modifier fa-size=&quot;[100, 100]&quot;&gt;
&lt;fa-surface fa-size=&quot;[undefined, undefined]&quot;&gt;
&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>
<p>You may also omit fa-size=&quot;[undefined, undefined]&quot; on the surface and the surface will still fill the size of the modifier, in this case, [100, 100].</p>
<p>In Famous&#39; Render Tree, modifiers modify all the nodes below them. By setting the fa-surface&#39;s fa-size to [undefined, undefined], it will inherit from the fa-modifier&#39;s fa-size of [100, 100]. </p>
<p>Fa-surfaces also cannot have an fa-size/fa-rotate/etc, assigned to a function, as is in the case of modifiers, which can take number/array or a function, and sometimes a transitionable object.
<p>You may also omit <code>fa-size=&quot;[undefined, undefined]&quot;</code> on the surface and the surface will fill to the size of the modifier, in this case, <code>[100, 100]</code>.</p>
<p>In Famous&#39; Render Tree, Modifiers modify all the nodes (other Modifiers and Surfaces) below them. By setting the <code>fa-surface</code>&#39;s <code>fa-size</code> to <code>[undefined, undefined]</code>, it will inherit from the <code>fa-modifier</code>&#39;s <code>fa-size</code> of <code>[100, 100]</code>. </p>
<p><code>Fa-surfaces</code> also cannot have an <code>fa-size</code>, assigned to a function, as is in the case of modifiers, which can take number/array or a function.
For example, this will not work:</p>
<pre><code class="lang-html">&lt;fa-surface fa-size=&quot;sizeForBoxFunction&quot;&gt;&lt;/fa-surface&gt;</code></pre>
<pre><code class="lang-javascript">$scope.sizeForBoxFunction = function() {
return [75, 75];
}</code></pre>
<p>To reiterate, the best practice to set any layout/visibilty properties of a surface is to do so on a modifier that affects the surface. Whereas a surface is for containing HTML content, whether rendered from a template, or data-bound with {{}}&#39;s.</p>
return [75, 75];
};</code></pre>
<p>To reiterate, the best practice to animate or set any layout/visibilty properties of a surface is to do so on a modifier that affects the Surface. The purpose of a Surface is to contain HTML content, whether rendered from a template, or data-bound with {{}}&#39;s.</p>
<p><fa-modifier fa-size="[100, 100]">
<fa-surface fa-background-color="'red'"></fa-surface>
</fa-modifier></p>
<fa-surface fa-background-color="'red'"></fa-surface>
</fa-modifier></p>
<h3 id="fa-color-fa-background-color">fa-color &amp; fa-background-color</h3>
<p>The exceptions are <code>fa-color</code> and <code>fa-background-color</code>: these two properties are passed through the <code>.setProperties()</code> method available on Famous Surfaces.
Take note that they accept a string in the html view. If you do not enclose them in quotation marks, Angular will evaluate it as an object on the scope, but surrounding it with quotation marks will specify it as a string expression.</p>
<pre><code class="lang-html">&lt;fa-modifier fa-size=&quot;[200, 50]&quot;&gt;
&lt;fa-surface fa-background-color=&quot;&#39;orange&#39;&quot; fa-color=&quot;&#39;#fff&#39;&quot;&gt;
This text should be white.
&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>
<h3 id="ng-class">ng-class</h3>
<p>Ng-Class works on <code>fa-surface</code>s:</p>
<pre><code class="lang-html">&lt;fa-modifier fa-size=&quot;[150, 50]&quot;&gt;
&lt;fa-surface fa-background-color=&quot;&#39;blue&#39;&quot; ng-class=&quot;{strike: applyStrike}&quot;&gt;
Strikethrough!
&lt;input type=&quot;checkbox&quot; ng-model=&quot;applyStrike&quot;&gt;&lt;/input&gt;
&lt;/fa-surface&gt;
&lt;/fa-modifier&gt;</code></pre>
<pre><code class="lang-css">.strike {
text-decoration: line-through;
}</code></pre>



2 changes: 1 addition & 1 deletion famous-angular-docs
Submodule famous-angular-docs updated from 415b7a to 82ae0a
Loading

0 comments on commit 540b39b

Please sign in to comment.