From c944fe5944da8c8e030bc1cb51c36f5fa7a959cc Mon Sep 17 00:00:00 2001
From: Tim Lancina <tim@drifty.com>
Date: Mon, 12 May 2014 11:25:54 -0500
Subject: [PATCH] add keyboard docs

---
 docs/templates/api_menu_version.template.html |  7 ++++
 js/utils/keyboard.js                          | 39 +++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/docs/templates/api_menu_version.template.html b/docs/templates/api_menu_version.template.html
index 07cc80f047..70bf1fb81f 100644
--- a/docs/templates/api_menu_version.template.html
+++ b/docs/templates/api_menu_version.template.html
@@ -441,3 +441,10 @@
       Tap &amp; Click
     </a>
   </li>
+
+  <!-- Keyboard -->
+  <li class="menu-section">
+    <a href="{{ page.versionHref }}/api/page/keyboard/" class="api-section">
+      Keyboard
+    </a>
+  </li>
diff --git a/js/utils/keyboard.js b/js/utils/keyboard.js
index fac100d30d..8dbb93faa4 100644
--- a/js/utils/keyboard.js
+++ b/js/utils/keyboard.js
@@ -1,3 +1,42 @@
+/**
+ * @ngdoc page
+ * @name keyboard
+ * @module ionic
+ * @description
+ * On both Android and iOS, Ionic will attempt to prevent the keyboard from obscuring inputs and 
+ * focusable elements when it appears by scrolling them into view.  In order for this to work,
+ * any focusable elements must be within a [Scroll View](http://ionicframework.com/docs/api/directive/ionScroll/)
+ * or a directive such as [Content](http://ionicframework.com/docs/api/directive/ionContent/) that has a Scroll View.
+ *
+ * It will also attempt to prevent the native overflow scrolling on focus, which can cause layout issues such as 
+ * pushing headers up and out of view.
+ *
+ * The keyboard fixes work best in conjunction with the [Ionic Keyboard Plugin](https://github.com/driftyco/ionic-plugins-keyboard),
+ * although it will perform reasonably well without.  However, if you are using Cordova there is no reason not to use the plugin.
+ *
+ * ### Hide when keyboard shows
+ * 
+ * To hide an element when the keyboard is open, add the class `hide-on-keyboard-open`.
+ *
+ * ```html
+ * <div class="hide-on-keyboard-open">
+ *   <div id="google-map"></div>
+ * </div>
+ * ```
+ * 
+ *
+ * ### Android Notes
+ * - If your app is running in fullscreen, i.e. you have `<preference name="Fullscreen" value="true" />` in your `config.xml` file
+ * you will need to set `ionic.Platform.isFullScreen = true` manually.
+ *
+ * - If you are not using the keyboard plugin, it may be necessary to set `android:windowSoftInputMode="adjustResize"` to
+ * your activity in `AndroidManifest.xml` to get things working properly.
+ *
+ * ### iOS Notes
+ * - if you are not using the keyboard plugin, switching to inputs below the keyboard using the accessory bar will automatically use the native browser's
+ * overflow scrolling and push headers out of view
+ * 
+ */
 
 /*
 IONIC KEYBOARD