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-surface
s:
<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;
}