fa-surface

This directive is used to create general Famo.us surfaces, which are the leaf nodes of the scene graph. The content inside surfaces is what gets rendered to the screen. This is where you can create form elements, attach images, or output raw text content with one-way databinding . You can include entire complex HTML snippets inside a faSurface, including ngIncludes or custom (vanilla Angular) directives.

Usage

<fa-surface>
  Here's some data-bound content myScopeVariable
</fa-surface>

Example

An fa-surface can use an ng-include to compile an external HTML fragment:

<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:

<fa-modifier ng-repeat="item in list" fa-size="[100, 100]" fa-translate="[0, $index * 75, 0]">
    <fa-surface fa-size="[undefined, undefined]">
      
    </fa-surface>
</fa-modifier>
$scope.list = [{content: "famous"}, {content: "angular"}, {content: "rocks!"}];

Common Confusions

A Surface is a leaf node

An fa-surface is a leaf node; this means that there should not be Famous-Angular elements nested within an fa-surface.

This followin will NOT work correctly:

 <fa-surface>
    <!-- the contents of a Surface must be standard HTML, so Famo.us components will not get rendered correctly. -->
    <fa-modifier>
      <fa-surface></fa-surface>
    </fa-modifier>
 </fa-surface>

The purpose of an fa-surface is to contain viewable HTML content:

 <fa-surface>
    <!-- content -->
    <!-- databound content with curly braces -->
    <!-- no other Famous renderable nodes allowed inside a Surface-->
 </fa-surface>

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:

<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:

<fa-surface fa-size="[100, 100]"></fa-surface>

Whereas this is the preferred approach:

<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:

<fa-surface fa-size="sizeForBoxFunction"></fa-surface>
$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.

fa-color & fa-background-color

The exceptions of not setting layout/visibility properties on an fa-surface 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.

<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-surfaces:

<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>
.strike {
  text-decoration: line-through;
}