official/page-params-by-href.groovy

   1 /**
   2  *  Example of passing params via href element to a dynamic page
   3  *
   4  *  Copyright 2015 SmartThings
   5  *
   6  *  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
   7  *  in compliance with the License. You may obtain a copy of the License at:
   8  *
   9  *      http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed
  12  *  on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License
  13  *  for the specific language governing permissions and limitations under the License.
  14  *
  15  */
  16 definition(
  17     name: "href params example",
  18     namespace: "smartthings",
  19     author: "SmartThings",
  20     description: "passing params via href element to a dynamic page",
  21     category: "",
  22     iconUrl: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png",
  23     iconX2Url: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience@2x.png",
  24     iconX3Url: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience@2x.png")
  25
  26
  27 // ========================================================
  28 // PAGES
  29 // ========================================================
  30
  31 preferences {
  32     page(name: "firstPage")
  33     page(name: "secondPage")
  34     page(name: "thirdPage")
  35 }
  36
  37 def firstPage() {
  38
  39     def hrefParams = [
  40         foo: "bar",
  41         thisIs: "totally working",
  42         install: checkSomeCustomLogic(),
  43         nextPage: "thirdPage"
  44     ]
  45
  46     dynamicPage(name: "firstPage", uninstall: true) {
  47         /*
  48         *  The href element accepts a key of `params` and expects a `Map` as the value.
  49         *  Anything passed in `params` will be sent along with the request but will not be persisted in any way.
  50         *  The params will be used going to the next page but will not be available when backing out of that page.
  51         *  This, combined with the fact that pages refresh when navigating back to them, means that your params will not be
  52         *  available if your user hits the back button.
  53         */
  54         section {
  55             href(
  56                 name: "toSecondPage",
  57                 page: "secondPage",
  58                 params: hrefParams,
  59                 description: "includes params: ${hrefParams}",
  60                 state: hrefState()
  61             )
  62         }
  63     }
  64 }
  65
  66 def secondPage(params) {
  67      /*
  68      * firstPage included `params` in the href element that navigated to here.
  69      * You must specify some variable name in the method declaration. (I used 'params' here, but it can be any variable name you want).
  70      * If you do not specify a variable name, there is no way to get the params that you specified in your `href` element.
  71      */
  72
  73     log.debug "params: ${params}"
  74
  75     dynamicPage(name: "secondPage", uninstall: true, install: params?.install) {
  76         if (params.nextPage) {
  77             section {
  78                 href(
  79                     name: "toNextPage",
  80                     page: params.nextPage,
  81                     description: hrefState() ? "You've already been to the third page": "go checkout the third page",
  82                     state: hrefState()
  83                 )
  84             }
  85         } else {
  86             section {
  87                 paragraph "There were no params included when fetching this page."
  88             }
  89         }
  90     }
  91 }
  92
  93 def thirdPage() {
  94
  95     state.reachedThirdPage = true
  96
  97     dynamicPage(name: "thirdPage") {
  98         section {
  99             image "https://placekitten.com/g/600/500"
 100         }
 101     }
 102 }
 103
 104 // ========================================================
 105 // HELPERS
 106 // ========================================================
 107
 108
 109 def checkSomeCustomLogic() {
 110     // ...
 111     false
 112 }
 113
 114 def hrefState() {
 115     /*
 116      * `state: "complete"` makes the right side of the href green.
 117      * It's a great way to show the user that they've already set up some stuff on that page.
 118      * In other words, it's a great way to show state ;)
 119      * If you're using hrefs, it's a good idea to set `state` when appropriate.
 120      */
 121      state.reachedThirdPage ? "complete": ""
 122 }
 123
 124 // ========================================================
 125 // HANDLERS
 126 // ========================================================
 127
 128
 129 def installed() {
 130     log.debug "Installed with settings: ${settings}"
 131     initialize()
 132 }
 133
 134 def updated() {
 135     log.debug "Updated with settings: ${settings}"
 136     unsubscribe()
 137     initialize()
 138 }
 139
 140 def initialize() {
 141     // TODO: subscribe to attributes, devices, locations, etc.
 142 }
 143
 144 // TODO: implement event handlers