ionic-settings
2 |
3 | * [Introduction](#1-introduction)
4 | * [Usage](#2-usage)
5 | * [Configuration provider](#3-configuration-provider)
6 | * [Services](#4-services)
7 | * [Directives](#5-directives)
8 |
9 | ##1. Introduction
10 | This plugin provides settings and lock screen for your ionic app. The keys and values are stored as app preferences on condition that you have installed
11 | [the app preferences plugin](https://github.com/apla/me.apla.cordova.app-preferences), otherwise they are stored in `localStorage`.
12 | You can test the plugin via the [ionic view app](http://view.ionic.io/) with the ID **141b234c**.
13 |
14 | ##1.1 Features
15 | * 5 setting types: `selection`, `toggle`, `input`, `range` and `pin`
16 | * 2 read-only types: `button` and `text`
17 | * grouping of settings
18 | * including settings into a view or modal view
19 | * customizing of settings appearance (color, icons and button positions)
20 | * storage as app preferences using the above mentioned plugin, otherwise in `localStorage`
21 | * touch id support if the [touch id plugin](https://github.com/leecrossley/cordova-plugin-touchid) is installed
22 |
23 | ##1.2 Screenshots
24 | 
25 |
26 | ##1.3 Demo
27 | ##### Note: To test the lock screen feature respectively settings persistence please reload the demo after value changing.
28 | #### [Ionic Playground](http://play.ionic.io/app/28ea71301b60)
29 | #### 
30 |
31 | ##1.4 License
32 |
33 | [MIT](https://github.com/ivandroid/ionic-settings/blob/master/LICENSE)
34 |
35 | ##1.5 Versions
36 |
37 | [CHANGELOG](https://github.com/ivandroid/ionic-settings/blob/master/CHANGELOG.md)
38 |
39 | ###1.6 Author
40 | * E-Mail: ivan.weber@gmx.de
41 | * Twitter: https://twitter.com/hybrid_app
42 | * Github: https://github.com/ivandroid
43 | * Ionic Market: https://market.ionic.io/user/6540
44 | * Your support: If you find this project useful and want support its development you can press the button below or star the project. Thanks in advance!
45 |
46 | [](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=ivan%2eweber%40gmx%2ede&lc=DE&item_name=GithubRepositories&no_note=0¤cy_code=EUR&bn=PP%2dDonationsBF%3abtn_donate_LG%2egif%3aNonHostedGuest)
47 |
48 | ##2. Usage
49 | 1. Get the files from here or install from bower:
50 |
51 | ```
52 | bower install ionic-settings
53 | ```
54 |
55 | 2. Include the javascript and css files or the minified versions into your `index.html` file.
56 |
57 | ```html
58 |
59 |
60 | ```
61 |
62 | 3. Add the module `ionicSettings` to your application dependencies:
63 |
64 | ```javascript
65 | angular.module('starter', ['ionic', 'ionicSettings'])
66 | ```
67 |
68 | 4. Settings are defined according to the following pattern:
69 |
70 | ```javascript
71 | var settings = {
72 | label1: 'Group 1', // OPTIONAL GROUP LABEL
73 | mySelection: { // KEY
74 | type: 'selection', // TYPE
75 | values: ['value 1', 'value 2', 'value 3', 'value 4', 'value 5'], // IN THIS CASE: SELECTION ARRAY
76 | label: 'Selection', // LABEL
77 | value: 'value 1', // VALUE
78 | icon: 'ion-checkmark-round' // OPTIONAL ICON
79 | },
80 | myToggle: {
81 | type: 'toggle',
82 | label: 'Toggle',
83 | value: true,
84 | icon: 'ion-toggle'
85 | },
86 | myInput: {
87 | type: 'input',
88 | label: 'Input',
89 | inputType: 'text',
90 | value: 'Hello World!',
91 | icon: 'ion-edit'
92 | },
93 | myRange: {
94 | type: 'range',
95 | label: 'Range',
96 | iconLeft: 'ion-minus-circled',
97 | iconRight: 'ion-plus-circled',
98 | min: 0,
99 | max: 100,
100 | value: 50
101 | },
102 | label2: 'Group 2',
103 | myButton: {
104 | type: 'button',
105 | label: 'Button',
106 | icon: 'ion-disc',
107 | onClick: function() {
108 | alert('Hello world!');
109 | }
110 | },
111 | myText: {
112 | type: 'text',
113 | label: 'Text',
114 | icon: 'ion-document-text',
115 | value: 'Hello World!
' 116 | }, 117 | myPin: { 118 | type: 'pin', 119 | label: 'PIN & Touch ID', 120 | value: '', 121 | icon: 'ion-locked', 122 | onValid: function() { // OPTIONAL ACTION ON VALID PIN 123 | alert('Success!'); 124 | }, 125 | onInvalid: function() { // OPTIONAL ACTION ON INVALID PIN 126 | alert('Fail!'); 127 | } 128 | } 129 | }; 130 | ``` 131 | 132 | 5. To initialize the settings invoke the `init()` method of the `$ionicSettings` service (returns promise) passing your settings model object. If you'd like to protect your app with a pin / touch id, make sure to initialize your settings before the main state of your app is loaded like shown below. 133 | 134 | ```javascript 135 | // INITIALIZATION IN CONFIG PHASE (USING PIN) 136 | angular.module('starter', ['ionic', 'ionicSettings']) 137 | .config(function($stateProvider, $urlRouterProvider) { 138 | $stateProvider 139 | .state('main', { 140 | url: '/main', 141 | abstract: true, 142 | templateUrl: 'templates/main.html', 143 | resolve: { 144 | settings: function($ionicSettings, $ionicPopup) { 145 | var settings = { 146 | toggle1: { 147 | type: 'toggle', 148 | label: 'Toggle 1', 149 | value: true 150 | }, 151 | toggle2: { 152 | type: 'toggle', 153 | label: 'Toggle 2', 154 | value: false 155 | }, 156 | pin: { 157 | type: 'pin', 158 | label: 'PIN', 159 | value: '', 160 | onValid: function() { 161 | $ionicPopup.alert({ 162 | title: 'Success', 163 | template: 'Welcome!' 164 | }); 165 | }, 166 | onInvalid: function($event, wrongPinValue) { 167 | $ionicPopup.alert({ 168 | title: 'Fail', 169 | template: 'Wrong pin: ' + wrongPinValue + '! Try again.' 170 | }); 171 | } 172 | } 173 | }; 174 | return $ionicSettings.init(settings); 175 | } 176 | } 177 | }) 178 | }); 179 | // INITIALIZATION IN CONTROLLER (WITHOUT PIN) 180 | angular.module('starter.controllers', []) 181 | .controller('YourCtrl', function($scope, $ionicSettings) { 182 | $ionicSettings.init({ 183 | awesomeSelection: { 184 | type: 'selection', 185 | values: ['one', 'two', 'three'], 186 | label: 'Awesome Selection', 187 | value: 'two' 188 | }, 189 | coolToggle: { 190 | type: 'toggle', 191 | label: 'Cool toggle', 192 | value: true 193 | } 194 | }); 195 | }); 196 | ``` 197 | 198 | 6. To include your settings into a view simply use the `ion-settings` directive within the `ion-content` element. To show the settings as modal add the directive `ion-settings-button` to the navigation bar. Pressing this button opens the modal. 199 | 200 | ```html 201 |
247 |
248 | ##4. Services
249 | ### Service `$ionicSettings`
250 |
251 | Using this service you have access to the following events and methods:
252 |
253 | event|description|return-value
254 | ---|---|---
255 | `changed`|Setting changed event|object containing key and value of a changed setting
256 |
257 | method|description|return-value
258 | ---|---|---
259 | `get(key)`|Getting a value by key|value of a given key
260 | `getData()`|Getting all settings keys and values|object containing all key value pairs
261 | `init(modelObject)`|Initializing of settings passing your settings model object|initialized settings model object as promise
262 | `set(key, value)`|Setting a value by key|none
263 |
264 | #### Example
265 |
266 | ```javascript
267 | angular.module('starter.controllers', [])
268 | .controller('YourCtrl', function($rootScope, $ionicSettings) {
269 | $rootScope.$on($ionicSettings.changed, function($event, changedSetting) {
270 | alert(changedSetting.key + ' -> ' + changedSetting.value);
271 | });
272 | });
273 | ```
274 |
275 | ```javascript
276 | angular.module('starter.controllers', [])
277 | .controller('YourCtrl', function($scope, $ionicSettings) {
278 | $scope.set = function(key, value) {
279 | $ionicSettings.set(key, value);
280 | };
281 | $scope.get = function(key) {
282 | alert($ionicSettings.get(key));
283 | };
284 | });
285 | ```
286 |
287 | ##5. Directives
288 |
289 | ### Directive `ion-settings`
290 |
291 | Use this directive to include your settings into a view.
292 |
293 | #### Example
294 |
295 | ```html
296 |