Skip to content

Getting started

Jump to bottom Edit New page
Ran Ben Aharon edited this page Sep 15, 2011 · 27 revisions

Basic setup:

  1. Download the project files: zip, tar or fork it.
  2. Browse to index.html from your desktop and mobile.
  3. Edit the file to your liking and make it your own.

If you have a server that runs php, start with index.php so you could enjoy TouchyPHP which enables embedding assets into the page (potentially speeding up load time).

In the future we may add support for some other server side languages.

Dig in to the features

There's a whole lot you can do with the Touchy projects. Full documentation can be found in TouchyJS and TouchyPHP.

Before starting, make sure touchy.js is loaded into the page after jQuery or Zepto. The minified versions are easier on the network.

<script src="js/libs/zepto.min.js"></script>
<script src="js/libs/touchy.min.js"></script>

Here's a few quick ones:

Fixed header

Your HTML structure should look like this:

<html>
  <head>
    <style>
      .touchy-js{display: none}; /* To avoid a flash of content */
    </style>
  </head>
  <body>
    <!-- header -->
    <div class="touchyjs-header">
      ...
    </div>

    <!-- content page #1 -->
    <div class="touchyjs-content" id="page1">
      ...
    </div>

    <!-- content page #2 -->
    <div class="touchyjs-content" id="page2">
      ...
    </div>
  </body>
</html>

Reload the page. Now, only the first "page" is displayed. Insert some content into it, refresh the page and drag the content up and down. The header part stays while the content scrolls. Neat.

Page navigation

You can use TouchyJS.Nav to control navigation and handle url changes. Make sure you provide id attributes to the .touchyjs-content elements.

Insert a link in the first page, that executes TouchyJS.Nav.goTo("page id"). Like so:

<!-- content page #1 -->
<div class="touchyjs-content" id="page1">
  <a href="" onclick="TouchyJS.Nav.goTo('page2'); return false;">Go to next page</a>
  ...
</div>

Don't forget to add return false to avoid page redirection.

Side note: of course, you should put the event handlers in an unobtrusive script, not inline, but for the sake of example..

Let's put a back button in the header:

<!-- header -->
<div class="touchyjs-header">
  <a href="" onclick="TouchyJS.Nav.back(); return false;" class="btn-back">Back</a>
</div>

Click it, and the first page comes into view.

Of course, TouchyJS.Nav.goTo('page1') would have worked just as well, but "back/forward" browser button functionality would have been lost.

The only problem now is that the back button is visible even in the first page. No good. We want it to appear upon navigation and disappear when returning. TouchyJS.Nav can handle that with it's attachCallback method. Quick code:

<script>
  var button = $("btn-back");
  
  // Show button when navigating out of the first page
  TouchyJS.Nav.attachCallback("page1", "out", function(){
    button.show();
  });
  
  // Hide it when returning
  TouchyJS.Nav.attachCallback("page1", "in", function(){
    button.hide();
  });
</script>

TouchyJS.Nav is even smarter than that, letting you attach functions to url address change events. More on that in the full documentation.

Environment info

Getting device info is valuable for cross-platform cross-browser web-apps. TouchyJS.Env lets you tap in to environment info by CSS hooks as well as by javascript API.

CSS hooks will look like this:

<html class="iphone webkit touch mobile orientation-portrait ">
  <head>...</head>
  <body>...</body>
</html>

And you can use javascript as well like this:

<script>
  var info = TouchyJS.Env.getInfo();
  var platform = info.platform.name;
  var browser = info.browser.name;
  var isTouch = TouchyJS.Env.isTouch();    
  var isMobile = TouchyJS.Env.isMobile();  
</script>

Get geocoded location

(This feature is not activated just yet and will be soon)

Another exciting feature of TouchyJS.Env is getLocation.

Let's say you have a location aware web-app that uses the browser's navigator.geolocation. Maybe you'd like to notify the user of the location you detected. But position coordinates aren't really user friendly, right?

Try this instead:

<script>
  TouchyJS.Env.getLocation(function(data){
    alert("You're in "+data.city+", "+data.country);
  });
</script>

Again, the alert is for the example only. Don't use alerts - it's gross.

The callback will return the argument data containing the following:

  • city
  • country
  • state
  • zip
  • position

Be aware that not all data parameters may be present. For instance, Kabul in Afghanistan returns no zipcode and any point in Antarctica returns nothing but position coordinates.

If the device running your app doesn't have GPS capability - no worries, it'll fallback to retrieving the data by the devices IP address.

More on that in the full documentation.

TouchyJs events

Right now, there's one relevant function to the TouchyJS.Events object - attaching a callback to TouchyJS.Events.ready. Then, TouchyJS and all of its objects and methods are ready for use.

TouchyJS.Events.ready(func);

Example use:

TouchyJS.Events.ready(function(){
    // Get searchbar value
    TouchyJs.Searchbar.getValue();
});

<tml:searchbar>

Almost every web-app utilizes a searchbar. <tml:searchbar> provides the following functionality without the hassle:

  • Placeholder text
  • Keyboard integration - "Search" key label and submit on press
  • Clear button (coming soon)

Here's how to use it:

<tml:searchbar onsubmit="searchFunc"></tml:searchbar>

More on <tml:searchbar> in the full documentation.

<tml:image>

Need to resize your images on the fly? <tml:image> serves your image in any dimensions you specify.

Here's how to use it:

<tml:image src="image.png" width="100" height="50"></tml:image>

More on <tml:image> in the full documentation.

Stand by for more <tml> tags coming very soon.

Add a custom footer
Add a custom sidebar
Clone this wiki locally