Skip to content

API: JS: Transitions

nateemerson edited this page May 21, 2011 · 3 revisions
Clone this wiki locally

WARNING: OVERHAUL

This library is currently slated to be overhauled due to the fact that it relies on the deprecated Webkit functionality. A new version of the library is planned that runs on all full devices.

Description

Leveraging the Webkit browser engine and HTML 5 technologies, the framework provides an implementation of CSS 3 transitions between content elements on a page. These effects are provided, most basically, by a set of stylesheet definitions available on Webkit-classified devices. In addition, the functions in the transitions Javascript library can further simplify this.

Implementation

Transition Styles

A transition style can be defined upon a set of entities by defining one of the Webkit transition styles as a class of a parent of the entity set in the DOM tree.

The following transition styles are available:

  • webkit-transition-fade
  • webkit-transition-flipY
  • webkit-transition-slideX
  • webkit-transition-slideY
  • webkit-transition-slideXZ

Javascript Warning

Please note that at this time only the CSS entities employed by the transitions library are considered backwards compatible. Attempting to use Javascript functions explicitly from the library is not recommended or supported and doing so may cause modules to break with future updates. Instead, please load the library and use the CSS entities defined, not the Javascript functions, as the CSS entities are ensured to remain compatible with future updates as the Javascript changes and evolves.

Example Code: Implementing the Transitions Library

To employ the framework's Javascript-driven transition library, the transitions library must be specified as a parameter in the script tag that includes js.php:

<script type="text/javascript" src="../assets/js.php?webkit_libs=transitions"></script>

If more than one Webkit library is to be included, they can be concatenated in the webkit_libs attribute with a plus sign (+):

<script type="text/javascript" src="../assets/js.php?webkit_libs=somelib+transitions"></script>

A simple prototype of elements driven by the transitions library:

<div class="content-elements webkit-transition-slideX">
    <div class="webkit-transition-element">
        <p>{TRANSITION_CONTENT_1}</p>
        <div class="webkit-transition-trigger-next only-webkit">
            <a href="#">Next</a></div>
    </div>
    <div class="webkit-transition-element">
        <p>{TRANSITION_CONTENT_2}</p>
        <div class="webkit-transition-trigger-prev only-webkit">
            <a href="#">Previous</a></div>
        <div class="webkit-transition-trigger-next only-webkit">
            <a href="#">Next</a></div>
    </div>
    <div class="webkit-transition-element">
        <p>{TRANSITION_CONTENT_3}</p>
        <div class="webkit-transition-trigger-prev only-webkit">
        <a href="#">Previous</a></div>
    </div>
</div>

In this example, the transitions library will automatically set the entity containing {TRANSITION_CONTENT_1} as active and hide the others until the Next entity is clicked. At that point, the {TRANSITION_CONTENT_1} container will slide left and vanish and the {TRANSITION_CONTENT_2} container, along with its transition buttons, will slide from the right into the body.

It is also possible to set an entity besides the first entity as the active entity on page load.

<div class="content-elements webkit-transition-slideX">
    <div class="webkit-transition-element">
        <p>{TRANSITION_CONTENT_1}</p>
        <div class="webkit-transition-trigger-next only-webkit">
            <a href="#">Next</a></div>
    </div>
    <div class="webkit-transition-element active">
        <p>{TRANSITION_CONTENT_2}</p>
        <div class="webkit-transition-trigger-prev only-webkit">
            <a href="#">Previous</a></div>
        <div class="webkit-transition-trigger-next only-webkit">
            <a href="#">Next</a></div>
    </div>
    <div class="webkit-transition-element">
        <p>{TRANSITION_CONTENT_3}</p>
        <div class="webkit-transition-trigger-prev only-webkit">
        <a href="#">Previous</a></div>
    </div>
</div>

When working with transitions, keep in mind that, in a non-Webkit browser, all elements will be visible on the page. In the above examples, therefore, it should be noted that the only-webkit class is employed on the Next and Previous buttons, as they should not appear when transitions are not available. Therefore, when designing pages with transitions, it is worth keeping in mind how navigation elements will look on a page that does not include transitions but instead shows the elements in order.

Example Code: The DOM Tree In-Depth

State changes in DOM entities (HTML elements) drive transitions. Even without leveraging js.php, the framework defines several styles to simplify the use of transitions. To trigger these transitions with Javascript, a basic understanding of the DOM elements that guide the transitions is necessary.

At the markup level (what is applied in the HTML document) follows this pattern:

<div class="webkit-transition-fade">
    <div class="webkit-transition-element">...</div>
    <div class="webkit-transition-element">...</div>
    <div class="webkit-transition-element">...</div>
    <div class="webkit-transition-element">...</div>
</div>

The framework then provides several classes to govern state:

  • active displays an element that, on transition to another state, will go invisible in some direction.
  • inactive-prev hides an element that, on transition to active, will come from the top or left depending on the parent transition definition.
  • inactive-next hides an element that, on transition to active, will come from the bottom or right depending on the parent transition definition.

An example of one such DOM tree:

<div class="webkit-transition-fade">
    <div class="webkit-transition-element inactive-prev">...</div>
    <div class="webkit-transition-element active">...</div>
    <div class="webkit-transition-element inactive-next">...</div>
    <div class="webkit-transition-element inactive-next">...</div>
</div>

Such a tree can be constructed manually or through Javascript, and then the manipulation of this tree must occur through Javascript to trigger transitions. For example, if a child element of the active element fires the webkit_transition_swap_prev(this) function, the DOM tree might then look like this:

<div class="webkit-transition-fade">
    <div class="webkit-transition-element inactive-prev">...</div>
    <div class="webkit-transition-element inactive-prev">...</div>
    <div class="webkit-transition-element active">...</div>
    <div class="webkit-transition-element inactive-next">...</div>
</div>

Custom libraries can be written to effect the same sorts of state changes.

Something went wrong with that request. Please try again.