{"_id":"@litexa/apl","_rev":"69-050c6565c60fff288f2e5ce4a554717d","name":"@litexa/apl","dist-tags":{"latest":"0.9.0","nightly":"0.4.2-nightly.157326457.1"},"versions":{"0.0.2":{"name":"@litexa/apl","version":"0.0.2","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-labs/litexa.git"},"bugs":{"url":"https://github.com/alexa-labs/litexa/issues"},"homepage":"https://litexa.github.io","gitHead":"795625ee8ecd349565f081808eca48cd9976d9ff","_id":"@litexa/apl@0.0.2","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-fa88Aj6WLtneEKSrotMc0Kc6irBEZ+oOiiN892aCbrFn5a4V7h3WZzXkSHbTzohQDTIYazIi5cxk4tcsPtKCMg==","shasum":"c8acaae67ad6c8bc3f2ded551ebc522c7085b918","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.0.2.tgz","fileCount":29,"unpackedSize":98054,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJczJZoCRA9TVsSAnZWagAAegwP/2h+u7kdasR3BwyjewWf\n9X1Ha2lOIYsvKfKfRsI7DTpD+NsAFjsLPXmCjejaWSgqQOQCSo09DCjEDOpD\nWubbnmskTfSHXW77OZ0Kz0cwLeZQSFAcR50icIsOQhMmgMUDN2o0eYjnWSPJ\njt850ww2EFEto2+2u3B6sR/erljxPEc3yYZm3uuphRQe1gk0TqsPxHqDVnNT\nFe+uSdi2TXEOi6QVx63lIdZ7HnACYBZso7TlnjHFZUNkmhqq1qOzVRqBTvRl\n3xSkL8uY1+YZkicmaQLWEkv+Oa0dN7df+avQCNFTqF1rYQt0Tsaf73xLVIhM\nMai73zGgBBiOG/S/ttN7vY5ZfAhW7nrp+l6YYiZZ2qbBqPDvzIIslPxRQBgj\nhgroucdy27KrWirlyJEtd/WVqk31z2FBNNgr5A0jR/RRGuLzWoOZ4FKDqAiU\nlZBVWsiz1758jHDVQDNCWpcptlPN4FsajN6V/pXTzLouyB3PBxFxvQoPd28a\nldYLnkB6FHZRro6oVgnFWfZ+JLPiqfPt6nLjtpOrHd0QGADXL1yFkMx75YM4\nQmKYYPbJ85kTdxt7gKEwKP7cHPOfRnP3ZtiCI+52jRXM0WsB79fp4K9CPZAs\nSfd3CRq66W43YjZ2s2mGSZQcBpg9WRI1JXCpF6VA3Vwqi3Rl2auscTOsEdzZ\nYsjq\r\n=/JJX\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIADyucqW94IbaSYLltfPx2f64ClhYL8n/el0RPyHTWD0AiEAmk1PsugTVXnJ6JfNEZCMtnSAkY73rVkcl412hE7HMrE="}]},"maintainers":[{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.0.2_1556911719574_0.0027733397122948755"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.0.3":{"name":"@litexa/apl","version":"0.0.3","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-labs/litexa.git"},"bugs":{"url":"https://github.com/alexa-labs/litexa/issues"},"homepage":"https://litexa.github.io","gitHead":"f9d79982170f28b81e4037f52e3df6ea1f72abf7","_id":"@litexa/apl@0.0.3","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-y/nrQP7ZeTrdaP56a01rVknpfZZeyG6yPzJ3Zb1DwKWj08czylmUpDRPDEgUEGDkdB1h7ITXJMei63jrCwTJ+Q==","shasum":"a01d9598b605f377343aa1fdde43268636887d99","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.0.3.tgz","fileCount":29,"unpackedSize":98134,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJczLvkCRA9TVsSAnZWagAAfmUQAJ/Dtk2I7TgaHAt/RiF7\nt0zKfFmj6g5Zm7h4MSBYVu6CvguznMeHuU9p0ExmtirrF8IKD+M8qCJCirrb\n57iPE/zBOrnFN2R0E5U77NBPz6pPS5iW0AQQFJtDhC5bX3vc2DO/OLfIMz3r\na1Bqdof1D4ukm+Pusl1S0nHKhAEscA/CPL/VdGaO71PZQxhn4alw4uQ0Rg15\nEEVzdMy9X8Lw631XThmiQfF7UcJwKVpOVGHSl8Z4fU+8HO//7xMmFgkFL5HP\nqGYF5VxVApm0OKjxCtIouD24eEHkvRnh8O2JWBF0uBcBwhkx5TKGBFUfoA8X\njG2R40rGUvoLZ5QraCNlff2lGzZIueovMW3MSSipRZXUzL2kfKD+3DH4mdU3\nC1fW85YJNwXNjcPPIhtITaQjsj9rj4+yF23ipClz3krL6JPfArTcOu+U5Lha\n7Q8689+NGaOP5UZZsizmbqvqBO9Nh8Gbui1iHcFGhCz+fGtMrReXX9DeUrlH\nKlLnypZCNHMfc2TUHMIsj5/K5qxqMlw3+w+kSb4cm6C59yeaY/8T7QM6dfKK\nmaOaCi/smQvxHiSRavTdVz+/vOuqc4qf4UyuV3ZomoIP3jRUQOIjM/8EfAJd\nGQzUjQ2N3M0UcjiFmIJppC/u6D2m16uTIFfWZTwob/Y4JuAJRjMyyUDLBzQu\nQhCI\r\n=JUCI\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIHKSa6fXLRkVKgxSqOVCBhFN04XEhtJ++iFStebN/gY5AiA1kqbTa8JQZvra7A9auzwSA5/MpcUqEHmb6vnQCCJFLw=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.0.3_1556921316002_0.4144314006173775"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.1":{"name":"@litexa/apl","version":"0.1.1","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-labs/litexa.git"},"bugs":{"url":"https://github.com/alexa-labs/litexa/issues"},"homepage":"https://litexa.github.io","gitHead":"56523ebcc830e555c1e2b43f0027a03d1eefca1d","_id":"@litexa/apl@0.1.1","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-p75dXUA3kp2LfRTJ65E6pHCKkeXe2r4XG/AGvc/Zi2QZhfbXqcFL7LfsIdrm5UjQ02UxFbVgJv96Vn806MDOpw==","shasum":"b1d05b6e71f95338796b44c012d187c37e32df9f","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.1.tgz","fileCount":29,"unpackedSize":114431,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc0IYqCRA9TVsSAnZWagAADLIP/AwVsa6LYY42Dw6GHT7y\nNXgBgP6Jo9f0X5vH6bl9QOhiN4RotNleMWCwlmlqe6GHUtrPOzJtRJpV4qcB\nmC8ijfx0NOjl22HZLZSegiBRriPBvtLRsXh0RXGuShShJCShByI0+oh5hZ9y\n7nUdebl8g2EVFVCfrGqYfnnBb54RllYraEY6lX/qf7QqhkYgjcdCf/UELla7\nhHv/cgsF+WbX/cJaK1pnAHtLiGTgo0ZfLebqsmP1MMh8l6W2oqf+2lsO6F7z\ncp1AgA37ZpPR7C/BQ9sDv+C4KerY9wnZfRBfSgqiSI2EFQL7kSRjgTxhwClS\n8nBP1fI17gLBGQpkRWf1DPjlrMJ6bvkerHt0rYRolp7h2kfO/XzlGvSwcjtr\np29cafNdSbgfyYy1go5gbW5RPewt1KGjQPnGqSlqIJFXcazizGUNo36x7WW/\n3oR1tOd3+1tjSFDzGlOJ7vBAVR4bb4EldKArLuzVHzXj7qIjCIjjdPZB02NU\nYEbskN+uIzX8Y/UfMNzHSzwTNtRrR2wq0+0n+lSBc0p8awzZlUDVJVHTolLC\nQl5QEpGGPcqzx18/NY+kXnt1WH066/RAZz40UzAkaKynhHjzfoL9f1JAA0tu\nww3KAjnYkiJ9bMuUL8TXPGkwd8s70Vd9kCNWZxiCM3loAvoe3iKmChZuV0tz\ntrjN\r\n=tXr2\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDByYGpQ469+bC6ODhlxf/WUj/4khJEQPhiSy//bKh8mgIhAMKpOYEhoevsZboTC9iRl+nzcxcBS6cbeWzbeyXHvMDP"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.1_1557169705861_0.9848611592458314"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.4-nightly.110967595.1":{"name":"@litexa/apl","version":"0.1.4-nightly.110967595.1","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"http://litexa.games.alexa.a2z.com","gitHead":"495fc60175e42f13ec3103bd81f8d2a1bcb9126c","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.4-nightly.110967595.1","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-N07Wl3qvfq7B2ddq+ZlpJOXUKs+KSrEcTpyRSf4AiAEuwNQT3XFMA8923P7xpAVkJocjNGp7p7hEZ5ubl5C4ig==","shasum":"47c02119cd70d621553b2cdf363ffa6d8cb7fef0","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.4-nightly.110967595.1.tgz","fileCount":29,"unpackedSize":114470,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc0gfNCRA9TVsSAnZWagAA4lsP/0JTBMknNBrrp3WlKddn\nVR9jF5xeLdAz9gPI010YlvZ4For/Pava6mtjP/WITLhZ0Wa7HrZDn6JDR2zZ\nTqBE5zZjZ55HE6Gf4IJpsDYi2wPihueKUDiXup/p5a3TFi+F0FfZa5xouXHd\nQf9w5ik0DHqWE/434rSAFxZCJbDb89Wg9H2TmWWOIC5Q0807ngpnX67RWGXM\nCixjymJBvh4RCIg5bEG01BBO7HN62i8x5OZx21rR3JAzy0+s4klMkboPjX0m\nEMhztMx2Cn832XlN2ehVBXnrYZD5yTvMbC9xdbHsqWjWKUuae6z+PTtBFNAs\nkbmP0cqsrCKGLFsiJpPJ0MWlJs5xuPt2i4geob3Vu8VP2keqYVgx2jIc6yap\nZMV1s3IIEWxjxaLPEcDjFuwRTG0JNu5f/LR43os0vNtB5TWA6Cc6x//+VuQH\nc4yLfrYnHFu/hJTKykeKWNS2Y0bFTLu/irORTqOabzu5LXLuVCSe2nRF1whS\n2hCMNbMx9k34mhQaLvQArUnjmKPZx4zBOu1TlVJoqXGxMDJlRobZIt9V1PgL\nG6YFTKNwmOsb4ILP6zCQHSJoN2i7AvpjBaQTDGv8944gx9NKb2IAOudTW8l6\nNiJ5X/xJjwYQS1RPZpo08QIoHL+7LAvDV/yptgSGSMxWA5MdIMLkcY3gOd0g\nfPqn\r\n=sBr7\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIANJxalVg2IIxKUCPx9o6c3Uo0I6VCVam+dfdv6i94I6AiEA+0e7PuWySnUpSAyQnyQUpbroCSqdOdl7QfNyzRpV+G8="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.4-nightly.110967595.1_1557268428756_0.6932922375502484"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.4-nightly.111120854.1":{"name":"@litexa/apl","version":"0.1.4-nightly.111120854.1","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"http://litexa.games.alexa.a2z.com","gitHead":"495fc60175e42f13ec3103bd81f8d2a1bcb9126c","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.4-nightly.111120854.1","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-q42pYFjs0gr1YR4X2an7bLWx+PsX72I3zlvGsB6gW4jFjRO+j+PGeivtqruRSwH3moXEvanVZNXHg/vExyU0Rg==","shasum":"663648321c843d9939ebcb821156fba106f7049a","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.4-nightly.111120854.1.tgz","fileCount":29,"unpackedSize":114470,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc01nGCRA9TVsSAnZWagAAkYIP/RyXWmiQUmFG62RAUUCp\n5/+zl9yr/GEmTh+UZP8S6S9KKZdtEnydGGkeMAOKqvW7d0nKUGVte79kxaeE\nfytungjKGbrl6d5R1woSXd9gtSkU8iCB3Odu6qBx+hSDhylN8w51Q8hRLGYT\nW+pyyg3UjgjMnwIojX3nQcoyTTIYp360SQWCgKd2qaq1JWiUZHIM9x+9JYBn\nW4/KS/g6aLASLKC643pXjhi6MWcD64+PtpwIrE8IEshR08QBPjlz91UzqpB5\n7c5oK5umJqPQrr2iTIjylWsuYade73th+Y21xHKKWTz7bzRGD4fVDjdzWnHp\nBxXlNkAH5XIddO6hFG0NLyvAGTinso5w396wmHK4TWpp2g3biSRgyTcbR4Xl\nvWYxSgwmsXkzfVtKrdpNZD5e/0zTr5zxvGecTPSI0eELxormP0EDk0wdwGUq\nE78+Lo4w0v7uiCyXnggzVjWMZc7Cjy17tUtTUgQ5xOz7vP8+eAVIANz0fc+p\nbsARylHcOMyRN1/bjzYM8c16s0BQMkW1HbkI/tOEFup3BJsjOA48+w7JWMwh\ns54DItQ3030L8so4eQZXpTW0pqcle4Z/VmdVa2myflq1Gs8nOA3QUvC9xwev\nrno7W6YLPDqwI7tOV6g4npg4vFNqK1yh9SRyrA64sXvT2YvUmrRmO5tkkRej\nxYpM\r\n=YXgC\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDz3NncJgMtNn7vdhbZ/N1Fsj6cQdFnCC5v1yWNbMQeWQIhAM5xRKfc0u7Ks6gUIMWdoiHHXpmCMp3DWyxl8Vxtz9oq"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.4-nightly.111120854.1_1557354950353_0.7002251049690553"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.4-nightly.111132236.2":{"name":"@litexa/apl","version":"0.1.4-nightly.111132236.2","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"http://litexa.games.alexa.a2z.com","gitHead":"1c576668dd36dc3e2675332bf3a062056c83e02b","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.4-nightly.111132236.2","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-DDnMo7bhnYWSNSPAJ2QyZa0gEGVUQyLIkNy/pLGofywv+KiWIYz76Zd5ZPtoGB2xdYaTGv8BnBrtshHlufK42g==","shasum":"1d7fef7f5c8a16ead9ea9f04d9fb4fc68c8d5546","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.4-nightly.111132236.2.tgz","fileCount":29,"unpackedSize":114470,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc04GgCRA9TVsSAnZWagAA9tAP/i1Uvruye/ZbBn2O1EEn\nLd0jfEcEhYNbqAd8XWC856c1mIevckHc699LtN4m8NiUcYcE6uuMX1292mw9\nQPpaFKF26lYrYm83lzsoTHCp5hqY39fXfDKZn7mDtZH6HjBaDuHfdZ0js8sQ\nPPZ8M+WNCLF4ZyIgM4YLg7XEWqET7kTCz5bqqdosAVJT9+T6DuWncJY263vB\nPqgF27MyB0ieR1PFeo8/qwztl5fp7QYpVyUW8KXrQ/Qatdby6Bm+WnEL+5Ql\nIz4asKdu00p7zMTsaCcEtUTsvFvTLhgK8Fo/7ZUI024Spa7WDbXOCuhlaTK2\nWFa77UeBoI1Icl+5GVPoHwFULYLz4OOkBn1FFVXre8PBDGM5tomxiNY2DNe4\n/JXe18G6Ns4AR8sCz3gKdSFlvldhBFYbeqfg6aArN/E2AsRExtDoaTW4XbE+\nZbwuqht2c+szgqu8auBzWclfQAjtJdJCBeTj/RfWfWKU/waSE5Yegc8Yc0RX\ny1Q1Kv7+cshuqU6KJF7VzraZ9YZbVGZX5a3+9lPw1hXMaBWweAdPi/yO+bkt\nZiBShqIuNYJrr6t8lTfG0XQcypbdTFzWCoT256OerkDoRJDIX8dN6gG3gNT9\nza9tbPPROWoyw+dyQ7JRW4PLf998VF1rMPPFGIp4sS6+Q9d2aA4dp5Ft1toj\neHOb\r\n=pTX3\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIB8wEXBrP3EEle1LNv8S2EiqLOoSeJkY8FTKfxT0gbMTAiEAouaOGtAlbu4WmMLRgff3E8CpyntugevHp8vLS5SQ3BI="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.4-nightly.111132236.2_1557365151681_0.7287563753665016"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.4":{"name":"@litexa/apl","version":"0.1.4","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"http://litexa.games.alexa.a2z.com","gitHead":"d89330a299df060bcd10e05f17b8dc50d28cade2","_id":"@litexa/apl@0.1.4","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-64PpDLjac+dXEqm+XDyLvAlVDDVJE2/WF786fzfs6TCJ5qOKjMZmEH26pnma0w0pINkN/UBsYANT5E6wa7PuwQ==","shasum":"6abfefb2a3e96d8b051f2df53f7b947ca023b1ad","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.4.tgz","fileCount":29,"unpackedSize":114862,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc1KBZCRA9TVsSAnZWagAA2WEP/3e5IpodfB0dbHmGR+9o\n6ubD1P+iEpZmISlXj/MBBuUSLydqHSTWwDxJV5mL/TI8U3RkrdcN30SaJn3D\nC5g/9SvbPTTXsj2l4EKhXyd9l2IIivxVYOLdwvPg8mHwsXpP7htFeiemHBYI\nXl6B1fAQ5nIqFH6Bmctj2ZHmnqluOVBaRdQjwh+WIgx0dbdb1YOD6QJIhiqN\n9UTcD9uoL2R10n7EMlXtHTLWnlmr19q3pv3Yv2IlI3DQCxRfcslIliupoLGN\nD5+sAOMA0XXResEU5SxJ9D3T/IwFysFbLysrBBZx/R9kHvBCFuR7H4QsKLWG\nhwS9zfQJDs1T/r3XNpyloCWCqYFyij0EUaBcdF4CgkoIcJRcvXl6FKffB35A\nuY2FbVmR+Ok27NTUdAHKTRjCxVKlH4y6KE7+HmynL3EDMNbLadVIScsZxFa6\nPbCVnzt0kxM6UecA2XV5pVmXOaoxrK+1/pwr+tcFgnb5lRm5UjwzoODlo7sm\n5mPyuWAbEx5re5XL3Emwk86hcXjI8j8INA/4C3uWGmyfIjkyDhvqbCad3HAN\nKUu4nbuRrujaFgIkylqz8+y88+j25ux+thUvjOX48Ug4tHFJnsU/xPP2Sh4R\nt+FGUTTZcH3ogutkPVRy2HQkFzL6/x01FQw2VQvhe2MR0bMMtOq3U3qUw1dN\nmkxw\r\n=Q1UM\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCIgS85W7ZBESjLw8TZhtv0eh8at/z1rmKx0zINc/OdZgIgKcAiMY3fggz29J/752MV/M53bLNL74iwS9+7XtSVyIU="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.4_1557438551214_0.6222852153368206"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.5-nightly.112154138.0":{"name":"@litexa/apl","version":"0.1.5-nightly.112154138.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"7b9c6d5302d1e9da84f72a64e3975f5e7d86e830","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.5-nightly.112154138.0","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-Xvi0KZBmX4MbmYr22W+l5aGKRBMwOaG2JSn+1VFVMN1FyOgamvohU6GTfCWNLJ25PvdzbOTwbRjKHCjDp9aOpg==","shasum":"8bfbd0cd21e123e3c3e825e76c08f1c566d0ab75","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.5-nightly.112154138.0.tgz","fileCount":29,"unpackedSize":114891,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc3ezECRA9TVsSAnZWagAAJ4AQAJBA6LfFrUjs7QdjxXuK\nAINQZGxwlo8KwsEppAWtsj7qI5z9Cabo1g7eYdiBUIhF1+ISuLmFGP3Zy1Bc\nHEgLHlQf2FZZzu70Li/v82jEYZ/lP2P8upOiRdWsw1YQ9EDeDqSyXWSPf7ar\npXG4CeKdrO1WfHhgpgPRZPHWhcLJdUAOw5mIEJOYzaCMw7fPR3YLsZT2Sh1N\n+Jb/vhXnZD1MAvuav8dcDqi74vGqZgzXdOcS+d5yHE86d4p7xFraWuiEQxry\nNHxeZaq9Dv+GNnsZXW44IfGjMuhOHbASbPQQYgrAHcBHYaO3pqNI4RWvqvUP\nloa/IRZ41YB55VoKgTwpZQVutsjr94wDBeeg24+tgEjFqeCQTI/I8uyVrujX\n8LNYGrHE3whkRU4P8+7V5RTYltiZWgqPRosQ3sJDL3EpRXKPbsBxcvR+SDqZ\ncCm8am+rbUUP4rlw27KOzvUKsgnaXVMy9KALrm3CxePcuaCuFk5VXM9QPLp6\nLl5GyhrMSyNThRvXBt0lZWzbxEXMEP/8C8cmFzQuT953vlrhfTJz/jVu7Usf\nxYzboiqbZjKy5kVsVw1O3DrzrQPr0umYDYR1bELPp/UFmsx3+jyDbIR6WB3+\n39vmOIW0SwhVxffkABteUaX8BWWiXc3Cxu1pbGEyaE9wVhSPlFXHqhgf+dyU\nB0/P\r\n=gMnB\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCLoM7zB+1LQqtRDwcnZqK8Q845PxG0cQ7KpD8ql32iLAIhALbWZfeMBhu1MuDllhGE0BOER8+IQHt04h62WZdYJWqB"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.5-nightly.112154138.0_1558047939674_0.6321733651890318"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.5-nightly.112295593.0":{"name":"@litexa/apl","version":"0.1.5-nightly.112295593.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"7b9c6d5302d1e9da84f72a64e3975f5e7d86e830","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.5-nightly.112295593.0","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-t5JLoYrYhkNbP98jtFO5A0iBAZR2GzmjWYaP0SPmDCtFUPSoJBdYt8NU06FbJQpud926uOX7Cv4jF848m/wVMw==","shasum":"bcd64b94d4fd6a3c6638beaf85006a5337109745","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.5-nightly.112295593.0.tgz","fileCount":29,"unpackedSize":114891,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc3z6PCRA9TVsSAnZWagAAJnYQAILqjSezFSP4/SEUSMOV\ncDEkSujyGFM1Ufg2lLEAfISB5za/89RmXiPMeUEqsMPgW/En+QleQ/wmFnH3\nHHLTL1MwLCxPZWVnAioes8789ihPBpT3O+T4Tl/2TSKvV1Nc9SXuBa1O+ctw\nWn9CRJn/YIb9YfAcGG6CNw6I3dETEyMCtdofr6uDIbQMbrHDjgUuDOKI6Lqa\ncV6h+eQ0xzQ7/5xGo5d8534speVFfB2EF1eKfS8b47WhYgzcTrLsPmxZeo7R\nlgtY12iWWMEC6JsT+WkBNnP/X0hFL0AwxKCzX8+waRPtripAcoj2iApRIipx\n1TGVopiQAa5nduv8z6Qauc8s0UBEoTJmaIuOiwZoniltTpUBOao5aGO1/S+X\n1dnamx/kZk0mbpX6nEaHkc6LI9ckwu0hhPmgvAd6UHwCeFVzkulH9q/K9Wnu\nnT65UVui2tfDbixx2U0HfyURMuXCNTcvy0L5uLwIxNa7TCsER1vD1fFcZhph\nFbrpXM53AEj8uBARAAX01Wjdy3IvfPIrUMULX0kNh4jTsjIy8Ruq/kFjcLM7\n6fPMwwfXbQB18dmZfUhLXzQq3Pq3PmE1//6Wg+9GG+5u23m5AnkVlKwP+v3D\nHHlG1NJNpMr2I0N5DFYDy0v19lDjeP6zEuzqMOdcb9CZLlw64jzKZ8LU0mf9\nfSkp\r\n=ffAv\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQD8wzhAJh3mqMPsSGBIxpkHcTGWS/sC0WvFW4bmWp7waQIhAOPlqEzaFY64V3M72VUbaeXkvu+ZQJCEdG+8N6+b4gyF"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.5-nightly.112295593.0_1558134414621_0.32441238155303154"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.5-nightly.112335225.0":{"name":"@litexa/apl","version":"0.1.5-nightly.112335225.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"7b9c6d5302d1e9da84f72a64e3975f5e7d86e830","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.5-nightly.112335225.0","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-bMs+s5jEZYKPB+ZqbVCuubUeHyAdx71Amye6qkaECUGdiVUk0Tg58rAkkFVCw4m0MTQRS2JH/NlS1W0fXtK7kw==","shasum":"0b5797e44bd163925e16fd1419006bd4fa482c58","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.5-nightly.112335225.0.tgz","fileCount":29,"unpackedSize":114891,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc4I+9CRA9TVsSAnZWagAAJocP/2kwysuQqyPxtlkxXsHJ\njSOdhX5jECKnSEACEhSG5563XLij+Tb+HFyMYkg8ZXIzqkBcSrm+Vbr2nAHf\n5tmsmF+90aEPeeWT9AD3+/YS4WHZ4wbwKSaYubSco3y0dv/4Sx+LZ86U11m5\nKKuVxFs+ZJsBHKp/e/ghzyeLafk3H1DDmGvNpG4PWxrFGk7bBzaeknYXCUKB\nsvCWbz44ZL4PcAUGPGY3qDMB//ef28hLp63/eFSXnC7LW4EctL/3lElaQwQB\nps3bd1vj0YHcE3shvmlOQpbjx9pJZvLhOOMa5lBccZF5NSwEC8DhzaRbxP8Y\nBo2THiaEfsLjUWLd1UbAFpl4fN8FZWaknejYb7ljjV1mR7Qe6o3xipQ0cixu\n5Sus7oLINqR0+P1NqTh+MRic6aaKnxXnMe6Q5tMkpMjvsgsMYPj1yFQRN4f9\nODWq42J9jOCFq3s2lH+V3DThbW5Ym3+53Zluv+sD7Ud7MVH7hUR+7UqAdQRT\ng5N7vnO5XVusYOnKctZ1WgCSj/QuNFWmHjqQrPia6SZvy90ie9D3nfYmIEUm\nyi/8IWwwMg8WCFBJpw3//t6eX8Ry2VidcwDskD7097mz3pup1mtxFM1rWlmo\nxDSjGFGzwXrntxTBj2Fu1fUEOkv7RXySjuhp3BP3lpHKq6Zh7sXqd4VdhnEf\nuxWK\r\n=9oJ5\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDy8PqeGqhK05YuBmqBOBF+7WCJYwwUWBJMpKHACqc1gwIhALCJH9RMYuc9Nl4b3Qr3JIat9rTRjjTLzBKxAkYdjIUi"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.5-nightly.112335225.0_1558220732709_0.4824372079317467"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.5-nightly.112374729.0":{"name":"@litexa/apl","version":"0.1.5-nightly.112374729.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"7b9c6d5302d1e9da84f72a64e3975f5e7d86e830","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.5-nightly.112374729.0","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-zwCkeSFLkxB981mJE1O5Ppkxjm9qd7hBfGm/FQfp4OgLMXA5RwRQzc7dYJR2+LvF8eCOkwnkCdFVOcguhi8Ktg==","shasum":"cab6520fe64525face0afc6183094bab204c6c4f","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.5-nightly.112374729.0.tgz","fileCount":29,"unpackedSize":114891,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc4eFPCRA9TVsSAnZWagAABrMQAIo7yE1/ol0HlHIZ2rUi\n3ZszY4Y06V/oK+qr89Sw064m7uDkGBQPRSek+qABDRrotJQRocPCBRDMPwNx\noFMiqnaB7Ob7z6P+ogbM6+DKXrdGyLy3Drpqb6szUkuZbMIA6VLoiuIEKxxb\nJR4HowMqhQ1BLOtESaHApN+DY+YUndMPnj8vz3b70G+9ZXnA0W9Z6vCAAbWO\nJDUH5FbUUqpPjflY6MQcSg8TZ35Nxl+e2H5GROV9zBG9F53SzGwiHhkBxrl7\nRRZ6aDie1GPNi2ikpqscxkOMV+rMzp+OyfZ5JzsCEDZQBFAJcHYSv3zx4+Ta\np9txfja4PesznqvNMSLUPrp5Gpq5OQjF9N3gO9c2gyOr8PXvISzJOQnq69Fi\nrd8IPEAgGllmbq0KtlIhDHRxbw0mHNjB6Z7KRpmm5KxVN2jajKE2olRddOdI\nV75X7XnXBRUWG0YEORdLfP5CmYQapSeMKfuV7cAWywX3ms/8ghTtO7aRlhQc\nFzeKp/C2SyXQW6aUP/aQkEp9mRbdKlRnMeZlApm07hbK2q+4FL1DlCr0bcMD\n8zg7XcDn4Cmgcx5tGnfhlLwPM0TJaQU/W4rdfMerT68dTNDDFIZyGFMBqRMB\nWsuNAkJ6a8HsHDET43FWHgMBXL+xu4pik9JfpdtVgR8NspZt7dB4vlpk173d\n02HL\r\n=jEi4\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQC5oTOgMr7ncjsz2Nre/5zodNWDhwj2/hix588MtbYj+QIhAOjn/hmYVvLxWmxiVy9nk5HLt+HedXUqabkKodY264Dl"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.5-nightly.112374729.0_1558307150098_0.22989644790754982"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.5-nightly.112519784.0":{"name":"@litexa/apl","version":"0.1.5-nightly.112519784.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"7b9c6d5302d1e9da84f72a64e3975f5e7d86e830","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.5-nightly.112519784.0","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-ClfTKlQmzpiYEohVJMgdEAX56qYXaZ/hqzPyZGRC8Da6c9K3Ew4H5/rNw5QRmMPRHr/jHcjhxlEkeWXN/OTUGw==","shasum":"2f298e7144a2854385f5faebee6ad988f32dc83c","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.5-nightly.112519784.0.tgz","fileCount":29,"unpackedSize":114891,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc4zMfCRA9TVsSAnZWagAAunsQAI+AIe6YX53EjtT92VgM\nOGvxvoqnMW13YjYY9CJHhREvKfR0TpY8dLLqOvQYH/LdkL5wKMS9IgPG0usK\nbBgDXBChifDHRjzuDvv/Am9HpRoxB2lpqwY2hhPnWa4x+NRRBv7PP9zqHYs6\nyEqbnxGe/PBMBSHaaNFFHJsiPWEacGlVApB4Z1n8hFRxHXes4OcdhmwrNW+7\nBzA6kCnrzsJXe2JNpZFA9U4c8bWNnB0X0aB5Yl5TrlruyWsZCqZrPUREY6F+\nEAKdtItY+sAJfL1fBu/TrvMuX9WWOBQNHU9xtobxWlslv/Q4pasYU9tupJLG\nHy4+aJKJpSWCg0wC4ri5cQN32rWJm15oMMwTUeLTRBkFYNcsUU9RMjVMpDI2\nfTVCFOeOOVtLLSzgaIgQe/T/po4YP5RnxmvEwr/sjn7MVmyN2LRK3qF2dat7\n8FLk8oi/BXqIEQ3ija+tBC51TGifORoeVD5xGk5BR1Zr37VgMBntMPko4Alh\nKci4luJaRfq+rp0drWd8yL4Wi5t0otXRpkTZEPdprZRdA8Lu9YpyeKAH9BM0\nPQV5uD9629fBJ7wj5ON3UtBs5Kkc01fHG1YF4KRPaVQWztAhNw2JRd0Jfx5t\n7oG0u9cBOOnW76NU20sv6uAs9uhmCro3uJBbgv0uOrwFkEXPN6e0zCtI33X7\nosn+\r\n=s1VR\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCnJfPLvGzk8XpHx0XuDYL5f6YubsPsMxKs3k+6wQ9VbAIhAIp7LF0cod6YOfF1znYobxlGt5Eq8t1/b+zGylmsJILi"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.5-nightly.112519784.0_1558393630213_0.16946217875771752"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.5-nightly.112682969.0":{"name":"@litexa/apl","version":"0.1.5-nightly.112682969.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"7b9c6d5302d1e9da84f72a64e3975f5e7d86e830","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.5-nightly.112682969.0","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-CTljjZfcMqjc9mXViAZAtlslTNQcKHZTZn/8xfvMwJW6/tUO9FTYrJBax0XlsI4dq/aM5CmXhuo4rL/1XEPrKA==","shasum":"a6dbffd3a382bd58ad1f5858317ddc20166c2660","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.5-nightly.112682969.0.tgz","fileCount":29,"unpackedSize":114891,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc5ITGCRA9TVsSAnZWagAAQK4P/0AS3hvgpei1p5muTpS1\nmClczuZTfXPtLkmNfFj+iEw+712DbMwnYoIqNzV6tmp9VFqzXv8g8imhqrQp\nedprnwcz8mo1BX7SG83tAH6cl/0GvgIJg+IjJIOY9eU21JMrofbFIZPLrt1I\nvb3LNHE9JVkDMXXt8zWvG8g9v82fH8yHGrc5FklfyrjQRnGBk+xxmUK968JE\nFmB4SWQXEqAUJ7BfJV3qW+lC5nplysI5xxmc7PjZWBpWFuDSe+R0c18IgE3e\nQlpY3eK6FsU2YdoeVb9lXNbxprS3/Q3qUEIQnXA6GZ3xCCGVr0QKOPAZowH/\n5PaZCndKACYJG1ZD6XRg6DC7VeH8xLRd6TTKgOgacrcNAOMWmVNyoXGRg5pp\nEywAnSvJ+NPeH9jKumis2oyJNVVPaXpT/GwX3t0nmOo4QAliur4mHNNxD2+Q\newVugHfpg//TAgYMXbEVYtEGAoa93EZBkjeB1n20M+c3nGRhruPwFdSTfb8y\nG63S0Et6nawTewW6EZVBfKi8ZWBQ1yiYLI7vpMJopmVV8mcSpQGA4TX0I2rq\nPefsQZ8KtwxUKiTqJWml3BCV/lDnkw7pcq69xPkEtTZcycbeSY5mfn1SaFow\n9Ubm9B8Jh+DYaWOa4Cn52CEFHCwZSTP0+DG2Djjd3W1LGGM/L1mydEYUXw2J\nHHpL\r\n=dFSa\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIHzUXe8rAHR+Q6Vcj2fEVmmHe0gSD80um0+0fRebCCLZAiBjoq3e8GXa2iINjFZfa+omSSa6/k7ANmYKJpW8tnhPVw=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.5-nightly.112682969.0_1558480069443_0.739135408707529"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.5":{"name":"@litexa/apl","version":"0.1.5","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"51341595db365ab7874cfff3faf5ffd314cd1075","_id":"@litexa/apl@0.1.5","_nodeVersion":"10.15.3","_npmVersion":"lerna/3.13.1/node@v10.15.3+x64 (linux)","dist":{"integrity":"sha512-qKr1RThYA/thx02rdd6pnooH6OJw0dmHm5Wz7tZrzMCAq3UXlqenzhAqDChLUwGshIWs4tqpecPUtKvuJmJ3Yw==","shasum":"a06653285f81997105e0046f92ea8751d9054d9b","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.5.tgz","fileCount":29,"unpackedSize":115008,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJc5b9FCRA9TVsSAnZWagAAOPoP/0JRMZWs1NSbZpiR6okg\ngI2gO1EXlcXLKIGHy0EmcOnnmszikrxL6cS7MZ4CD3VBF+FgNRhZvHAlQDFw\nhq+D9oaHZWI1QSt9wkWe1PY5/E1NKPVo51sgvxyX7Xc3v4O14bt25u0ZxxRw\nLIGJStq+9UEjcaJLT5LCziZksOW0OLJNnCdi0n9m7VWz48wpIkTbaOaPB4XG\nEJJmzP+Eh4x8D8Enul5N19SJJ9PMOW4ZDBldthNPbTtRlJKA/WymlnYUxiB0\n8apuG7eMtDhtua/Kj+XsZtPgn8YYX+fcrtqQpHDg3qDQboYeUaz2R1GpB5H2\nqdNpukUFf62921qmSpfA7YGjZKxskgHEwCHtQqS/8JxZriqkhbx+8n7pc2+T\nbCnlP6vapj93C26um3YfHcaqC7AbvtwsgUZJh8st8rTq1ttkSW+cwv44qohT\nkYlif78Zudt1jFXaca/WKtLoWLm0OSrtd6ZUXbHBc2uTKxmOQF86qWjDPBdV\n5ip6e6mWXQoUECo/vjJSd8h4QEZ2iD+4RE/hgKQCH89t/55q5fJrUWxQaA4n\nmhvPMzQztigPzW24izGuBzWnsMyv63yO33aZboXxS5Z9bTn21FOLdRtRnJm4\nEn7QLUqKhT3EpswRa9IB1rZDGzayZohmzmJ9np28OgXqW3kdRdpj8aeEH4Ha\ncfV/\r\n=KGEn\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDX/sEwk7qK5GeF7R4lUH8jxeVbnt13U0qCDKHcjAqhyAiEAnyOofdbxzrGKnJRuOQDgyVl4SBOY2hV7NyXDGRlBwLU="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.5_1558560580516_0.7024130275536522"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.6-nightly.116497869.0":{"name":"@litexa/apl","version":"0.1.6-nightly.116497869.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"46bdf16d5718eb0f5dc816579359366e080fc236","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.6-nightly.116497869.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-d6HxtN0jOUt3/ZgjUj0KzoA8+oybzw9wX4s9BfwJspxgx676hHQAlzLWpFURWRMFYKOvyHzmrq2pS0n1vsKjEg==","shasum":"782acb6a060d71a306b02ea7f4f0847db0afc651","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.6-nightly.116497869.0.tgz","fileCount":29,"unpackedSize":115019,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdDWuZCRA9TVsSAnZWagAAyFIQAID9CzTJN/0z8KXvUKuN\nNU30YV4z/I5fyUo9YxUPv0r4An0CquGZYnlmvxoPUNloBu1ZyrzcZREPH4hx\nL+yq29HzIIas3UkgzMikkSmMRRmUE8gXscSHwbSfCogQ4rSD1yBG5QS+OKrv\ngPNGw+58t3wfaEV97ZifHrP7eO77cCZP0aGAqqLcbRxcUT07fg5Xnapawoxy\nUCCEdGLQY8ZpOeFgVdYfR2PwYgMWpWcs0sxsr8Xpe/pelhy99lxM7gyc/2uD\n/dRT5eu4sBC1JV26twrWnlk7BbCHX+NlF6ZWaOyg1aAfdFDWbwNSTjvYDgLc\nRZk/dcO1Cd8iwtDiT3NdvEa9WhxnnUrL9fdiNTJkMq9hIP+nnwIHBqLxrerL\nNJBNWkQ3lQIC6EoT+78oVzvnKkOjq6dSzEltfhsxp5r35bHSmZ76lk/RHEXN\nI5Wds8zp9+6hZabb0bGNFUr26x2d3EPAU+8p6Pm1GctHVsa72uB2plfh+uKW\nBxsfuxmN9UADJ3FCtNqn5xr9etZTbniJD6fA7jophlHb67p1/TB/f6iIE55A\nU1zHrCCFH5VyxqkW2HMBsrxK6saIkVWeV/EHxpZpiCcjsIuu7+Y3HQjacTFp\nnqHZhnXg8OqgQmGYkTErq5QB/FfNqqOmdZXpDRRgT5xf1ShJkt8yRTyE1eMI\nNiQK\r\n=OIJF\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCNEvybCKNXBw9Dl8XZnSA37hdlQZ+LSMmd+i0P7WhSEAIhAOwqsbVjB4v11BYe2gTzmK9xpCPRMZ2S29pYtNJDbBym"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.6-nightly.116497869.0_1561160600442_0.5524490384310126"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.6-nightly.116537503.0":{"name":"@litexa/apl","version":"0.1.6-nightly.116537503.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"46bdf16d5718eb0f5dc816579359366e080fc236","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.6-nightly.116537503.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-GxCKdKPL8b2hgURDYXy9C5iaU+WfK7RUT1b4wkSBd3KeKc8pxsrrzwzrpanD26NNJ96GzLHTK7yyrTmBmj/uoA==","shasum":"77349f4f394b24ee6328f6229abeec76192acee8","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.6-nightly.116537503.0.tgz","fileCount":29,"unpackedSize":115019,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdDrgTCRA9TVsSAnZWagAAkZgQAJ5/apV0zK7p2kiIFKJd\nHABGaPTjRfzsIbm3iSLKI5wAxizokuhizb6mA+xznlReVxN8ApS7KfCi6drY\nxG+4AD/bduNqOgLYqOczh+Jw8jYIWq6QAdBQTNnUsrYEzY9mxG00GKNGuKwo\nFkph+gYQFtAuKBA9JUodhjO7D4XzWoZJRXmUPNCJuK6v7Xj40Vv6hkiwbPTV\nmW+s3bREiMSU8MJsWKG0vJh3fsyTp8ifwPriWOF2s0sPIcQdC7PPqLXCHCjW\nz5f2ru39a6TsqG1vJzmk5snwLRuXn9CIOFbmF3jKddvVFdOvKKXX8BwyL6FI\nn6CtlkJVCW3+pFPkmhLd1ZCS1Faa2D1CUEyoNEo78gn+D35nVIcRG2FsYWHg\nnaFTz8JXxaJLEnRg5eKyezV02hBKlIsHsml6m/kcjNe2IQqDDTrTQ14p+ivh\ntCRkPok3kzTVBRuyGD3oGqR7I12o8JNA0ixl7LDtpGFPpTCZwVVjJuFw4QjF\nSx9mPGjn8A4jlv76vHWspZX2plKWZXRgP9YqpKuFrwSsuelLxr95KsF34kli\na6DZkqVvFvRwnOl9QoToRJ+7eRwRNnJbr2bj4iDKBcjMT1Cg6rJEuf4iQPSa\nfKqyMW3UUa9cOuDIEYfGygPoGAAh9ApNfGNCUIx3MYXZ94X1z86uup20euIW\nPC73\r\n=Eygx\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIGpcoxmFEy7BkS2kmSEbqg9y8v1438fuyxuGVtCqO+PEAiBSZ5v5RYIHverGIWy4vC9fe4BdADMzpfZoaZrG0WYnyw=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.6-nightly.116537503.0_1561245714653_0.7954474772070013"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.6-nightly.116575979.0":{"name":"@litexa/apl","version":"0.1.6-nightly.116575979.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"46bdf16d5718eb0f5dc816579359366e080fc236","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.6-nightly.116575979.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-9UP4v7KYhpq4GRQgSo1i61cK5Lzfqhi5qfOxcnfTyWrQLnuBNe9Zm/J9aa5XvlPDCvkN/CK+l2+j9oFB/KtjAA==","shasum":"f0f4d16056f1cac46f4e959db2de55c1b7027054","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.6-nightly.116575979.0.tgz","fileCount":29,"unpackedSize":115019,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdEAn/CRA9TVsSAnZWagAAbEgP/2Lrf1YEpFQOMiEKuCs0\nfESL0tFl+9CRFsdlVXxTMSNHzzDj/P+8wENWwC5TK3R/tiRZo1SLRW5u5Zm3\nef1JG6NMSj1Rhq9JXx9m8xLLhlVbOsVzH8lQGfDCAzgHM6lh6n4NqWZODDyD\nEPJForA9GyH3+M/msr5qreqaM8KCle1x6qNeqEh0fQVO/Y6AUOqVotoFSvgr\niqi0atXY0tL4ogIf0vtJaSK0ihj7waZUvsJXaGXY+M+uLt7bst9+MfZC5O06\nvUwM7nHSks14mUrFClRpndGI34/VG4aRheOVBIkktMTXSudMQWzX7vNKsnLh\nYAjANBfzOIL4s/JGu6PYU1HaL3aPonDWTCNZRzkwGRwJPD8tcJByvFLQWwx+\nlOZyttNUPtIrCOosG6QE7FWSYKyDtZ5p8NpitwjLJOXVF6y21Q9kXigmezTA\nNSkZflLEuL8UX1i9+sN0Hzd2fH6+c9p9foYcQH2qYhS2dpyfpSMwFqkZ+kxD\nExJIUZeGe8y4bBSaYvWapsk1rs+Peoy2p6PS+czCA2C73u1egVU9Fq88q2TY\ne6NfRmqcCGMU6CgkB7xLcqxsIQnb6bYpVaYolCxhm5SrKsivjEJ10dTEaJC7\nwkQC4yz96SQY/ka5/ntN9/Kygi1B2jxoKDu+tNpvpt1dDKBCldrKnpQ2SGGr\nf6d3\r\n=bGRB\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIDfElzygBCMVVXR5ueCYCKiFzLp+HQIbgPsDLSvadA6sAiAETdrU0aIkMOVENX859Vq6BKe95enpVAES/qfeOD0Ilg=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.6-nightly.116575979.0_1561332222996_0.6292639604113721"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.6-nightly.116725281.0":{"name":"@litexa/apl","version":"0.1.6-nightly.116725281.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"46bdf16d5718eb0f5dc816579359366e080fc236","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.6-nightly.116725281.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-LC/VWzNq42wz3/OghK1o4hCi7zxWKqC/M9LTvL7O899DkGFMbjxNcWiQmiwmjuStuN4xVv8/FHb/v+nus8fqxg==","shasum":"7ca3f0f87d8b1746b65984876c31761aeeb1dc60","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.6-nightly.116725281.0.tgz","fileCount":29,"unpackedSize":115019,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdEVvECRA9TVsSAnZWagAASScP/2kBMCOG0Xy4lA44pR2R\nE9yj5vfqZcJ9F6akTji6zVHIAHPNqZwEVi3L6BQFUF12rkZoocnUiqr4wViM\nfeH6lOK2hqEygFPf5EcG8tO5wkx+y4If1b3d1CypP2YgLXc4nppR4mRdHL23\nmoRY730IlZ+nQ2W1w8TGQ8afnMqWwmfJy1FEvB8Emi9k66oroVAKj2iPI8Db\n0gjO3mp6MNy+y0MoxP6grkzQelq7HZBjK+M4VS5rWfGoUb6bfB/xWwcUpSu1\nxJZp5H2sd/gaOvvGajb25h4alUSNPmyObMq1lPAEwcS4dLD3CtJQiQK0k7gG\nXiAHHiXnqJ+tfe7fGo7q4CnXHtGCXxHkBML0Ut4KIecC+8JQ1c1l4E9YowC7\nIVnBPEyr805uXEkCtG85yX4b0F9lAiawWJjuhhHRf+PTrplW6hQy7yXWL0zV\nnL6hqHvLFdUzSTGSrkCOSslYH5twbVdCGcm4aaOpSuQtGl8icHJYQFOA0m0r\nf0+HMuLTtWvAMYntdZbYy8dg5SnKdf9jYQ+G2rfE3SBEOKhOX5DlgeDjLUWB\n95+E+4XObknoRtDZ3gcuby+8v5RAOQcAHOet6VJYBlWOv8iNDOmcDJyxcs5V\nkVjTImW8JDeLH5G6XxtvzG2RWNrQmg1XWvga0cN+NY4A0OFpCTxkFT5aEVtR\nGvMG\r\n=Rk2O\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDyUwAPvAjY+ed1dBlBLH06JIo3XeGM0hQpWUlZDexpVwIgFvZKjBwr2wrW7vYPh9j2JkVrpKfXRUGq5dGxwNFotno="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.6-nightly.116725281.0_1561418691478_0.36540980295932446"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.6-nightly.116894862.0":{"name":"@litexa/apl","version":"0.1.6-nightly.116894862.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"46bdf16d5718eb0f5dc816579359366e080fc236","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.6-nightly.116894862.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-PvDU8yf4xqNUiCErGxoeTZvj3vOqksNKn8ABlkNPyna+wOQAB54D9SnYXCZ1Bd/3jKMYomXv7WzZj0G4yHyeBw==","shasum":"17a255545892243024455bf20cb3d7200df28400","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.6-nightly.116894862.0.tgz","fileCount":29,"unpackedSize":115019,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdEq1OCRA9TVsSAnZWagAA2CIP/imFc9pfmhzAaN896mGZ\nSZkyl4keVt3hHLCt6lCDYi4NP/Jyp3GpDIADbA535k1DwinsDcSGPdxAspi7\nTq8K0Fr8rVPrlOwuf/mhyaHf9kWoPV5FGGvuD690R4VdZam5+NBunDGvFSg2\nVID2qJVlL5j+lRl9kMZJviIFQHxL7NVATN/zV0r9bjpmgXyvqUUHjYd2EoT1\nwc+3yteUopBqSyjHS2/fehQ9ebysSSLhPrzJTo/vlJFUAPSgQRa0qLi8/PMA\n7m+cZGOrlzCsU+OucXtBztRvW3PkCszriDR271IAO+RbeL25fW3WX04SL5Qa\nR80O8DqT2k/4nz5hpJ1hjXIscQ9OOJ47GgXbA0sHpvwkJkB5aZ4J0uRfGK0V\nYsFPJGhPKBOcIM++9R/tlEJ1or/0osEy/1lX2KdUCCDNBGeotM1hbCzU7MLJ\nvGSyuRodPnE4eeB7wtYy638kGsMJK9VUH6shBILNdQu6oxtnki7K8y13P3ug\nciOQxu+53j8Y9MB1NlwfU1NBGHG8Wxu9cIP361ArvY/2pq1iBHiC1hicdJ0F\n2QuT3VPr0UGJ4gU3JYMXKt1SbwYdgfGFbdbrC99EnExVG4f6gUL+wGl8SgBs\nTiRlDVHkf3vXGtL+MRkRFHiETBZ+SExkjuWbCBlYLFIzVsuPLc8ur2f4uoSn\nReg6\r\n=cbqZ\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDDgfzp8z6USofYSTxDh7ylAc+wC29DvSH3Gmn5F3b4hgIgMubjm/5y9xRwnA9p2KByBkS6UO43ZGtbVpanWLt12kw="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.6-nightly.116894862.0_1561505102000_0.5306979783975374"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.6-nightly.117061114.0":{"name":"@litexa/apl","version":"0.1.6-nightly.117061114.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"46bdf16d5718eb0f5dc816579359366e080fc236","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.6-nightly.117061114.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-WYLllVyj1+7HdrB6oR7K964xzrjmkCtzsAWbjOSPEwqRrDR4Qn41PWm9osSs8R3THyoP4Idp7+X70xoovJRtuQ==","shasum":"9bf36be9bfbccc27261e57d04b5689dce7f7eaea","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.6-nightly.117061114.0.tgz","fileCount":29,"unpackedSize":115019,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdE/6yCRA9TVsSAnZWagAAxT4P/iQMZWqShZFHPKpwUL6H\n+gxX2KaRcRJoLZjUtmpl8be02QonoDA7Za4ZPOSGo0bUlvT5c6ERTnHL7zJa\nzWjzDAzzMHeugj/WXAh7Oogqkn5CSybQoNb0tdxXXSYAU/nd5Ogaj+d6JL2X\npMp4hjmCUHjl44XgjdvcMJWMiOjo6zNOC/9i0xbfQHZ9R2wmoj5aOO4cPuBX\nmFnQW2aC5HS5IJ7GP838Ldy5GI683Pkg/8PjTRrS/zoJrKh7ayU0pRfy/WZI\nzaHbQfSi1ru01qSKqPG7riym/J6p10tzoog7Foa0pP6kcveF3Kcyns1NdToO\nLCemfAyk3ZdfAgQsJBI4pzPZcqrSd2z6v94mJOOS+3H2+nj+oHDKrveGzSYD\nS2cD3RasXAQBEQR81y28rw1GYf1AGLMBDNEff4xAnOBn9Sk7n+vuTH+HhG4X\nALHX76h9bWYNx4vjEHotdOvRkiFnF+qPS3/ik2oTDNK9pL9bf+XDZhvFgfUU\n03U8RqAyt7QZqo0TLIc2rvIuzAKQU7+JfZZyQYxRlFMj3vRYXE3+P5UuB7Ug\nS0PYAHXr1cySkV4vkwSPUvtvP3kw9YjacooD9vrEOB7a7NJZHQjoctv/pmcG\n5Ut1ni8tZ+KP06vn+FUVNZb7UL21zE1MyU3bZOpUCvrCCSLQraeEOhUPZ0Ky\nMWBX\r\n=bwSg\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCy5bEwDc4msKFm3jSIw8S7TagcCSkbtgPe+newNUjK6AIhALmrHukDf4hQeCwCfNn4KBWfvsSa4uQX08pqPwBxHFZM"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.6-nightly.117061114.0_1561591473749_0.8856597280357184"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.6":{"name":"@litexa/apl","version":"0.1.6","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"1c3a75c51ff0ca99e5aec086ff6f9c26fa225874","_id":"@litexa/apl@0.1.6","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-5bYH6dxFLMaGLJqvGA4gTZVPYABVbDKfqb9F9wfUdVY1BAzfZEVvxY2MMz+p0zDGrHLxkmZq6QUdm6hp0lUdIw==","shasum":"aae3280208428b7a20c77978e33781bc3eff02e5","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.6.tgz","fileCount":29,"unpackedSize":115234,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdHUMYCRA9TVsSAnZWagAAtVQP/iMJ35EESueUnvuUEZn7\nengMvJ9a7wfcxE+oTgtoYrX+dNAGjhg5VxcTTXQaICKxMEe98KqIwWFK5sbW\n4nbUw3eLh7nxTl7BxfMhAJJkm79zyPZw54OuytadvFk92koJ81AdpuoDNfVp\nAT3+oEPf41wZZ9j39aN9OSAuaBL+ouPMWn1cD0YhEilGJLWhxBsh0Pv4X78g\n0TKjZkF2ZHjNWsOfYOa9ZftPgaf4TSjRGrU0l4hMnEcDcsW6X8zUrXU1/PGu\n9C6T081NFZF5UNDIlsacd1tK24FgTv5rqx+bbuvB3ACCXxK9KgumQwKZpX16\nmv6120/JleQvFA1Q8HCct3MlcTL6zFytXR0NycQfAntS1vt9slRkbLMZMcJ1\nPhX/RCy1gNvgHV8ExJKo8WNHhdlpal7qcsGLF4mIelZ2cqXHMMT4hGxJfqtn\nhWPFBffuXSXPQU6Jtc0j/C9/SBw1tg54dpjWU5bJuvnM8rCrn0gVyoyZzb0E\n2z+h5LemxVbX5OFxkYehk4kggBzK48YJX7y6lqc2p52Yo1GX2v9IPWQF8GBu\nN7COHrpBmjaUWV+lxfy0Hg0RkVvwfumOS4I0u9YSFLGK8CzcH6Ew7uba905Q\nXKnji4x5CPJ0oU6ZtQpYUIPMgh9eSgqyjrJuKmg+KnfB6dEs8Jkzegl5Vywk\naumc\r\n=yfVp\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCrgsp6x1hhfaCCz60wZ/r6dIrXuoQhEDj9kTJfzfzYYAIhAIIgQM8txJXfHiIkPcao/2fRq0/JBqvf5XmcMdQQ8ioQ"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.6_1562198807774_0.07651886344980352"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.118656676.0":{"name":"@litexa/apl","version":"0.1.7-nightly.118656676.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"085fa79a6f10a59a306b52ce8dacdf6cd29e4ea1","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.118656676.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-Qr8RgFxkzuILOa0y+HhPYWzSKL11I7cn9s1q9i4V8DLVbbZFGAg7NDeNnynGkn4tuafiKfs/7DOgS4SFcXUYfg==","shasum":"2f7b48684c2f5775cbc6cc35e2a67fc41b4cb067","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.118656676.0.tgz","fileCount":29,"unpackedSize":115261,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdJjP0CRA9TVsSAnZWagAAh2EP/iAvwBL1Bq5dwofqeAtf\n1LkalmO4CLo130Nse6X5vnruxfx1bS4+PbzVoBRp1lfvwX0f4Hm3MixsNd41\ngYDXSY/EEKodZZj5aFKNa5lu7MSzQftvwXt1BZCWAOEwtOInWS1nTuG/+QYM\n2Qk5jVxoT7huipn2qBJfgDFvSmuPTbpz+jv+myqq0eTRg45ACKzJ1dPA2h+h\npxONxGt34Q1/MI6vmz5KIjeVws9pGteH+33fl4+4v8SvsIjl0fxd6MCPozUp\nKPmJTJApSYL2YaYCVnM/F7ffwsN0kaPIMAGLDopOEFPSdWaEHjGxsaYiCS2/\nB9EQAKgtrBWi8iHYdMUkCYFDgPQPSj8UJzPPn5rFT/MnvU8S+03LRHcN1/HQ\nhRY43iCcfqXXgn9JrNCw1LU6x3CfoaTGeEaLM5npslJUhARtF3Aziwa8/Kce\nTRvgTg8zXUo6c/KZyOwBBvaR0g1gRODTfs9EjJpcJzIhpvmw/OVBDi5+7mX4\nZf7aLMCydBkvs+SEMreeKQMso2wE1K9a3Rg9g2RorQGBiDsIY6WNIxyyxzle\nxoIbbZHo568ALAP2ytNEKt4AeqQhiq+g053qVeBZyYDfyw7beqyCDpEGx0Dt\nYWeoRc7TdvMcXlhYVsnFO2IcZscucL+3NmH6JF260uxlee1hEzft5/4CiqL2\n7iMx\r\n=uvcs\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCXfRoAyosc4e6bkMjAIpetbuBZNZsZzO1zkx8BijVXwAIhAJOGSJRiQK+kILT9mQgkxmhOsZrCd1GsbcUDhAyeUKfc"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.118656676.0_1562784755617_0.9725818329835065"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.118827687.0":{"name":"@litexa/apl","version":"0.1.7-nightly.118827687.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"085fa79a6f10a59a306b52ce8dacdf6cd29e4ea1","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.118827687.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-XyrvHPW22GuGN0SYb7PZ243Z9BNObWxlBPb7H3Td4SNFP4qq+syX2pu225QWZjqufpvxt41QlHaFbnVP5FFYOg==","shasum":"42a4474ebfe7801f1dfadb928989512dd6e12e35","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.118827687.0.tgz","fileCount":29,"unpackedSize":115261,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdJ4O3CRA9TVsSAnZWagAAP5EP/0baZpXtLNh6D0bHq7bG\nMxhmvXzlyirWCsPrezO6YtfT9dWJTpkDqV4UcPnULCL1/WJfSOTtQZ8X/yVg\nK4JPiEUySs58fR3oklgHfr0PCtxSlxLvK9FyX6Pyjz0WGWsyZ1uCxvGo855Z\nSC2xORjS/lJp2qNLI3L5DtUG9g5h7Lo1Dfkce+GWK3kVv+pJl50+fYlyrwFy\nWsTiJki10fWVxoO5mpsdrVUKIBHAcsOaz5Fly5s5B7A2TK27Tp+8ailjT11r\n3maU0M55K4BANmxK03SP7CzG/kcQS+KhqPGL3jHmYV1/xdNPFI2iZZAWZtKY\nQGdVZ6kjOclg29HZT/Qln7NQTYtDgLKu6ZALC2lxauaBTPtSPwkRaK26RQUH\ncE4p8RYguoUI/w+5llnnOqksAyuqGNGIWwsRI1CkmuygwWNT+QNtQZFl3QBF\ndtHfZboionlf6gVe6QiDNLQ8ZjWeJdjR9ycdOzjpOoqGR6rWpmMssleG+7uv\n0mgejaV3nvKHrO8ZmAW2fsSm8nf2qBBYDudmX3kdCHSKWsskJ/H5NNcS4KKj\nSR5hq/o9aBaghHOyccaUTxEzwgftTRJjJVqhOn/DY8YQVsnELcUJ3ZtItW8w\nROWl3b8fCDQDs0dR7hcaOcRStYG4lUqyTi1BIaDlUFIXatcxMDKlyoyfBCh3\neXs3\r\n=kNC6\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDsYaz5dNKu3W1yIywsR2i2bokQxduWvsSf51iZ/61cwAIgZdTzUsMDkoloIegEAUDKnDFxKyvvR15AmPYGJTgpQUE="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.118827687.0_1562870711173_0.7448332101715258"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.118977469.0":{"name":"@litexa/apl","version":"0.1.7-nightly.118977469.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"085fa79a6f10a59a306b52ce8dacdf6cd29e4ea1","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.118977469.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-yJdOEzegdtU5fPo665bayLqzQZy/COwL4BfjzBE7oZwJSTWNTKxFGMUjpYKnK8AtYDVVQ8RzAi5n42lyo6zisQ==","shasum":"73a4fd932c50d20885ab8ce402be484c0e7fe170","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.118977469.0.tgz","fileCount":29,"unpackedSize":115261,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdKNSqCRA9TVsSAnZWagAA8M0P/isXjFelcrZZ5xA144Ga\nLmYL9cVRHUFkZcYUKDvalESFfkEC83mfLCnc1QK2T/ehsnp/sF2zjEmVK+qg\nH89Uv6Z986HIne5MdTo+EMD8XqdhXOG+mNsB1gldNr8JyvtLvOJkLqIk0l3c\nNihI1W9Wz3AxrBdXVJ6vKaLQghzZp+h5FfiPBkQN3NYSA6LY0CiLo4yDOwbi\nmximmlqatXuCwcjxJD/EgCSfqKNwXHSFZnLKqb9plB3O+qS+Awuqtlav41th\ndeUY8SPk2nDfkhI67iU1BKFDUCx8Pq3xNLRxXVJJ6f8kyubYKr2395BxezWX\nsw6JOgAv9NZsv9fJ4nmsg55pmhBD7xhwt4yQzt7HnZisFdQdF6PDNd1IcmyL\nQOucmPEERcP5Hl+OXg57ALt1PaZ0+lns2nXtB5bUKXhHivaA+xi50h4km77a\nkNwGejKZZLE9UvSIJdO1k+mVBS+3TY5ZZQQcHszHnI0qM9e4FI9ZZ4NUpczY\nARP23kFiRGsC1aLNafUGaciKGDIioZNbMg68gXtAjtP9GFF1JqokIpJ74rmt\np4XbQFwtcLNzkU6z0uatoqLgrb677ZJlDSIqdtuwJJE71NwBGLoxNzDe+dgX\nucDbxxpmie9bwn3PH3V4UzyItuGBTE9weAwpjKizqOd2hlH3ES+Ahk7/YUDI\npgG0\r\n=RtQ9\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDkB5+oGo3Q/+elI+pAxT1fdthh1p+0Q/QFjU3WrIt2awIhAPOc9dFol7Kkw1ZK/GQ60GMHuDj7CuPHuDSn3XoZw7DJ"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.118977469.0_1562956969116_0.968095216096567"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.119038144.0":{"name":"@litexa/apl","version":"0.1.7-nightly.119038144.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"085fa79a6f10a59a306b52ce8dacdf6cd29e4ea1","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.119038144.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-Z68+iioP0gLYGYccgDmD8vqqNC5ePugZ+4wIrvmXlGGHntfoH2bOIBjdlxJFVb0sqTNGMFBccGqWc3gJraKi2A==","shasum":"49b1a0f004abe220058dd705e3797f8901c3e6a4","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.119038144.0.tgz","fileCount":29,"unpackedSize":115261,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdKiYtCRA9TVsSAnZWagAAhKcP/RRHjjNmlHxmV3+gbPGf\n619TP6RUqkRx5zigwX8/f3rOCayz2Umhx2x90r1kl5sqBUMfS6gYqQtu6yVR\nuicMjNkoHwKuJCGedLZq096IStPZolE0/PlxA3VigutUc4pa/d12htKshnAs\n2Xf5y6k21lds2TqxA/cwIXZ1u693zn8RVmX4SlWT9bu7jtjgYknpTGh18Wz7\n0BAYdMK84JGjV4TSbzB0tl9/W8wYqlAgUd2L+D+IGpTBFaUjvczqeQpdzFXt\np14a6lU9mZDtGb5XHhhi7Ec5K+zLWBZlupNwkY85aZSfR4z6pw0AqvwJKa/s\nfNE9w/SVkWJk71m/7eEDHiZO8tURbjexjcKIDeoV8pdQG721A1rlm5/Ekxjx\nl9UnHLwgwv9T+6LQBhnieNwEd40df5WqelaXQzv06i3JleaiC7TW8L4TPDbl\n5XyWMDny+ePqzGMuo8J+2BVItAbzIXs4nAf6ea3+IQoPd4pE+QwaVcUPil4w\nwNG5FlHYNp5R9GE5BObtgaHdl+ot9xbIWSTbA5QXqlb5Q9bW6YU2WX+aMBfk\nfBw/uJ0xo+dKtK4/Ix4uxBsJf1kmcJ9I/sEvFi0CUaFjJ2RYBs/JXYWfftfo\noa/bTElwX0iDVzZSyr1MTijgOaQaGX6Ugi1JNPQ4ekp1BXbbv5NEwjKbfc/F\nZ/M/\r\n=TKlp\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCICH8sR5fqgNuS5nYkKgzzwGNzL6fkJ41pKbViBYlIkhVAiBUgu1FmSblIeWNNuvV8ZKdm+pD3LdFP11kL7fH95Zgxw=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.119038144.0_1563043372819_0.8964333771920838"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.119075289.0":{"name":"@litexa/apl","version":"0.1.7-nightly.119075289.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"085fa79a6f10a59a306b52ce8dacdf6cd29e4ea1","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.119075289.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-ZUVXVZP704Umsgyfr1jHfaCpUY2yhRd/22CEpdP8NI0keUAlk4IT+wKcfex9SI6UNCtWQQpqVkGw7Pan58Cb9w==","shasum":"308810a0a4aa543635c41f789b1f625c3c0791ca","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.119075289.0.tgz","fileCount":29,"unpackedSize":115261,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdK3d8CRA9TVsSAnZWagAAuq4P+gMS76/EJikbvcU4YDto\nkaWzE2JD7PXgC0LLYHVyP2vDiNt6XJpqeVd5C6Dqse9/A+g1rK1Ad9d4nYBa\nt+xoj7lnZojSB27hqOQScMr+dD2OjLA412IYrTCVvf7gdN5potwReFIuaKfS\nnf5ECVgRAyZWQEKD1wKr1tIMN3Nidh9ETQ8pXRYyZTPsPKlfLvy4rkk+UmS2\nZCmdichk5lAFlSRj1tD5R9wcp1bEgF+VqJF/0wPPQF2sCQitxtVIQydd27Vj\nmPfHk+8jFvhh9e42Y9gqesiBbJoZvz37wjzjgWH8+hzSp9sX5lEzELMpKq15\nw9P0hH0s5QJ98cceptA4fDOcCRNngaw0EgVttigJ4OCPkesBlZUgoaS5Tcam\nA0PIV6dgNc3PlZEKTEDns2QDCpDhKayN5aWmJHC5ci+0tRgpguKxOHqS8zD2\nO+VTb9WuSE2RNOm3CyYsqFg9wvEEpMdo59T2ab1zuvL6NU3hI7TtfSqFcqMR\ntj5+Azt2k7yo+m9DvEfiYI7utAh2ovAV7u8T0wQrbzvjv7HmBoOd1PI1+3lC\nOmREkiNF+gqgcCkmOl9p1hBtzZh8WEM9VyHRLyfOKtkIZaly24oVKbMOSWZJ\n05tq2wyHM3VbjS/Ik0nYs0UMviooYu5uleUxbwnWxGl4a20i7f16swSywWaL\nVYOk\r\n=yCaX\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCggdwX1sPBvb/87wLJbA6BLhPZMrVXSIueW462A5vM7gIgFVMSRf6enDpt5Uuf7c/AWE4ub8EWf9X14SBcwSzousk="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.119075289.0_1563129723639_0.1799926365303528"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.119201138.0":{"name":"@litexa/apl","version":"0.1.7-nightly.119201138.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"085fa79a6f10a59a306b52ce8dacdf6cd29e4ea1","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.119201138.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-nx8p8IyBvkkJ4yZdVnaEtG8YrKUh+t2Z3Gk9drwjYLGZT7R9MxrOj44eTF6E3eTjr3YOlL24NQZfJsTMBqsSVQ==","shasum":"7b2409cb8e3ead89e93fbf94e9ff1e5b3ed35a1d","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.119201138.0.tgz","fileCount":29,"unpackedSize":115261,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdLMliCRA9TVsSAnZWagAAQykP/01fEvX5J3JfvvrNo7M9\nDZYNxVoHpw9NV1s81lBjBIcNrvwTIerjH41U5nPPxOhlcuSQ1G3bK7wjZK45\nXh7bFZ/4AgHERF1leiBuMc9GJmf7w82D4W87AA2bvboAqtEnwos+M7drA0lQ\nyU9RYHKuyu2XgTowI0NSjzElRAV6LJEN/KQfJlR8QoEMw4HiUANgVaOuZBHn\nYcOBToizLw8X7y60ragPNphjZuJlFR/xlSvm2Mdp2zR0VDD2+Y1qd1MRAXbi\nr4++XaU9jjfCRXYL+kmx2FX7sxE93gfCY4/dte42dW1U6txO8dhCUYUU9jIq\nHjoxSnT4tG0D02r6fctA9RJ2p5H22uXbGN3rfwKGTL5MU41j4dGvgyKiS4Pg\njTjdyGq1dNuwP2znJbsMY90+P64brWhrD12BMIeJ1FLY/nVRegQGSmW+i6ZT\nqYAOudDjy2WALNty399BNWztiaX6fQZKsoIf6ND+MnrK1KVjV8ZB5H1asH+m\nmHt31/zYUuREPxxWJP8LBiIzK0lM2FBlD6JRLdPq52wMj9VrEpVucw3bL7Vs\nUV/LsH8EDDMsw91g57GmqwWLFhs7yA7xsO3LYWd68Gm+G573Y/0x1Bs6KRh7\n91crE4HOp0d2/0z3FEFJO+37qP/TyBlHHOKZRaaDnomPcwOr9tFw66JtRqZK\nLC+z\r\n=sipm\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDeyQYWW/T22AY8IIpJBgc/HkYmx1BqtdO7nE1YkGNFwAIhAKx6pHrcBRe5SESg9QmHWUNQeWK+zFrqgPs92ZC0+lV5"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.119201138.0_1563216225830_0.15343730618089646"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.119523712.0":{"name":"@litexa/apl","version":"0.1.7-nightly.119523712.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"085fa79a6f10a59a306b52ce8dacdf6cd29e4ea1","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.119523712.0","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-4TTfcm3J5cUiUGtxTOt+4axzI57ROVd6PupFVvfyD7RazBMLU8PTAXy+rDWeaikcjmEtStcOrs9cZYoVGPl50g==","shasum":"7a7dbaafc48d748ccfe2ebaa6dccf14847cc9ae6","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.119523712.0.tgz","fileCount":29,"unpackedSize":115261,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdL21JCRA9TVsSAnZWagAAVa4P/0ByN8M110BZKDjyh7OF\noiwyZkVVJOGl6RQj6QjWw32AMi0veSmtu0Lxj4HmOxsw3S0f9wyAfnCkiWX6\nl/GS1+kvAaU+thRByZiPWKBIGTV1O8OuVQQ7q/MVJJQRNoysowqFEW3R2l+l\nkJFRhRWDg+fakqkuUvT/WFLGZ1xJjkbZ8c+2oXFLtICvpqrVPf/edmnNhew4\niqOHOTfr/KSnqOICajarMks+JslF8cxxv00zRnLSLTCZLFPZJh2qd5vxn7Km\nQ7t16Z2LkOHepvuz3jsAVk9fbSx6Uf0AZN69CXe9HcVt3LOOBZd1T1UAUkYM\n21R+2i9irGD4m/oIKjKeKYVhrI1+Pe+lD3rM9fzW7wRkHxJjdfEGrU68+qM7\ncuJuFn+NFE2UDTV/plsJc7Gavkn/c6hMwajmeHdnry/tmLB0p8OTp0Nn+NKN\nq5xKc9rBkD4yWiTmx7rzHcQZT952U2dwm9QLG1idT8kRGR5bJL4/G90bKz4K\n3d6+QaZTAEH/DcFVwJh4+ul+JelWKS+QZx8Mjr/bXfc2ryVLc1qey9YRjxBK\n56BD1qVnzQW1MMvJOH6ERyrUzwiuxuhAGPrE/vfNX8e+4KWoMNQO6RlcfgkB\nKk6jueKZ0KIyUtP+AJIWQMvA5EJPOQTy8O3bQtnI5xvwNuTR2GUvOPKjtPeu\n5Bc5\r\n=26PQ\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCMblIHwGkwuutx6EQsn/LhMlD1ykzR+BRwsCHaYofAPwIhAJEeoZiKGL92BYD3W+Hj70PnshI300XeDRG+5i3cnZ7q"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.119523712.0_1563389256868_0.8292270128962027"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.119894509.3":{"name":"@litexa/apl","version":"0.1.7-nightly.119894509.3","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"e2494a7a9c781fb315c955d0e690913b3e613044","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.119894509.3","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-dbgBz5PMpm736vtkty2d86zUIX/u65eTvXpuH2g0TEfJy+NwIBK7fOljU6QsZDNfLhi/BqjHoRVIIAph+UXsiw==","shasum":"fb770c1b3fa591f5917aa1e17eb4ddc36f1ed57c","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.119894509.3.tgz","fileCount":29,"unpackedSize":119544,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdM2F3CRA9TVsSAnZWagAAV70P/ils2lUsIbTJGleXaTjx\nK1AMzm34apylkQc/yMi83aMJakgmBQv3eodGSVkDnZHKeYm305YkPssInMXz\n+2XFrydL/R9+eq3SEFXsObnq5xC+PSxRQre0qmRL9XYkRdGFBGraqIen9a88\navzK6X1SlvEbmsFJ2g6GfDHxGvBh0MrMLldphfOLByxVLNmc2CNxQwnBkXS8\nOnuam9ejGs3jFyOTlv4ZHNRErHSgGBMPPJCzoEN/JhqoadoUle9bRXsvI5+P\n4ZiR6HTuSdUOejqoncWMyfNCqoOoV0dZqrIZEFDjhpScwJV1bpadK1g5Lc6p\nzvWh4Kk6BGdIWZ5xsPNRprW0ieb/19dG06TGHO6RBefVYSf6zq4auM4Q4L1L\nq03s5Pomy159u5hsgCGpcgGiJK4SPmzj/rb/spsDVPpSzY41K1alpRntd53D\nViArvCikjE8GC8muJxlh+c0Uc9mpstDThcMC8YlezcWjAsrjktNpYSOq3sxX\nyJuK62D2YAxM2MTLmSmn2DhUPpkf/uYyjhTtfUMfNbJPgxqjwd0fGvv9B1SH\nWim9/zXLpYxhVXP482pOjiexJh5scs9ip8XoC82iq104FOYLF/0sKqrZheyX\n3ET/msVpLS3+AQRmWHCfCQLI1ejYqkPnRGEIqXJ6/jeNOfb4BAYvkg+QjiJ3\nULIp\r\n=7Kz1\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCICVfv3KxcuJByN51CzEE+T2IkHamBiHveVM6qYHqeccaAiEAlyJR+TTiG6P67qXUrfTtxpB1RjC/rdWMJseSt87B7k8="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.119894509.3_1563648374586_0.9386604373201495"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.119933063.3":{"name":"@litexa/apl","version":"0.1.7-nightly.119933063.3","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"e2494a7a9c781fb315c955d0e690913b3e613044","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.119933063.3","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-5WqyMwzEM89QMKdiG+X1OiPY6bsDtDNMQC4kJk3tux7JQPY1QLZ1FgdNm70qAoHxE1HSXc2UOCF52NXFCOUCBw==","shasum":"22f0ed27f2887700e10d1d6cb207cd464887257e","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.119933063.3.tgz","fileCount":29,"unpackedSize":119544,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdNLMtCRA9TVsSAnZWagAAMMIQAKRrzy+EE+vH/fXcHI48\nzH5AXPsCnfvHbP1M7K8Vqgw/+O35Xjs2qB5TmgLlewE7kn0rg2j91uCr0Xgk\n1UeJDvv5AqfbJu+NS8W23QR99IdPwSTXE2s0JuYhmwSscfP4JZALg6HhAbJv\njXKg2jIQUypHeePO7g2CQDCQHIoUSWZTcYdCtFi30Q9Kiu2prcNiD7gl6PK8\nQ/+vZuArk55RrF8DDb98TkF64BbESOIrpwjfVwztMPZUb6/MM2ETQehx7fex\nz863Lbl1gyWHlUw7RotFVONwypUBYdncd3dCWTwYDNumcXdLFhaKEdrBdF6z\nG/LKQkxWUq617jZFCgOt5qEluyJKKlwutGPlIxllOJNmr77YjzspO48R/bYt\nF6JCxdVMZHqns4XUy2+c4KsSLX37wO2pFVdDMJQANg++kEoY2/FNshPHJKrK\nhQOmft+OoLBxrFMLKt1Smttc2Xwq28Q9yJHp3bHY4/0wf8Ku5IAlFrN5LYiS\nNWxuSRy+t4GbxEIiBkABwCk3AWv9JI7vkbE5FeubOzUUTTEczetG5Qt27qkQ\ncF87lLCTTXjUxBuYOTyU1+5FuRZtbP/dq6J4Pm7KmlVGClWuz7eQxqoZaft5\nBfK+dzVrwargVh03sD0kSy7oQrJAs/gYjUHAHgHjwfCOgK4bP/Ej2hfLqcA7\nI5wf\r\n=9Ib5\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDeKfGNz+h6RIR/jkow+QYtAuYs8X/7EYz3EgEqnySfFAIhAJNYC9wQJblOQTLvjHIaFn6nKi5FB3WoJK2fHUu3Hfjr"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.119933063.3_1563734827683_0.5166627872940435"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.120058190.3":{"name":"@litexa/apl","version":"0.1.7-nightly.120058190.3","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"e2494a7a9c781fb315c955d0e690913b3e613044","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.120058190.3","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-B4PKKrHalnPkGcxsPLcrFvfc9v0Bq/k+Wd3tTeDgJK+oSWJk3T8/Sz+mVShydQ/JU91vGN2J5j+O36cTTt6Gyg==","shasum":"63dd0d604843391e48387ea2e4ec124f2b3ed460","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.120058190.3.tgz","fileCount":29,"unpackedSize":119544,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdNgUFCRA9TVsSAnZWagAAY14P/i71+op8I1lTa6dO51Zn\nkbedTtk3pRYIcwh9ChPt9lLwUTQj1e3RNrv8MVu00eg5G7co1hF+qFpi9WML\n4IVfGYSqMyBwGtGFLlLnA4mcGQonN38zoqHLTVD7bfm/Spjam6E1puKSIq1T\nRaKfWz6NJ8Js8jAMy9iUCXQCTc52JnmVz77pMjS0ZU2S336jCGYHfEvkImjW\nphCKmkAKmXNtUhTesqZ0VaixUiYb1zWcZQ4HvlBNIrDENrSzMeKVLA73cgcX\ncwiju/o6gPXkoVyYigObiLM1+IYJz6qZFKcZI5WTluYT0ZrD+vAf/EeGbmxS\nSi7cifZKkKNoAVFfZ4sVEEcrjCbAQcWfjw1EyH8tyeNLa1E4FlWAGPO+OHxw\nA8ct4/Rf8es44VOZplsCCybDAiZsTsR6n/EQUJrMCVCA3HWZ0xLFAJ4FoCeB\nKPu0r1Kf7NlQw+M+hF9QEZpxaaAYLgYDiLYR1+49N6Y0i74jRDM97jjPC2/h\n4NItJDunM0MrMZ2NF6tOAnrO51KaFckTicMfyiJFzGMhBzncgd0oQfNzQuun\n1hNUntkmkmoKZem/EcOgPQg9bZy7QgTNPopPAy35ebg9qTRhy9+feL7Hmt/k\n5xFKZMr2x268KPfTLKQCBYr0ah69IyEL0L6CNQBcKw3+zCRVWaiMfZFuEHur\nfC4z\r\n=DD7z\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDSv7uir/xUNUd1N/A19Q66MwRZ0x28f6Merr+tmOHtPQIhALEPHlITM7eCdCNNfmU760rKoxAJi9YTXaDjBv//pyJ6"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.120058190.3_1563821316883_0.37246732108609826"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.120260087.3":{"name":"@litexa/apl","version":"0.1.7-nightly.120260087.3","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"e2494a7a9c781fb315c955d0e690913b3e613044","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.120260087.3","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-OZnZnt2M74MxOrrpUGmS+7NuaDW4yFgXyf6mZI2CmntWpaUTSi48oqjJFJiv6SigPa6GdbTjRUpdX5Oj6pLSFQ==","shasum":"c962760854096682e84812562b94e53da516bee8","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.120260087.3.tgz","fileCount":29,"unpackedSize":119544,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdN1deCRA9TVsSAnZWagAA42sP/i0Hnbr595Vqn5LH/Cf8\nAHkebFNQGwPt06c6PXiZyIoNN1v5C1tPzYjCAhBqOuyuBaPDo9SJwHdFv+mI\n3e3gzbGfySbFeRDs0m0jDqSLMrw++lLJcKpiTWnhw/mmdXU2v8G1g0VobaQm\nb93ooq0X0F/PnYJ27pexmg2zEoAV/tL89gY0ErXTTtnIYIaYZvy0Agu14Bk1\nFS88+uVdd+PXJSMcuOE85q5eZhrOUSkkw6Umyl7q/lyYFnDmy2cutUQZAKS7\n/LFifa/mDuVRC7faxW1+ivYAoyTyyoLQAvoatY0P6iOiNMrUJzz5in8MKQLs\nLKxmaqA5ko5+HzU+i7w0cD7xd5N7ZI2YBl4cygMYv4IN3nYoocA3lpOLDt2l\nqHHZedTlsVXYJECMu0BSwnmqILJm3VRiJUaCsK5iltD6zRLAOgI988le0G6a\nGKugprJWl659G9wQ+uNIcCrdendiEscVAmPGcZ/v+KqKCT+POGWchu0TWWmn\nX7BiJ2xVqJxf9oP2Xh/UBOvAER5T1ZsU6CWa7CTLVzDfIqsYfyfAnIvXDcD8\nBf1PvW3GG/3ewCgED5GRtZU5SE94afj8+2hPH/6X10d5894EZlQZx7L4Ar7o\nuCLJGSsHo/vYbpHW9Qmtuf79pWAoophmkTm6uHzq6PYk0uzsgh2EP8fCHjoY\nvaRC\r\n=f4Ga\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIEsIEl5okl74bidKhgKpGuqtn1resBrqQV2z8Ty6E1tnAiBedvhpxO892ggUJqHNrHDHfRcRPDvpkzMoM5dVyHkm8w=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.120260087.3_1563907933308_0.8214153263354997"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.120755988.3":{"name":"@litexa/apl","version":"0.1.7-nightly.120755988.3","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"e2494a7a9c781fb315c955d0e690913b3e613044","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.120755988.3","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-l95Dv3XmKkscUhQ5gUERhDIqbR1z8V86YR6E1AdOldKXDIJ/Il3DWExlnLUSxS6tbBdGxD/AYvvacu2YKxRw7A==","shasum":"263e02e025d5f43a742a99771e06fda4b635c69c","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.120755988.3.tgz","fileCount":29,"unpackedSize":119544,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdOfpuCRA9TVsSAnZWagAA+noP/i/rRuxtJGvoMj0P5zqz\nuV/YiiyosCzb1ptllTmym1tFem8CYPx0Ml5FNULSRqLqrmRclJdowVrN11Qw\nUeCAsCBJhsgFzFoxpxkpsrOCYtsUu6XkMuETIZ5LrBD9ibHcXQ0KG9+RPX7r\nGFkpF2lDRrsDh+uYZ/Up4o6NuQB5PCGIYDgPl75e7Bym5uzZtp7KtuiezxDO\nWu4zD+K11jE+NeDJjxTee7sijHq9wKz72p3o5e3yACAJxv3TrFDFqwCIjeg5\nSe1QGhpoPwwpkTShMqqnBDDQPcrPmbhAGT3HhQtKnQNhvdF2FwMKkbwc2pWj\nfM6KrwJQlM3wjGtlDGiz93bjPYKnK7I7L2grgpnbNpC6AeX/TP6+D0TNnzBL\nyqd3HlTCM8cZWDmdAuKazJVHyGb/NBro8WHL8Nb7yqxuXKA+flqGos+GbKhE\nPNYAP04vLO9Bn3zLuWBZGVrkivMkLi1zQksmFO1Gg7SP1c/lcfsx0Ulej2YB\nslK/+7oJVf7JgVs9h5K0nRzZLxjXUlFCKiei5TgOPBIVdU50G8Qm4CgxZVhn\nqf8rwjrqnz1Uv3RElOm8PYPKv7Sk3eiq1y7exw1hx/cN4p+7bnG6DFcJPEiI\nuPhCuLDanhkKWfl7Be0+wJyAw3esduKaRMikPuC7Y6SAoxLPOX3YjxlybJDL\ncycz\r\n=YBMv\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQD3hBFwKqGkrpPI894YPUo152OYdyP9eOqjG77f0NiDygIgbxayxnsAHXS+H0ChBiaigbF99mdcL07U9i/QYuryDi0="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.120755988.3_1564080749643_0.024319974425561774"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.120897975.3":{"name":"@litexa/apl","version":"0.1.7-nightly.120897975.3","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"e2494a7a9c781fb315c955d0e690913b3e613044","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.120897975.3","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-gZQgqoF9sWlfFuX746qQompjRUqKXdUrTirMGtI0Fp7LLfs2hnm3VT2VXSlbwRqGYYB0OJpys8e0tJzL9J6Srw==","shasum":"ec298fb9ff3b8f19c7bc2336a665741ba07f556b","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.120897975.3.tgz","fileCount":29,"unpackedSize":119544,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdO0t5CRA9TVsSAnZWagAAUpUP/j+7jhNlv34rRcd6c5dx\ng2/AdS0FI4hHDy97bO3FAjra293Pb4PT02U5xGKgoxF9Q+egk86MGe3PCczy\nm1Vj1yWJnIP1CSENS3HjfLFVylffQwYGcxzwkFalSPEZqmxY/OndBsdYIX/a\nsWwJDkQEQu+pBhrahOes87S1QfwjxCd87Ka4KtbmmJBrT2np3Yz8BjiriHmr\nLBYYX4fUq0YZWXjrTpArBj0Q3uwcXxIUhjb5mQcMX//BqduSHvJbhmBZ+lLj\n3PTMvkv0qot26CGnKhPMzbKGjAu/QFXeJBpZNu1Z9/zqi4k9hOu7YL1mU/Zl\nUikrDN7eGUFzjSqditWUPraI4XwKg4JsW3Dmu86xvu5vV3Bj0Myw2IRahViG\nGlchorkIkdz1Hm6tO7VOcX0EKotNR1oFc5E02EBNqYhGlytz5syV8SfdGmxu\nv1HUnSwpYTbNs/oVx/HDgCuwwH3EQewDorryPWkhfSWkmWngyaWnZJOOyT0L\n+HbHjWTG+MyRd/DjIqoQr3wqsTZowKSRw1DmQd7H4V5mVRzDVSpoAETWQz+s\n+y6ln11NIV0CVQFGURbgsTsseabQz/kIDJeA2Y6gbxnkXmwZppPuGIWD65m4\nVXb0cNIqOcPc3EyORFU/w2CkNlU5o4tpp0xqtKk0DlE+6kxiQwJU9j4VKBl+\nmQrh\r\n=Lm35\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIB59JkeiZN9Ruyilgqc9rG6W/MrdwcP+TKS4D+8H0XJ+AiEAnH0DLBda4e7MKfIeksljFQkazyHu7eTQjkK/6xa9514="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.120897975.3_1564167032912_0.39375898604815407"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.120951880.3":{"name":"@litexa/apl","version":"0.1.7-nightly.120951880.3","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"e2494a7a9c781fb315c955d0e690913b3e613044","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.120951880.3","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-T1Na06oi6ekxXAVBgsK5H2sMgpfEkJX3ObPm9tWAWH/TV9/HfUD98S9ENnM6MHSp+Q9ceB19MfMAfnu6RjTDBA==","shasum":"649c31744820ba1e3e3c52524d1f7797badaf10b","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.120951880.3.tgz","fileCount":29,"unpackedSize":119544,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdPJzwCRA9TVsSAnZWagAAYpoQAJk8U4vknbCEEPu9luPw\n5y+wIMqPcIoCM6RN/muOK/3Yl21MnyEZKD45cX6Ss6rwaXg8wtU1cDyH/Z+m\nqL/E9B+G0YkV5jzB8g6qt2C5k1tbqm4cL1GBNTyFi3KTNnpJ5RAVCWzSovZl\nYQcCzhJZvF2mvfpTMVUrwPBFyHZ9ZO0Yx8vVtF2e1FCfDSwjqKW1XbkOmkKq\n6ddsokH4oc+2IRbriQkQ5BDXat6fiYvlBsSP6+p4wwdKpsDpjYl/jvKBpYEc\no8WWigTIxwJogTx3oTAdq1GAr85N3Zpp6ASFJR5LPix/gY0+ZzVZtifGkPMX\nlSCPUT7aNrylcmr7WU4FIyqb5AarNXRDxV5iJJlOARS6iH0jhW04c4GwBvpi\nqovB3w33bxQl9ZGJgCMy0KCHBEcnteBTxY3mhjXv51zkAw0zjn+0o4jMfs/0\nrB6spH7ayq37n6PRdNqhf8MwZ9mKeeGGO7Y5NyKdZj3FnrXvlbbYF+ELsf9F\nbDvOdqT74XMA6dZnuMEa4ALMukjFS4lEh3qslFocwMF4LBgVT89ID5ibxB9Y\naAKThznmz6qcy46cRbzu8BAyFRonPJWYS9sxd6xClCAcgrMI3fIBOvS61IIW\nx+Zd5LUEZsXDWJDFacc+NQqQwRk2gba0Q7Az7He5BM4XO3IcxRe2yj3scQ0+\nwe5A\r\n=tixF\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIF6aFwkq+soPNU/27UZBPkEf4zv/0e/7YveqmAi+j+GIAiEA+mgksQPvgVaVGSxUgf1BU01UH5ocHQ7A+ns2KNz4bBA="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.120951880.3_1564253423558_0.7880680633394404"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.120985351.3":{"name":"@litexa/apl","version":"0.1.7-nightly.120985351.3","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"e2494a7a9c781fb315c955d0e690913b3e613044","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.120985351.3","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-V4G0zt4KYgx0xzRnVcvDKkt6W59HCuyLoy3/sKbTJyDBM8sB55Z9jBwzHbSDmALmJn+rJLtSObk1hQya+KJs8Q==","shasum":"6919bd50b4e73cce00f2020db771b1571f18ce35","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.120985351.3.tgz","fileCount":29,"unpackedSize":119544,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdPe5zCRA9TVsSAnZWagAAdi4P/imRtx1Yikc1NhC615mr\nS1t415ZWu+CRAHaa/2rWhdKiRz9ZuAxH32BVtJhIsfXrzzx0ObNDuHoRLaUd\nHJ2bKJzYE53HZ1l2EHJxCUW1rutk8atKtBiqH4mB65Q9urEdnt/VKsGeah7E\nqChsaQ6hMlcXhSOWpMdALk9ktXF8funSK8ZgpqYdQoSrELao5pZ5vIJ+7NWH\n8fo7CgPuWjh5QxFwkoWlieNeGPO+coAOfz28SPZW4H8CKPMERdw9c6y8eYio\nN3p92Sm1pesV9MwqgFCjsNjy2ofXqZUt738mJ9HPH+A26/osZ86HmbH9zQGD\njrKJd9/nglaRJwVKedCB0rubbH+7SEhQwm481uihBNXkAVJoQ9y993pWcJ0p\nxgx5f+HukA/N36HJOmq619LHVC5s/o1FyFD9ZemPAcpxoGXaZRuFcs6+Ew1Y\ntu9UxRugDm14Q1PElqHgzIepP2CL5xxsjHjgBRWCS6MwxfogPqFJxCZGnOoB\nyG3I3jLnxH4GQBjRDxf9HydycON6fu6s6esPBQFHD7z/15gEqYwTCjNsMwJI\njrSf7UjySJ0K6WPOA3yQoDdYO7zxE9hhg+KFThmt2FwnzX9O3bVXAaX6bgTj\n1YXMEYvV/bvYLT76yTCrCzhfSoNp/ET1ClNdvpzxZB2irObizKQ92WGoLeAH\nvp1r\r\n=brzu\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCWCXpGnvdxXKLvk5NAywvBz3V8YwHfbbfYGIBfEAUcsAIhANV6xjA7omTC2jt3y+R9EKQVFTLZfTEDCkbEEjTZKRQ6"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.120985351.3_1564339826280_0.2703387708258793"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.121138444.4":{"name":"@litexa/apl","version":"0.1.7-nightly.121138444.4","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"df4f2ad1f4acc6fbbc28ba28dc4a4aaec7b9c01e","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.121138444.4","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-nPNdg51/m8Qc5R2DpOJCMpSHNmw5YyauB63i4y2deg9WH7XcHxdgpPCNqgHz1qdecEvGcMmCQvIizJXk6Z4opA==","shasum":"91bbbfe894201ad67827427e8881696c6d607b54","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.121138444.4.tgz","fileCount":29,"unpackedSize":119489,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdP0BPCRA9TVsSAnZWagAAPoAQAIae1OO7rylFmj3fJppI\nei5te27Pa/ebNyXAbJjXJkh7UHeAnzfy0YEo9qq3P9a1gwoVWykCzaVgMpFN\nOuqyPFvWewrR67q4O8c9i1W43B1MgbriLRCzS9W/wjTGzgEAAo/dph7N2S0+\nFna5DHSfsFt8V9Fz5LO+/cJ5wSaQSs9HGnCSaHb8/W14C8HgIfMj3C9R/OI/\nILd8zGQvRPbMguB5ehdhtDw+jjpq9mwxp/lsaTxBeCgeXSGyUQPRyJstkuqi\ntrfeUXbSfv2+PUVaB5kTIqOYbiHLZhfwtLuchibIXRHmgwV9OKwaeN9jrQw9\ng7GmS8wBZDZ6/BHdyRi5yesSplcCdvkGAwQw+x/WH5t8EiHUs274QpU3Cf8s\nyrDhW4LMyyD5+I125oM3nWyoPFl6vraiFWOsStwJh2HRRbli3OA6459HVXpc\nb3J47l/e1nHkC3XunwN3uvKCK4uHdp9Lo9gisrmL4Bn6zS4iFjb67K/sgPyJ\nM1H18nn2rivDFXZHGaoISjCT2fI2G3eUelUbGi3dH/fTMmhj/TT+SJ94dG9l\n4yi66Gf3ozkDWsI5+YQRQUtv8WIOdR0Y4/7J1178fWb8Nvkwdf2LDKpKF1hC\nUYycgCm63AaE8HSXh4B0Zl9Bg7PoqSN3D76Lf+w2YSN5Om49DWCEszw3JDKf\nNfJG\r\n=P5z6\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDfBAzocTBIHTf3Kk4E3Cvc10n0rr+ox9oUtohVdJxx8QIgWyx/o4hHKLdMXXNbO+t6d2+JxoU54SSPuzrj/xsJg8I="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.121138444.4_1564426318240_0.2884741593237312"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.121301407.4":{"name":"@litexa/apl","version":"0.1.7-nightly.121301407.4","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"df4f2ad1f4acc6fbbc28ba28dc4a4aaec7b9c01e","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.121301407.4","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-DLpp30hEsrW3j5Ngq9X4kS9+tLHaPtV1zdjIIPNn6fHaio0jOe8Btnt2fxy3V7I42kNadDaWqD7N74ft40nyDQ==","shasum":"1712a31012d788c5682c3af6796be474ae0f0b1c","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.121301407.4.tgz","fileCount":29,"unpackedSize":119489,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdQJHXCRA9TVsSAnZWagAAgsgP/3yaXH3+yhcNPmeYEncu\n8SAv8rUSzxJDyyWp02KbOdBa1gMlqQCBDvlhl5GnoFUTqMIZA7WoCMg8BmHi\nfCd8kMINXPFrInrlr0jLd27+FqaQXhd6Ago3qQrBHgX3F2fipc/z4ralNLki\n6h7YE0bEipuA47d9hGjwXspL/fX8tO61o5stxsxD9wZXUMuljRYLbvu3p6u1\nVOxMPc7HLbyST6shlchdv5YcrRf6XQO/+gVZBge3XBLH6iHHQpoVpwoVXM1W\nQajTru8KePzUWhB6FhVyX2Qz5JPMUkzvBPqZ+qCAa8ENScDGjeoRPcTha+mx\nLELlEOYjxdo9jqIPv4v3S/TQG6Ef7W5GZu1W6L1+H74vR2KMbqCOitG1UGuQ\njE/W4Z/uSXeq53h95IE8CQFwcW78hyvwTyN8CKUPtqRNIDUBdy8gOrsAWi/Z\nC8UXfUwL5QpBVQEzzm5Sgjjpk5Oy9K/+atcpfIfABO8O+TfYoUZa6YtcvzHS\nmYQN2RlRSV/crVB+P/QdPKCjUisti3nou8WGD4uC/ME4u62u9DCwecny1wZY\nltvj2jQCByH6J+kSM6DmgxMOffUjdjqtO1Dk0XZJUbuJjUlQtFp7eGzeAoP5\nVB7piJglti25/hItWQCys2ftUP47Y8qyxKRXerJqdvYggSgB3SLdG3kNnsmG\n2vvU\r\n=YitR\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQD1adD06yqnTMNvag1psYvp82yz7Gv2wQPK8Hk2tWnR6QIgb9Gumw7r6tCfD91NQDrMaZgTTxDFdbukFe+5lwDD1oI="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.121301407.4_1564512726889_0.20002163310931964"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.121465221.4":{"name":"@litexa/apl","version":"0.1.7-nightly.121465221.4","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"df4f2ad1f4acc6fbbc28ba28dc4a4aaec7b9c01e","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.121465221.4","_nodeVersion":"10.16.0","_npmVersion":"lerna/3.13.1/node@v10.16.0+x64 (linux)","dist":{"integrity":"sha512-MmtzF9Uw+dRBrUBRFD9szjrt2n1aGjo8NtU2ZIgn+CYTe/WJCEVGNO+DstXhx+l0FmzgHjzTRnwahP6nHvVDHQ==","shasum":"ec201a2e72a0d2093203380726a3fe88f5c73680","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.121465221.4.tgz","fileCount":29,"unpackedSize":119489,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdQeNLCRA9TVsSAnZWagAAd8UQAJoMmptKzLb6qmXZJL3t\nCjGHWs0kPH22SBOkZlA7LohgszfBIjQuQQOu5vp0Sc/w2JBqtI3zCEai8sTf\nMzHrkGFeA/4TnIphNAqgmkYQiQFc3iW1fJqib2YVOC5pkGqANoItpGvEwTwB\nSHNhI9CzoJKTKveqcNvKA8QoH5lXvDGWUuiARTjPEUMfPcr/IE81YXln0a66\nspPR0tMF6GYoUF9uCWqlg8uGPPdGYKzkG957CAcHPM/xe4HHVFnWUSM4+GKz\nDyonD4kNMW2su/2a/rWMqsvZ+F5fZEP4wv4YJyhoTq+4Oi9UqFt69pFMoZvo\nq5PXWd0I7mj1SgOy9t9vscHwqBEL51FIQvCJsx5HqdMZ1YpFWBOntgP8kWm8\nK/RIOGrqqMNCNHjjmF7mgQcVLG7n7biZuqePwq/ztUhtaAOigUPOK8KhWABG\nEEZjXMnVpoozSmmR2np4u5JX541kTuBx7Bi/agaiM0nC8AiPWEBUOpFBMRPx\noFi/fhQsKhhdXzOWjBVFskjv/JOJLsPDR+kqFHQ3orjfQpJxnf5eHfX2ZepY\nV1vVavjqyxqS3+HPedfHReckZP+OHdf0M7D1p0TBAWJTP6Pcu/b9FiAD0QrY\nsCQK72P0P4amiF9hndjLmvoBvqkSpAZOsngVqKXfaEHew5glQOeBvWQ2s/OI\nGCbU\r\n=MTCV\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIChwmTPHLr5iHeL/vkn1pfHsSYn54xYOPOocJJuD+brXAiEA/KkbMZfwSt1NU5ySmt94x8Q7w0jxJyXttEt9xu0PVXQ="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.121465221.4_1564599114314_0.331966625098129"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.121654298.4":{"name":"@litexa/apl","version":"0.1.7-nightly.121654298.4","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"df4f2ad1f4acc6fbbc28ba28dc4a4aaec7b9c01e","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.121654298.4","_nodeVersion":"10.16.1","_npmVersion":"lerna/3.13.1/node@v10.16.1+x64 (linux)","dist":{"integrity":"sha512-/LJmW1hk/7DhHt0ApghK0lQ0f4yMTwfZswuYLO/xreFWhYmJpOOVyorJXPkekKMMu/un8h0gAxkxElvkvYX8gg==","shasum":"f5a425dacfd50359fd14866a884d8148d25efe6a","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.121654298.4.tgz","fileCount":29,"unpackedSize":119489,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdQzTnCRA9TVsSAnZWagAAdeQP/2xKkpsP6jtpQWnH0wI7\nP4dS48aotkKlNbFftaRDv1xeMvy0RfDGlMKrkzQyjEr1S6IzMMTwJy8uQ6b5\nr1cwvab15ESMdJSXW+8Mb2QVoRB2rbejn4fP6avQdt380Zjq3hNJdtJWyDW9\ncOJEA0K0qNjgffusZzY2pNugi2UNllkarV+miTfFImfihZQd3YMU0VXu9joZ\nsrxgjcwqHWZ4wKJrzYZR+qaekPkz2FuHJE8CriVSHpubYHoy9w4PiwVk56Kv\nua3uMmiC3FfxnM4ttCs/hbapjKODM83W5ysvA0v8yNwJeye8N1axaP2Yw4/d\nxt/su5Ek415mVGJUeohZhfBBKSiFcGn1xbQZEXk3b+tRX1VhQHFXkkoM4mej\nymbNsYphZQvnEaovJyDNwTYWoNZP0ABYpQFGkb466rN9HdJqWhz7uOLVBK1I\nE3wTjUu/cUPaLCqTsVzmEFFQFKuD7Vvm9/R9ODxIv/PJbMX6LcpJ0VdkwFLb\n90kjZCHWyoHPBnS2NfLtyFkgafjOdRHaveVGMwr8eA70Exz9cXQqZKHHg5G6\n7ec0LOBrNwqbfiWss9gTiH03xD0xBMoHlmFkNEhyjFo2cvfU5No7qQO0sP9b\n0QyHwLQXlH1H5hfz3S7my9ZIZk14fJ18dgzZWvFf2JI8YaIEmtP5Jbinzrwo\nBAhE\r\n=B738\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCTKGo7CBv7bFc2geEpyZUGAKmxRyUs5X7WoXNlm45YCAIgL03o3nOx1XvKRl4WjJYPSQSapJZioBBvHtl/+itqmsk="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.121654298.4_1564685542461_0.4311439480504844"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.121796953.4":{"name":"@litexa/apl","version":"0.1.7-nightly.121796953.4","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"df4f2ad1f4acc6fbbc28ba28dc4a4aaec7b9c01e","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.121796953.4","_nodeVersion":"10.16.1","_npmVersion":"lerna/3.13.1/node@v10.16.1+x64 (linux)","dist":{"integrity":"sha512-Iae8YrwmpKzCYJN8/cbk25KfdS2V0ltm+4jcl3bGf1dALKkRW51NayVtvhmcGMJN/DMg9I1yMoedTcmBX7P3kw==","shasum":"76e8b260db7dd5ccda0959015e7f3ce0c17946f6","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.121796953.4.tgz","fileCount":29,"unpackedSize":119489,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdRIctCRA9TVsSAnZWagAACLoP/1rr0tlhw/hskBh58G9p\nxU7LNFOPU3CdhajRCXkpc1ngrLDE9P6H3t1YYpEBqVm8M16BhWQkgfJCGA16\nXVhwSFh3kDbMmFnMGq3NQh3I4/U1dQZM59VW3IN7EakJufm5HUiq0uKWTkar\nku2amEKf1b/710THX9RlI6zmkxWM0eqrNYNW2tssnhysJEqEeK9CJHcoSRcR\nQp8lytBfNhcuxoFib3YI/43i4kDjLQhSi7cquQESqV0C4PSnjR/Nw0yY3zJX\n92LCe84tmKNifHsTBCjbqqslqUFCDxOvSsEfSfqEhwiVKAwOI1f8C897uQcn\n6/jDHKnr5YRwR6PqtDXEtfFePkrlrKIJS7Yqnj8mtE1TacMgYlsqfPauBeTn\nQfRQpmBM2aw0Mcuu5bQxYyK259AVXuL6pOwrswjbXw2Ql6thXhAec0jmbQhl\nQoKE55V4T/5+R1YA5FAIMWgZw4dQgpN3owD+zLe8CX6fcoMjV9lKCkp0kZTI\nD2A1PPr5vaCL1+Bs9O7G6dvy5ffUOnj8ImYlMr35m+mE/Kv703uSerlQCoYF\n4zU2GpVbloVAfIvChoB5aed4MxZskzEynDSlZxf+esoY4OmQUU8IhjYFjxzZ\nobWY7rQ3T911md+q4aP/3fkAoEEf3Roj+8KP+tK5Ypywts9ubRT0QVZYV7Na\ngPd5\r\n=nygC\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCICQEvdsmI7gQEJmhXSmkIIgJOWQ3pRIWvNTjc3XNWkXgAiA7Hy/aGqADBy8DzuKiGa0hUiqKlSCG9ZMU0c15hblxww=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.121796953.4_1564772140894_0.09958635446861552"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.121850486.4":{"name":"@litexa/apl","version":"0.1.7-nightly.121850486.4","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"df4f2ad1f4acc6fbbc28ba28dc4a4aaec7b9c01e","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.121850486.4","_nodeVersion":"10.16.1","_npmVersion":"lerna/3.13.1/node@v10.16.1+x64 (linux)","dist":{"integrity":"sha512-WXycPkpeh7AOSLW1WTAUNCPg0/9RMzfB3/0Z6iYzyOlKUDnzEtVLMKhxJs3zRnxPibmawzVsg1agaMTbF6JrYQ==","shasum":"85e005480a60ca4ead0799a309ec51cf5b6058e2","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.121850486.4.tgz","fileCount":29,"unpackedSize":119489,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdRdiJCRA9TVsSAnZWagAAxygP/A7wp6JzTIntoIaeiXRp\nVvEfTFrB4egSjqllXZelrgPd7VRcfG9fRTLrR2zEqTLunyetNlZJUwD/zXUd\n1E+WxJPrUq3+KTEAuGHnd3WDCzsZQBG+dC3q02dATJEUac4NAOQcKZwuRYRL\nSOSj+Vu5iRXGfuzQL4iEBBK8uyIu6JjyGNSoepOwBGYljhIwhjt2YfEobfM8\nUdnoW8Yc1rgMMuEj5etRiFuQGJBH+NUaBGcgwxviEv2H0jTr6uf/Pw4yl/ts\nP3fECELiMft+2fukTwscjLdk+qtWnlzjyXAS05gkPrqq6PWSt4wJUEjBAvSe\n6iQ/BG3+PZQz4JriY64EtTcbMxWvxFpdYGmiSnamF8Sao3+jJoWkMvEko7ZU\ngzzuojF1t/4RfM3x/iZ3AzYnW9nhSBNNEFzImJ6NTWOoPVbjgxgx5Er6NX6C\neQUGOfR7sDmfWFmRP7kIhTkbr8MN5+lMCSc88QNyGh3PQEnpVXTrw4FlBaGK\n4jy3QTO41EkBpUx4rCTHGkjCMKz6I101JmvS6tQ7y6ROwDwAedp1BkauF+BX\ntiK2R3v3V7fAWiGeUqbOLaqW3mnrmD2RRdrzX6i8BCf2NA/XK1iWOOMBJ4PJ\nPrf5bd0RmG6jjgLFVqyvyiV8kh6gXM+gPfQeFYcoxtQXSDEqKn7sA9V+Rela\np4wK\r\n=4zgU\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDnjM039iWvv6QO8JUSeBsSaTnAbGJBapSvMO/C8RbgxAiEAuO3hi/cs/ZPkTR5wlYAgpSxzBAqcE/aif75proaVgBc="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.121850486.4_1564858504811_0.004236313864975694"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.121882823.4":{"name":"@litexa/apl","version":"0.1.7-nightly.121882823.4","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"df4f2ad1f4acc6fbbc28ba28dc4a4aaec7b9c01e","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.121882823.4","_nodeVersion":"10.16.1","_npmVersion":"lerna/3.13.1/node@v10.16.1+x64 (linux)","dist":{"integrity":"sha512-2ZQpbrnszKy4wa0YWnFT9JCm3WneR63BoRPwuQBsCVZeAoAetJEU00PA27pXFN17KN2wz+5OArjk9fef2KfEbw==","shasum":"2c24cd448f331d88260d65d236d1a085787299f9","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.121882823.4.tgz","fileCount":29,"unpackedSize":119489,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdRyo0CRA9TVsSAnZWagAAVi4P/AyBXEmUXy/RyTIwRBto\nDYwVUWo8igrVJ7TTDtjf41KiPkMMJp3Ncimk7UfyZRR2KGIDwYGNGVu/BBFS\nrC/twHcl9pR3nfCzFcOE6Dt4ZtbacCiKwzdVjeTxOIISYdUCKbsnCGSuVCuT\nwu2IPfMUwUBOjA6jukWeptLnJ/STgjaxdX6qlw+mlzu7usZ+OIriLHkn5OGX\nClwBBvf3ZXdPoV2GmNuqkPMR9uGfQuwvX9+ZPLqtupMa7U91QpgWy3nxsJW1\njA1w/jUy9JK6JKrdQGtKE8xL55KO0NbMmDxR6j8JiL5FxGsNuyu4+RowYxet\n5GgbonxXNGyAsyAzmg/v2+VpluwqZE9rUwml9i04oMcqHh6SwnS0iwnx7Bdm\nTGOkDcbxa2UnHJ9PQIE01yWDbZgG0u8PMqTIN5XrptJh6CxGyaV1Oen5W147\nh/F0IzQswku+FbS/gxkDlMzugpal1qiNIrxz1t8SNohb81itPUfpjBoT3LO7\nqtQQhybDJGChBR9uQCZ5TaYCICDJr+BLmoKxxDAsyQ2Zf/n8mOxHUwx/IccP\nanmqVc8wq53I7NIv1hDrM0hIJ3JHpcmooPaKka5STdfZHJxkeTrLK0+FafU0\nadPyMWgmUTmqKYvMJQDNoVywEW0I5wk0dF/Kn0eHKWEOUyIFjOkjbaOYYUmm\nt7yp\r\n=PSj2\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDboJ4sgbkfWAS9j2u0RxEUpzIY4Y/Tj3LtFTbpLFvC0gIgdbQvdBPALW9NIzCJuzm/QVRQk526wyXJxRoOF1zovfA="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.121882823.4_1564944947936_0.17164181842490667"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.122004222.4":{"name":"@litexa/apl","version":"0.1.7-nightly.122004222.4","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"df4f2ad1f4acc6fbbc28ba28dc4a4aaec7b9c01e","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.122004222.4","_nodeVersion":"10.16.1","_npmVersion":"lerna/3.13.1/node@v10.16.1+x64 (linux)","dist":{"integrity":"sha512-omoz41+K8sK1r+5fj0egaP8/cTTFxRGqSuBI2Ia3vhd9pG535Jz0lPk6YWEtQYHO910SQ75g20Qju94/CnKK8g==","shasum":"facbea63e184f3a3b8e2bbba358920bbbd0cba50","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.122004222.4.tgz","fileCount":29,"unpackedSize":119489,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdSITsCRA9TVsSAnZWagAASxcP/RuzMBuPbEh1fWkGhIQN\nXW3HcivPIjO+OxWeYuH+OEV7n7xhy7soUdWqx6EEEMFW93pYA7pXMB/T8PaO\n2aHeh+gizGIqLhLCY4p2X5uDo6FiQv1VqmqR4wyqQmSSbEyfp2hWq4t44TRb\nSP1t/n9FAw6lmOpjyLuHrtodLR8e2Qdayvt7fThk3U8EBrRWANgv0kRlnvO2\nBKAb6NTfNJB7V/vf5uttEeigeEcrG0X1Ep0rksue4cJYGGA8ItYNfh94fwU/\npZxiMPSBPrkRB/QX7URxlp3vDVG0QXPE92ymvtLtaFG8DC9DOjv6DsszdFTU\nX2bxhSgmZ197K2Lncl+fZjJPKDiaQeCKrE8AFf6eUx7+XD2/k3JAjFnTRaSY\nPpM3NPKZhxKUIyWJJpn5E7GOg/+BHAO6Kn1dflreHo3fXWfW6bCMLax3OBbM\nBRaIqvo70xMPl29NOgWKcnGbJdmICWDQ6rP2/odGHXUIDcUW+ZfnCuqAgmE7\naNqV8bpL/JLSbVLIQW8cq7ZZ8NyMmoZhdXSGmoemWZQtk5XTXWWOjEZLrf9r\nMDkI0848Demuu1ZSyGZZCLPRFUFFNO3WRrl9mCF3sx1Q5wtXbuuzV30B3KO+\nHUkphcXdaCvDEAUKqWqst+eRrWvOhX9oWoyDU8zr87VNuJygzYPIPtRJzEem\nNgxZ\r\n=wMP7\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDJV1TfQ2j7RUProftjqY7KmsaaWrdDotcfRUC6aYf1rgIhAL972xS6S3O5QlYU/mGXfo70TFuNFdh9YSq6qWIYIEee"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.122004222.4_1565033707693_0.24781522772194542"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.122490147.7":{"name":"@litexa/apl","version":"0.1.7-nightly.122490147.7","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"071f4a185aa32f4866b4b68a3eb0ed914418865b","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.122490147.7","_nodeVersion":"10.16.2","_npmVersion":"lerna/3.13.1/node@v10.16.2+x64 (linux)","dist":{"integrity":"sha512-Pn/1gYpE2Wb03HNwwZxdbcEfm/n6ARKpMK7ZVtFQl5GVj9l65xC1LybEQ7AHHqzAyBhgtXPoYrkYWTNlBmnLuA==","shasum":"0eb19ecb5a53dbf4ec2678aa08fdd0cdc942cee6","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.122490147.7.tgz","fileCount":29,"unpackedSize":119529,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdTHBQCRA9TVsSAnZWagAA3DgP/iTnu8ug5ordx8ex92Mg\ncJWOkGtdHMTaR8szIf3YFYSNOQHks5MJpm29pmDsIoVUWKDFluSc88RA9K+X\nv6N8U/AS2FwRsLdJgpty0fQMqf6sghs48Imac+cNJX0TG4ts6aHlCV+D/alG\ngrnBemDmaJJ2rQqTSV4Xq91qOIYU46DOst1Twl/w9O06t5vXuSH8pgzkcBlv\nmdqDBg0EavPZYAvWdVyEZYPvWNK/27xC7yNvhi8p3uJjXxK9b6zcm8rCylAf\n+ZAemGgrtNtgn/zzsT3ATsQsd/x4aexlP+EgQRKtgAyEBJQyPf8OqEmUONGq\nytCqbeOmB4crFKGtsYaG5+a7aP6W5WG2S1jsWMHUmH6EKFlm1zZemf56TrsZ\nsB5E5Et2gv2GLexW2yDbtyKTMiauOGx4eZpDy7W766Yaibw7UfjA1N6TLIYP\nFmYp/BVkvUroQw1u2wuCQiEEdSx6gn0pxtVfgW1sXw4ur6QYsFcdde9lcOGt\n8gvBNSkc5D1O+XEDNdNnkctV25LwVYTsXZ+O5fw3z6/gYFMZ2sndH0LwVZDS\nR2Cfqfh69jqclFWycGycLTryzZMNHdBi2RES4TdK5U+9vRW3XhEwdoWsFRgB\nCPpP6c7r5yv3jPaZYHxxE9WIvfICg/rAe69I0jfVUeckRcC0nB/36ekeSLzs\npelu\r\n=B0hJ\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIGz18Z1BqfSxXz/JWJxnGA3xB6CkFOtcElqvrEjCi+e7AiBH0VWKTetDfLrrdlHyfh4PCeGWVnoBS+8ts8a+v0K+oA=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.122490147.7_1565290575135_0.9690382586722033"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.122635955.7":{"name":"@litexa/apl","version":"0.1.7-nightly.122635955.7","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"071f4a185aa32f4866b4b68a3eb0ed914418865b","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.122635955.7","_nodeVersion":"10.16.2","_npmVersion":"lerna/3.13.1/node@v10.16.2+x64 (linux)","dist":{"integrity":"sha512-/6hxeqK4sxAkVtRgOf+DQMD/6dDmunWUTGVw9NjArQ/rkXqS7PRg9Zv0kn0DTheoDv94a4/tJkFwa4CeNddrhQ==","shasum":"ad0d1ed5a9feee6f595830f6e77fd1f49238d475","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.122635955.7.tgz","fileCount":29,"unpackedSize":119529,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdTcHICRA9TVsSAnZWagAAkScP/1itCAe9+kG7Iv+gvDC9\n55h6c5GWhbTykX9xPndsMzA+QWx6vxDSdg9TwK2u28pSxcl0x0rBW8Ps/lk0\nFCMV6YyZ8+jVH1rhZCnb04p2uR5f2EMMX8wJxYHavlojcB1DWmuH+mJJwAoV\nd0SB0cRMszq4f38qzYwGUPbwdQlrRplrq/DzIejCTiUEP0WgDXReVaMkU1BM\n95RYl47yMywTrjzjSM/AJTrWPI5ewzO1qfHrrXadvzex/Y+cr6uVUtfKDeKw\nFOk9/YKw5nQO57z16+wD/8Bd/zBLqSyJL/tgr1pw9Iw0xOFwEMB9/h9M+wqP\npZtGMxdmG5ACbb4dxmSb1/GcDo1DTBjUKfgs6paOJlTLxx+jp+dyxtApL57v\n/2bhL+jOy3LfUTVntlJ1ixj5RShT39vdMHM1/CHj8zPUtc+9xqyEj5beN5NY\nX63ZvoMOCrCdGr/o5Vc5YGBW5WPw9gSO1te2/4f0P0MI4xXDCOc22FFCZQS4\nYnd5lZUyBbFtdF4k3vT6FdfTcM3TTokMxHzgpVCGgtwzgE2cThkNXwj0fkM4\nApMKXTeuAzolp/jppL/trHE5GGOYeOAoS/+YdOf+n0ajP2lUM91JsndATHb5\nInJPSDIU2WHfJ4Fdjp2pGWk5xEe2MBi+R3/g6tisAXR9X/dEdZNBdO6fW5mj\ntfr6\r\n=W2qQ\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCfYUgiPzg98WeeRyabxvtqIeKDcy8+wwA1043c3LmKcAIgFQYjbMplicyy+ahOnIPI1XyAQ8h6mAMAhocPm0JKnyM="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.122635955.7_1565376967431_0.7739999840279139"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.122691933.7":{"name":"@litexa/apl","version":"0.1.7-nightly.122691933.7","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"071f4a185aa32f4866b4b68a3eb0ed914418865b","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.122691933.7","_nodeVersion":"10.16.2","_npmVersion":"lerna/3.13.1/node@v10.16.2+x64 (linux)","dist":{"integrity":"sha512-G2zEzKhycKgcXvakSS1YAnCMQw9JOaGa+lTj1pIrkYsJNfFPmJUhYKVAGzXthDnlh2N2ARLVK/7E5S8JK42jvg==","shasum":"42599147c64f9168f28b90223bed2d7a2e82fb51","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.122691933.7.tgz","fileCount":29,"unpackedSize":119529,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdTxNtCRA9TVsSAnZWagAAHscP/3WrGxBC+OO5KwXUJwrP\nB6u8YfHcJS+W6cufp8//A0VyG6LQcdXv6PQviGQ1A/IocFpdfd5hUUB8j05W\n+GvzVzh2BO4wa79C5e2mrq8E/nvFlmnzM9Ue1R0ihV888++I1uUsA3ZcdM3l\nGHFvW5jBzB0JKemBJP/r1wLCCQ24HKRnX6WL+aOoq4P3Cej2iXMTWFTC/bAp\n8zSxvlvS/+4TP3R5gGvj1jonl0McuSKisSL07WXtFJC8ualO6Cym8Sk3b6Xa\n0CyKWK2g0n00cLaJFF/Qgbo0CtsKGDl0mKbhlI/iIuxHcR3Y6lqrkk6zyMch\nLKdF8iH9eOLBXzLlMtI4OxE5DGGtFijcXS1mVvuCWinXc5J2ac+Br5B65uyo\nZtDotOQRR9Hf3crtjyE/3nxR9KCIRSkx0ttntFSdk6XXNkjqP3guajAbJcPX\nfKUT9wHSjEwIU59NHtaSg/m+fOJ20V2t8MLNpWkz+wZ85ZRgbyioJra+FMDY\nXEzI+2X5sifYZsAObywXWpa7ApmJL8e4OugrLwFeAtBe42hFV8FVeHxBeImx\nqIAPSIL8xyWh5mI5oMnQO9NXAB3MFXvBZEoAcRwcPiFC/DdlGMKzLex2KpPD\n5wvPRSpQYauiaW8jee/bnlTfcoObVuSVdLtRdakMQU3f0jGjtWQVj5fVtx25\niXnA\r\n=mshH\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDThguupf99L+vDFNC25PxfumK2Yc/Xx1nxFSs657U/vAIhAOFQpkhmA3EwJRO4l+LB4yRnSWXAcfZNqmrE3025+myb"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.122691933.7_1565463404451_0.39698226325300645"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.122723633.7":{"name":"@litexa/apl","version":"0.1.7-nightly.122723633.7","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"071f4a185aa32f4866b4b68a3eb0ed914418865b","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.122723633.7","_nodeVersion":"10.16.2","_npmVersion":"lerna/3.13.1/node@v10.16.2+x64 (linux)","dist":{"integrity":"sha512-pgHIHyomCqUYz5yFE5VpMCT6P/rCmgujTmhtCYSmYSdBzyNcFcnae8ZdYKO2Q8b8ja/GspJJE9xCCLzKu8FvFw==","shasum":"ddde22883bcc34566fcbcc74a3c9ec99898dd04f","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.122723633.7.tgz","fileCount":29,"unpackedSize":119529,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdUGT4CRA9TVsSAnZWagAAkPAQAI/X5hCMGMkO3HMX5jFB\nOXBgubFakvAbIJ5U4KLulKJra8k8FcpLHr5CoLNgSmD04msYGO5T/eGLvVNJ\nrDa2zNc99A+cGAeWDOBaIUv2SBGmFH+gHUdC7k6naDgsKYFwm2bgunu54Jmr\n9HYsDEMTu20cKVl40tWtaakzV25GyWqtD48I/Xb3iF/01rqLZ+7+zzkP4V+L\nj2tRTPxk39f/LVMupgqDDYrKlOIwMIXQpdxg1PnEefuGwL+X1ChdbU8Yv1tT\nzPSpACA4fLnZGm4F/2BU/WQLc84kiAYs5P3+mhFzzp05BgwuDJ8Z5bzejsVs\n/cciLX5IFQxxmEAA6MOCmNU95C+FyONl3IjICX9hDl4DuwOhxRHgfxEvvBQw\np8q0QpSkNAAZUivjST+5MB9UJBj09YwjAJFuQozm/hNgL3mRN/efI4IUTV75\nnNY3Ko2uKeXWz6EgOgCoFQvZF6tECSjzl702rbTtOovHjc+FSvyWDdGV7Qif\nNafLuRjBmVMsjiNIEJrvHAwzNQdRIIyJPKZdLtTLqRsKa+iM+VC+u4+7tHIR\nZ/qIKFmMYz52hkeOSZNTVVi8Vgia3E1SG8kO9eLOfrC4Z7Af/Hbmu1M4qe1o\n32mfOAIHgjFZaJs+37n1uACmsz8LloSIlGmTEcqCDqMOs0R6QVPNbkdpQLrC\n8CUS\r\n=ponL\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIH68YY0b/yBDXApP+xmJvyM2bhXl0x2S5zomiXabtKrQAiA+udK4pLuBbxbJ+aZO8J8Eh11FQqNADkpiZutaCIggJg=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.122723633.7_1565549815429_0.5785977809213319"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.122873740.7":{"name":"@litexa/apl","version":"0.1.7-nightly.122873740.7","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"071f4a185aa32f4866b4b68a3eb0ed914418865b","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.122873740.7","_nodeVersion":"10.16.2","_npmVersion":"lerna/3.13.1/node@v10.16.2+x64 (linux)","dist":{"integrity":"sha512-B8wDyHCBgBgtY6r/LqP/o6egngdNCFifILah1qwfh3tk3IFC/+lPGY3m9PRp0K3tidEzWSyTLqaQmIht87AouA==","shasum":"169bcf82f216fe90df68e94743cd472319abdf74","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.122873740.7.tgz","fileCount":29,"unpackedSize":119529,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdUba1CRA9TVsSAnZWagAAZssP/19PLgP7R2KLKlP1OpRY\nJE10f9hZ8GVbuAwrFhhhcH/dySfvZV4JHFua2eF1WdZ4LOysHMnREtRzqBR8\nrr7GoYkkJFN7unyl/wo4Q9l8clEW5Y3MxetsxLY2UrEXy0nPaLU+ZXsV6iFN\nkKkFKzzFE7ICh1ItS6w6Dweim1goXZU/4PDeaAuT1Mq+EKMDc/A55AYZgIi9\nANFJ32JVLkPYJGGCfybcd0eA7VYMrU6YzUqYLe+UY0oe1eCyd4Uzn9MeKkaZ\nnat+llP+xlK5AnLzThNKZqIsWFhLRm4ga4bRYIbE2IMUVbPmb2GrUfYrzVQI\nGbR1C0glDC2NkNUlBkcMkWOFVEHVAHJ82COAxW6SwDjGSKZTx+XP4KrDXY8K\n8PaXjjmEBaEg2S9kxrjoWO/PWF9lzPQC0dKAUkXDfV850COli9HtBaLQX6tY\n14AyrvknWV3e/xt5IbjMdcYmj4Ckz8Hh2mdXCtPIdSrDxpDJGCL1lRDhlE0L\nXzdHTtKCtgCo0AgrJExIH8g3dYae1ugFOPxoJOP6r3lvTDxOGf6H54dptjMx\nu4SVqkoWgA+RnW5hj1h3vvPxAi/W82Xy2zJLRwI1MWMGEeXKcTCo2P1zxCJZ\nQYfaoaj7MgO5K4lez5wTV2N2gCVGMfE6iGttPetUnaL/DgKPRNHgq7rYl4IV\n5FwR\r\n=Pw9J\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIClx5/OgX3NsvMrhmRnavsV3y4qMB7azeOrNNX9PSw8zAiEA8figEV0q5AHHKuvwOwV+4ZtHwVNqeuxsyyd7pJ/7O2s="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.122873740.7_1565636276798_0.45176158412850054"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.123051848.7":{"name":"@litexa/apl","version":"0.1.7-nightly.123051848.7","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"071f4a185aa32f4866b4b68a3eb0ed914418865b","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.123051848.7","_nodeVersion":"10.16.2","_npmVersion":"lerna/3.13.1/node@v10.16.2+x64 (linux)","dist":{"integrity":"sha512-4PhKHE7pS5oNXnvducQNAn6gqKlIxgovZQgcLkwgUQWtntcML+3hP0hy4cCd6MJrj9OYwQtrDrPH3pwxAeUqYg==","shasum":"5e9223abb42f20bb976cf0eb041872c5bb458d69","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.123051848.7.tgz","fileCount":29,"unpackedSize":119529,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdUwiiCRA9TVsSAnZWagAASXMP+wczXXd8cAPNzLZajhdt\nBw9Mh/7BA9ULMm6GG6+q+l8X1D7ai2q56sd23Sgikh3Z1TvsmQEyEiExjq/t\n5xcUbLUCRqAATe+SJjFtuIygjuvgU9Wz06ABsyfyVzFWtwMEczjDZKVFPatw\nzJfQyBy5oEleYySGIWitrkslRGQT8wQbOMA3cURcTC9ncImI3MepQuYuKZRF\nrfYAQH+N2BfR3Qo/NG0wujS/hWfWuAFceKs5vqefux1H7M8PgXfCaeJuobfw\nsgBu0S+XAcl3FDJ+eJWVd0cZEJH5fiREIc6D3InIs7H+Rdi555x58sAiIka0\n7aNGGzDVKhEqO6eXmX9BdUGin7xq0kgWggVn77aEYuszznMLY2S7Yz6Z84a8\nH5+Cq57Ol2Dsx/XguKvT1IwLwZOi7MKdovdBLxrJF+sBkDQCGYRhKCbZ6TIr\nRiuRamfhp9LPyb7HXqqxwoUWnuVbIGZ6OeZZ4igaz0Bg1ix73m9u38pEJdlc\nMN2tNMrFkNNBpv2LuZLfcaJnr5qPJI9uU0b0c1BnaOZqcfqihyjhON1lOiWC\nq3RdXimu+29VEBCkipUYgL2jqhrRHR+9FOQ+sH12N6N8NNk1jCdc4c4B8zch\nS8l0GijrNNdFzTjITilrWt7MrQmUgVNlyZvLuDljHft/b+YHOMlpgLvABc2u\nHCBq\r\n=HJWk\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIFcBdcVpV/zJD+d3mV5KQa5Z+5eRFj0bCProp5m3W/DDAiAObqX6At7uwxEx2BM0Yyyh02hh9xlUoynv4ygOvWPF/g=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.123051848.7_1565722785362_0.5299635233129003"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.123273511.7":{"name":"@litexa/apl","version":"0.1.7-nightly.123273511.7","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"071f4a185aa32f4866b4b68a3eb0ed914418865b","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.123273511.7","_nodeVersion":"10.16.2","_npmVersion":"lerna/3.13.1/node@v10.16.2+x64 (linux)","dist":{"integrity":"sha512-8R9abJuD8uQ1scwEws+uf1FR54yYx4ypvenNVytgscPLue0PZPV+vMkF2ZEXoSVkNK77mufp7T1vAO8YdAx0yg==","shasum":"124a6c0646308ee032bb78b768869e3795143a40","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.123273511.7.tgz","fileCount":29,"unpackedSize":119529,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdVFpSCRA9TVsSAnZWagAABsoP/3YoTdd4Fe/GGQdNS0p5\nWfecrWS6wdabeaMSlPpMMvNT9UyIVH/+1Gqf4t1YdIkrCA7J5gbVkJeqGy34\nqtWy9cRfDYeoKnquVZoEdwVGNeCX3ardVAmNcmKR438F46mFG0qd6ubvYv31\ngVa0TDBg7e0FpLtur+gPCZxNytgl3pGSmV4MCR/sGl1Omh6Yn8jQRZGKMenY\n9yrdLwg7B2aHMvTlL8vmrEo25DvCy4METc0c5ezQ2hcfkK0XSPw+CBeeBKov\nblO6MWnjvKb2lj10o78gI7G5f0qlJZfHBSXXvXGFf6LvQbZ87/JP/mxQpsQ7\nAnL3B1M9hq4xCbGxiCISbLSvAaOj8/BRmqtfbDFMykxUQWrSML3DJMkV/v/g\nvjCGrap8piP6e5liwdA7+esxaVDLGwCgWnouYWPwM9G0MVccnQeI1HOgKK11\nIM9v9wyps6ZuB8cnSD2l6E+sIAIxLPqfT6E0wxJv+juFuxgKl9QhEfONHD0m\n2sUrHsk51qiZC1ERc11K3cmSKaqsLB8WQV8miv/Bse+Ct9HMMSMeQ8W9g7BH\nabGbsa+C2E14OauALwqvDNPvlUMNNlnXbZ7JuP0lOZ+Lbw23YVDK/zK0YWBL\nNndXv2PRYloSnnD4gp60hBR5EB/rq0R6JcOvzzPOPG7lZYtb65dY9rzJNaBv\nju/v\r\n=82Tr\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIFdbhAyxvUgYi7OC2yGYi0YYrWHEsjTQSr4Wa2XouZMiAiBUH49lNs0qfwCGzsJkyT/JKVpg2UNwB166ogABQT5KbA=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.123273511.7_1565809233982_0.4409642946606187"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.1.7-nightly.123413273.7":{"name":"@litexa/apl","version":"0.1.7-nightly.123413273.7","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"071f4a185aa32f4866b4b68a3eb0ed914418865b","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.1.7-nightly.123413273.7","_nodeVersion":"10.16.2","_npmVersion":"lerna/3.13.1/node@v10.16.2+x64 (linux)","dist":{"integrity":"sha512-xzXu3W9mdv68UNJwFKtZeqMNQcAoqarqIQulAPjHpRVSKpsMORc5O2xfEPQdoblfxjLvOiPHmi6ip8sKCkgFLw==","shasum":"bfdfd2d5b2c03af0befd59f720b3656350b5f2eb","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.1.7-nightly.123413273.7.tgz","fileCount":29,"unpackedSize":119529,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdVaukCRA9TVsSAnZWagAAfjYP/2ovf5cuIQaQ42k1eQ5V\n9EhnHe/bCg2k+9Pq/DptW/GVHpaYUfPbzKS0gUiBVVCpAo7spoiSselXiL/O\noeGVA8zkx9yfjlkxZe1eeI4GfufORtWHs+aDy8GrSyiWq1JTUekJ9P6n5Gdh\nUBXFW3TrSEVzj6IQqq2D0vdRHJZyGmd5ip9lTtxAtoXVZzdGVmeWjjrhLoG3\n4zIIAuMnquiz6ybA94Lv7tUXkNq1Zhj8tUmgP98zVIMAbqB8h9iLxwfXmPOL\nRdRj0piU2Xi2NQiN/r1VcE9Il3cGpblmX+0OmAtJ551RBKbdloKc3pB/JGIw\ngUQv1ddKmoEwKdYob+J368U205niQJqy1Hb8OtpbBeyYKowv6+AZdOy9uINV\nUBVyqEwepasxXrZfSslNF4v3lINEeHBSg1anYxlVQatPYrn9yGY00+4vcYvd\nejdEdRI4/txUf+VQcZHD6C2HoZMsnWq+Jtj3OvCsKSGDGBeSrWRhDTKW2q5l\nihIdJNJTJWOicygRO+AdNqeHHYx5XeLuYctKHy3CfdEjd0zHxeRFi0VuR1EG\nGxSVanPlevGgIyl3Uvel7lvfgvWhd4EienDmwNB1GEKOn5wFF2OUinRg/795\nCA4il8Cxx3y+e7bVTzWKQ5EfEUl4pr+NqRyiEROVrkZD+3pFi1hUsccS+pYv\nkAwQ\r\n=KpWu\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQD3OuouMCUp9AouySkj/x/YUa44ZeZvId1zOpZaoDvFkAIhANbxC0knyiuK+WwigcYXChc/jO18gXW55oUufjxZRp14"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.1.7-nightly.123413273.7_1565895588099_0.37506837547004435"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.2.0":{"name":"@litexa/apl","version":"0.2.0","description":"This module adds support for APL directives to litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon.com"},"keywords":["Alexa","Skill","APL","SDK"],"license":"SEE LICENSE IN LICENSE.TXT","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.games.alexa.a2z.com","gitHead":"3adf414d624551190f210b80f940c9c0fcbb89bc","_id":"@litexa/apl@0.2.0","_nodeVersion":"10.16.3","_npmVersion":"lerna/3.13.1/node@v10.16.3+x64 (linux)","dist":{"integrity":"sha512-WxWJ1mF11qQqYA6R2+aF7DBNKGTYFPjPe2UxIfx909DENQCv//16H6+AN866p4itv1F6/oj7IXPxGvcI90/b6A==","shasum":"765a3eb4bbfcda0f3c94b9a2e9dacd71648623b4","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.2.0.tgz","fileCount":29,"unpackedSize":120472,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdgtZ9CRA9TVsSAnZWagAAYvIQAJyCfmcxwhLTubMoeheQ\nzHBPm/kBeA5dlaKCdVZfMRtlsvwexw0Og0alro8cmCSxnQGd4jKrNs+aM74c\nR5qdt1SOkFvB4gkFPtLF8+6iVWWCxlGoKZCGFctjXn8ivM2rNJGEl23h4+TK\nXXxQC2h6XHPacmiw2Gp0EmLDbuvIPN9QejcFaWVs7HHzzprPb4jbjt8/9vcU\nzsla6QmwD4bSqaw1egshmjkNXowcB6EbWPzoO351ytirkisTG5GWhZxPPg2/\nfpEVRZZnsiUSh2ZAH+L4k+22BVRm2tiBaPWvdB6d75qNJlaK+073Le1MI4xw\necTR3HKmp14CnpoOrszz6/GHDHyvf+zaOBIDQRwh1+cwc3azFiuh9/yUA5Zs\nhCT6iruy1S7uUgR/ZDZ+0tmSS7pH/OHCLwN4ZTA87mDVep5ZmjyKgfiq1gBT\nkLlhc4dD3VhpZLO5AqGcKQsJPwR9o+EJHLvPDJxXnfupm+3DKbt1+GhsXXGz\nzW5VgIfJS6T/nWDVfSH51eWBTUoWnw/Yg06J1dBPRzcDpQd85V1y+MDsmMHS\nK7x2RljjwYTAnEFksnVTkGRNxC8cxbk72GUWN/vKp34m9GSoz0Vjm+8IJ0qY\nWygxgaQ2j2G1lrxfE2NzDONLRPhbnqePOmJHAtQEx5DdQ4BIlTER7OmzgZVB\n8uik\r\n=9yk7\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCep7B/zQF6Tb1gix99RGtVOIoyMGaDvbktDhfdvk5DhwIgEY9Oc16AayXUC24zKWuI4nW2ckdDWrCh7dmIXntwDU8="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.2.0_1568855677149_0.8713692285079246"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.3.0":{"name":"@litexa/apl","version":"0.3.0","description":"This module adds support for APL directives to Litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"8292531c50c47a90cb264603155b867d07759311","_id":"@litexa/apl@0.3.0","_nodeVersion":"10.16.3","_npmVersion":"lerna/3.13.1/node@v10.16.3+x64 (linux)","dist":{"integrity":"sha512-ySTYQB8JecP48ro3vVCeQGhKZ9/sEjeNxgW0zYeR+TiGB6yQjed03iHgHPvMj1j458iChCv8bBNOZmpfZQdmNA==","shasum":"42dada69214f04b4ba83776b692d53e84f0a6361","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.3.0.tgz","fileCount":29,"unpackedSize":121946,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdoRyMCRA9TVsSAnZWagAAI80QAJXeWPTQtm3ogaL0yFVf\nsccEwc3m6aT4W+I0gQ1XPSdp/0iIYoiXwZP5TTOiEIaJf4ce0p4R4JIo3BtX\nUcUfqlzCmO/vR/7TYfpfyfAwwvIKXbGHQpYBE4y6+yQg4MPsWyBzo/RfLXYK\n3/khpRjXNBAPtmyT8wFRogyCdhfMU/DlfPwgM9xls5x23c8ZJDCYOH+wT4yE\nzMDuvAEf+xFIM17t0pcFnXsstai2DlvYtX14IaLCGT8avIAlBTsH5Z6kON7o\n8dGCvCGDzvPgZVgS5faBWy0LJj6mclPCAQCZwGJUHI2v3ndcqh5AkgFHBZSD\nGaVTueXKJpFq7yGbqR8HWUxrdR+gNfqFMjJY78EfhuEMlTz+DdcqXeo8JrwE\nNkpqi1Q4gzZvQGwSKzAw8n9kdbezqGPg1GarlKZ4TdRTdyf3W0E6OJwG8Zzu\nCE5tsbtpiHXe+HImJVjGJbCHI8iDa/bSXe2XgkiFrNcAv7MmJD6sSfmSXBuX\nrTGJ9mBqzYuOPZQ30VFtyPQMFL1XKyDEKE54/yu8RHcVeH7gg/u/ps2+iVqp\nRjcJqO08gydwv/8O7GaQ6VOoQ9ZV6qzWiRjIhYT0tYoZ3Nczco3eG9noy9Ov\n8dUtPP5Xujwsvqi3Z15LLIbBRl7IlhBI0bR2hvIFVZx4Qorktzmld4To8QQX\n9Kjh\r\n=6QoR\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDO20yLt7aBzpMW2U5BgrFylwt9HetCsTuGaNzcBcCEqgIgCHGIKT85M4ZpQxnHEv39XdyestKcHYxMYlRDbz7Vxwg="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.3.0_1570839691579_0.536068131872004"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.3.1":{"name":"@litexa/apl","version":"0.3.1","description":"This module adds support for APL directives to Litexa.","scripts":{"build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"0a9b12eed2e37a861122c71cb3f3ac26ea9fe4bd","_id":"@litexa/apl@0.3.1","_nodeVersion":"10.16.3","_npmVersion":"lerna/3.13.1/node@v10.16.3+x64 (linux)","dist":{"integrity":"sha512-kbvw3+q0VK5QyrbPIktILNQv4zn2RUPJUO6rCCSapiLzcwWdW1k10XKZhXxC/b67FQK0TrEp1+9EMAM12qEovA==","shasum":"2cf6c3a2fdef9ce19ee0a2dd1612cd553fb7f376","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.3.1.tgz","fileCount":29,"unpackedSize":122265,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJdpP1HCRA9TVsSAnZWagAADfEQAI5JSyCm9y6W6XFUzJpG\nkeEn6imr2MPdkvn0LdyUaime68KrV9c5SjgANT30HAIo2sIDMj0olQLUs4K+\nZ+Z5udEox1pSgNoHfUx2kWHMAP4LtjYbLxMBSW9fLuMCHSkDf2lWozRo4a8O\nbl1OmDrgNvW92bNU3zL2FES8RqLDyjS3rttc02L1cmEfytY1fiMs28/ep3Mz\nS34wJOZFhHZ+vgAkzaHsK8kE2zK+qB6g7Pm/i+jKnB+3s0yMwgTY7XdEx/P3\nPJVsxQMNnk3bc31NloP5T5f9mlzd9vUYX4e7UdnFaebncSPkEOHF1KFVg5NF\nCtbKy9VHsZzGR2AHRyFILU/kuQqed6IxfRgjfzUW9jwiBM2Ch3jPc0wN1WDS\nWhGriR2+IjvH3DW+PPSgVt8XFAlS/nvZQcJzJDXz60qc+UEqWL5qyneMPm1b\nRbwnq3IK8g5uKAyICraCwxkW2gVY1MjsiRhneIn/04X+6hYoZ5585HmjJdBs\nH7aFqkXW/o1S4OiOEStM5sN1e3z3JFlmipHFhpFyUBVrK/fR6qEktLXmvGrk\ncfct3MuYejQUCMb7IrUZSpHtCFa1gyXKNkyxRLGV62kjEiY1lF5amBOdvJ1n\nlI9dRpGqWKuradf4N4LkiXExsBbq62fURmuTWKDITwvCuefVCqX8KHX/9yYG\nmVIT\r\n=j4fE\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQC6KEf06DIhd0B8xHEBCHbKW66SZTmP1duX2SiY0M+EpwIgMmjdlFkECE5xTpBZxi9SjNmyzZKf/GFNEtup16MgEZ8="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.3.1_1571093830819_0.08022421848523997"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.3.2-nightly.143460678.10":{"name":"@litexa/apl","version":"0.3.2-nightly.143460678.10","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"84d2ba7851387deed6fff571ba072018eff9a4f0","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.3.2-nightly.143460678.10","_nodeVersion":"10.18.0","_npmVersion":"lerna/3.13.1/node@v10.18.0+x64 (linux)","dist":{"integrity":"sha512-bkmxskfZ2f5dkkFhSOYh8ei0ZDvv0o5gUbb/xCkIST0t2xgnhvMTNlTw5DOaUVU+cyN59P14hGY7fT1qT34OBQ==","shasum":"7606bc8b179b15917908331dcf8fb2379401c092","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.3.2-nightly.143460678.10.tgz","fileCount":29,"unpackedSize":122328,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJeFOfdCRA9TVsSAnZWagAAUdQQAILwcW6Dwohdu/y5TIIy\nwYFDg4Aq74DYOYJFSR8v08YxzaWm7kZMvNG9zhqFZTAtfWKWyZHJvSnt0aDI\n5nGrebjRML+d/jMhLZ0/uNdmnaS+qp1NcfeBfdCzxVY6v4KjBwvEiI2OgV4h\ns30uuIIh9cmVnxuM+ztjjMxWjphDAUweegSpgoqOm1aj6CcLLuV2aiYdGXHq\nc0VDWskmz9Z/CRRdmInnhnRGcJ/RghoH+udBhmh3Rb30dhpL675CibO+NE3B\nRn6aHvdM0vi8XmhuojE0Xg6weN3NAGlwN8zRGhqKuYj+E8mlJPC/5lvde4ta\n8NthEUnj1rQBy2J8JX35y/mxTAZWSWEHqHOhUN4GSxokCcvkKrrtreEmVQ0F\nIBN2J0El/RasnmBydOPvZ23Zr9ulviTEOHZfNYFyQZM05guPEwfNXb5ykuCd\nU4t5/lIKo6TBreu/bsjUh3MQ+cWz6qDBNhV4c8D/oXo+y9j2qJKGZ75U46wt\nknNfQqvSLCFIXhAjwO38Zb2m3IwKLrC7mh2YBrt8P4t5gf/rbfCkiVTno4Fs\nKjpn4HgkaHak2oLXWlw4juIOHsHU54jzdVvRbsxDqpCdpH8mAw7F154dC+MV\n4x26WZqxsgq2Mw+ktIs58iR1ZXXHXtZgEa4ah7pyZuwulpIIU5gF+ZDBxviI\nVBpt\r\n=Xfli\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCHKUony1oioMPlg/RD12PX8n3P8AXpr0Zh/xOaPGyYOwIhALwFBALNKhFmlg3wnZSfIZo/6gE765DXJVRqp3A+cwsH"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.3.2-nightly.143460678.10_1578428380946_0.4775472427555234"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.3.2-nightly.143626239.10":{"name":"@litexa/apl","version":"0.3.2-nightly.143626239.10","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"84d2ba7851387deed6fff571ba072018eff9a4f0","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.3.2-nightly.143626239.10","_nodeVersion":"10.18.0","_npmVersion":"lerna/3.13.1/node@v10.18.0+x64 (linux)","dist":{"integrity":"sha512-ZFyZEWvjeQSevXscCktIFNqWReoXxo3jvnrLAqdkXS/+1cNaXO1BaPJt9GCNwykNGS+UDi0Q5TdF6R5AMaAI7A==","shasum":"902e7b56daf8b161b1e410f3f71ba3d73c35d67e","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.3.2-nightly.143626239.10.tgz","fileCount":29,"unpackedSize":122328,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJeFjlWCRA9TVsSAnZWagAAQUgQAJ3oNxO189TpPDQ8loZG\nGIG2lMkSxSIscR2eavEAvzP0os0TLD1Pdn2UqgXgxubGRiBQJXrEPMDxywNu\nLfmbAae7JC0B2YlZJH8PHCDz9et6q134Rbcm+tXUkRaTm9hP5EnF5p0Ysg+R\nh6rvwNuAzbVmqAxXV9csAweC44xvwCQLwTgky9x9byoMAEvw/xWSTXnEpq7K\nQNwCagYU8ELJ51WDQMjZvkjz8CqhGf507LsdQZX+drwj1O+uUZuhO0eCQ4IK\nV7W3Dy/fqbtNbI/CBBAZsQQMREQnMpG+1IUMxKb/hEaADN05dwM5OFp1JMNX\ntqsdeYVuCBnsb7rMcn1jhIGfoXg2dwAoQ+jnFxHN5g9KrKgQ+JNhymvcprpo\n1hDLKPhmAvxN8yISyWG9twa9HwUZTlxfbh7aJxhzhx3+CA2ZieEFioSE57f4\nEdVcgeLv/CYCQqK8eDM5P+oJDokYb0haCujf8uxgIjLqvXF0XXpyhQglgP61\nnGsE7m0VIBExwWS0j/cZWx7Kzq39RtRvhrGwM93oP7ljgW32xICvmUpl1EYX\nDuL/KECIXjToO+0Ug40SYnvRyQoYJymko1me3+++o0C8nufDNr0vJ03i1T/f\nrg1oNup1rDWhNWc4d6FCGUxUjmgcngxkjmVCKDpZWkI/DYmCQ8lPZdFH1oPf\nyAId\r\n=lSss\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIGsv7KOTxXA/r7+vjQ37ntVBTbBYUerAD2/WOkg382qtAiB711iTrsHy80KLjYSkvXf0aSExnJ5LXVTqspVFnfE9wQ=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.3.2-nightly.143626239.10_1578514774370_0.13913938875328258"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.3.2-nightly.144576404.16":{"name":"@litexa/apl","version":"0.3.2-nightly.144576404.16","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"e833b8f81c68a81446c70237151b55b4c7807f41","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.3.2-nightly.144576404.16","_nodeVersion":"10.18.1","_npmVersion":"lerna/3.13.1/node@v10.18.1+x64 (linux)","dist":{"integrity":"sha512-E1yNE7Sai3YXksOPOEibG72XLTUHEeWO3xtEVjQtH/kSQT9E6bw+8Fg+wwVbgkz5TKvpwDV/QPlsO9cyRt114w==","shasum":"77e4b5dc44a76ce1ef265f408f9d5ad4bdd33fa9","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.3.2-nightly.144576404.16.tgz","fileCount":29,"unpackedSize":123279,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJeH3SkCRA9TVsSAnZWagAA0xIP/1SaO4M+KQGRzfIJPXYQ\nU9U0pMiHYW5rVUeWg2ecGCykts/gUFloBOAK7r67+uztHAumtA9NuhDmXefr\nHbrwtkV3Ydqt0l5iftj0s6U78b/WyhOZnusa8oNkydfMAWLkfEGb1cjAMDbZ\nhHBA+YYE9zvHr0kJrrbMGFB79rWOAzcJ37xVr4gxl2cbwrjXxM1mN3a1eIy9\nhMRj5cQaxYB8jm5JvmfDunzbx3ra14Dxqqz6VjDnPYXNh8uM9jY2GLGHvcFM\nPtFE1u2VD2jodmD6u3VgEFcfQA7gxJEWJohc+4SdMbaOZAcSiQFofIy085kN\n149rGXXsnZ+mlvrH2xmykuKnD5rGLEEz3/9x8rW4AeRK4dfKlNkt2avUsMdX\nQOnsWmGZ3CVa/6F8/cSb6JgQuiBPkVutEFF5GHNIKZeeeVTMyrOUM7IHEM9R\ncdQ74yLeJy6IY05jub/dsfCLvSaSMoGAuBP/gl87hlGa+ldXObGtMSgxLTaQ\nivvPJNobuiu9ie5pg/0B7QpZmt7tenzytsZoJvc133IvIsBQ+87/tbSZ2yDo\npbxegwNlRNGYLI/ETxzToRy1YN2xjt4ToPmRkLGEA5DGDhjIxfDmloMZF4OE\ncgmaxDbMjBrC8bK6Ja5WnLVQVmwyBkuxTnkNAZ/3Tl0Bgl36Y61O7IIJHF0R\nsUSx\r\n=cTfF\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCe9wlihVI5rCW7YbhbWHSdDxL9RtmLzcjqtnQJR3G1UgIhAO/hzO8/YEkKF/1ClkhFgJyLfETNsn5wr0PPf2N7NDAI"}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.3.2-nightly.144576404.16_1579119779608_0.202361198271918"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.3.2-nightly.144807869.16":{"name":"@litexa/apl","version":"0.3.2-nightly.144807869.16","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha \"./test/**/*.spec.js\"","test:debug":"npx mocha debug \"./test/**/**.spec.js\"","test:file":"npx mocha","test:file:debug":"npx mocha debug"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"e833b8f81c68a81446c70237151b55b4c7807f41","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.3.2-nightly.144807869.16","_nodeVersion":"10.18.1","_npmVersion":"lerna/3.13.1/node@v10.18.1+x64 (linux)","dist":{"integrity":"sha512-HSghwvGx9m3tuxI50U80N52wcsofVybjT2tfXtCkivNN/8dWdCeXtSWewTrJQeOay58VkP+15We9mdJpekFhhw==","shasum":"bb7c54d6969643187d80e2e815c9f47f9bffa4ff","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.3.2-nightly.144807869.16.tgz","fileCount":29,"unpackedSize":123279,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJeIMYDCRA9TVsSAnZWagAA68MP/i0g5xEM62K3r3vU6u3n\nRglriuh1YruPL9SzPtcyPS54DZTn3Go33g9v/RU/K4dqZxwl1vk2v0f5ffVZ\nt9LjEpmfATisAOG1pEgvyj3ZCsrLjx51lEnWIiObm1ydr9cpY1E04BoaKVxz\nCJyPjk1QJ7ZCPQuTx8Kr02NR37u1O6CGckNdMfuLaiigKTOxlQ7gCT8AgO6A\n46oinXK9+BDZch95a/MvBip5/CcVz+U3OTQK1iC/73IRpfMYtOHJfogA85Or\nYnR70+TfJbC1YoQpWCtojU/67Nq4p1pfxNcAbzA+TfH0iR5ppSEPiPEBHXxM\nGIev+3OVjYftdODV3HEGaJ30gGfZ5o8nw2912eJdMxsEjA3niK92o/+WXI5g\nRDawHAthM9oIN8En/Y1MA4T1Gs2oEWRWfAUelUF4OzUZYQj8NP8B8ngB1Q1Z\nVeUJSkPXo9GVQqlVVsSbSf2J2y8L/ZUkBfgioupZ2UPf6mdNQinfXTNLzkyY\nfFwiEYIY5p6gQ7kKxszOyiiYC0JMuyb8llRp9tdMamHtYIBHpteqm5HUKg9p\nVlfVGyXt/Q61I05nV9c2CBCLuUPxPmLsn7nSRTAPNFfagNveeF2OnAwKJKhM\nILjuRFAgwnHMlLWOIYyMKFB51DtPV+F//odIMI3inXlxjkTdYucpN0fQkD5k\npmli\r\n=30uJ\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIBz2ARmv4cXyOspx8kPbtBtsGpCkHwP74ivBA5weMwxzAiBXQW1iZGLQH5RUersG8gPIKmhljla4n1/uD/c1zWhoHA=="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.3.2-nightly.144807869.16_1579206146646_0.8198450132651949"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.4.0":{"name":"@litexa/apl","version":"0.4.0","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha './test/**/*.spec.js'","test:file":"npx mocha"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"5f203822eb5ecfad5590d02d8d3c8b1a39a44b81","_id":"@litexa/apl@0.4.0","_nodeVersion":"10.18.1","_npmVersion":"lerna/3.13.1/node@v10.18.1+x64 (linux)","dist":{"integrity":"sha512-XIzp5O7yXZgoBBs9QqWUKuoylpDB7wcdee7GQQJo2RiQ5BwiiLOZieSHIycnmrYBvjtpp/pbQeowJOvRo71fIA==","shasum":"a9b6fe9bb1c4090e689a9ffc22f6bc12a9a8a99a","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.4.0.tgz","fileCount":29,"unpackedSize":123907,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJeMiTGCRA9TVsSAnZWagAAOqMP+gMnTxLQXM+TCZEaXJUJ\nsmN7P7M9xFgkx5b4JdwxqiUdab/MZFSYt0HdDdslVxLOp8qcbTS2u0NRfFio\nYNh5PTBYsFcBO5fC2W3WQr+4BIntzHd4AYVLSB1Wix87lm8yEp1V40rMyaF1\n6dv8RSrp3XHo/UFu12lDrcJmRuntQxhwTlPZm60IcdDsrdqIX3vK0sjcJDKA\nA64JKfdpx8SGSWSFoYEnGpQT+gz6wwUjk0WBQAqxAR1Gxuo1NU+HmwS3mMD7\n/ifZxK/MZXiI4y85HxpKBfQWrjfS/YyqQOU26K7bL1xA6v8fdCzQOr5CU0p3\nLmeWs8djwFvzhD23kgVcbKS/hSFhskeaMkxFGpNakArzKxpe1Ab2WfYUqkE5\nLpDQOHuq0TELaf4e2P9yHsNuFx2xlEhqI32e/AMAwRr9/0qFX+xFYm7ioiDt\nLpZxEIRMDXXqRxqGMYtfldn+kIQ3eHELHYT5lFVkWc0+k3my8mg6xcnd2AGi\n1x/ZV+2DQkWpTIpndN1ACfFhy1Q06wCTQG9dn24eK2v5a2eenIk4E1elEkRo\nrzji+5tySAYSIfX4k8WeeEs1u9WJIjaFbInPoZuLmH0gt+WJ07XsqLubYJ56\nV3Vs0DzuPbQadD5Vq9cXXi2YzPvXQp7f2WhBXX9ayNCWsh6YwSuKxWPZhxIi\nfLoN\r\n=Pwht\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDXMxH6OBdfXFNASQ4WCFK/x/VnrAEsPeDJ3zGce2f/YAiEAqEtXf5Xh5YJqNInDIFwbra4ylS3Mil2S3XpaA5RkuTI="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.4.0_1580344518099_0.7782773564279173"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.4.2-nightly.157326457.1":{"name":"@litexa/apl","version":"0.4.2-nightly.157326457.1","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha './test/**/*.spec.js'","test:file":"npx mocha"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"f3cc7de046f0d8f633c991aeefe33e032a6f1bd3","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md","_id":"@litexa/apl@0.4.2-nightly.157326457.1","_nodeVersion":"10.19.0","_npmVersion":"lerna/3.20.2/node@v10.19.0+x64 (linux)","dist":{"integrity":"sha512-3Z7of0unL/lzm+HywX/KL4KMgTuIXRkgX+DeG+NAUvNEbdHtXT5GTCv7fFxRJ2fIkrzXWLW5r1r8czpmYEQ80w==","shasum":"8ba551d0b52b1e483ff8ad875c9c2e193fa61f0f","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.4.2-nightly.157326457.1.tgz","fileCount":29,"unpackedSize":123935,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJeg6/TCRA9TVsSAnZWagAA5b4P/RSkwHEF1Xc4GCOroS3g\nCFg2OH5rQyrJ+cn236AkEI8oMxE71Dlomd1KzZgYLBCtStD97opfCBIogHlt\nlpUURmiZOFtioi/opiCupLUcnINYK2/OAsg58gR9LUNBxtX91IcSvmGmPFtu\nraUCMSs1v6uGDmaJ0EckqqZTvWH5TwdIXINX7ejWVGcKBIO7r3OrTSgAMjFO\nvsREVCyRKpImKee0X7/Bt8Bo93RoPoKU+/AhZ2xzuzFHKAaISllwLMt1pk96\nYjyVjEbF6ZjP8ebeLvQQXV5YI3ni25vfWPUoFkyeiPcDHRanYDZDOGu3pMDg\nJQdSibi5xLAeK2vABmHGbTyvRybwn/XuUQBhmH8FScx0+52sGnev84WuIQuh\nn66f3pHN6LKjO1iFTuh2toWvKGlUGuL3AvgtGweiEB9M01VNmlEu5ymQRXQA\nJN6lRTZ2fGYg6TEhq2Ra2eOxnVmr2wL91GaKrCnHuuAMTxfn49IGXX+tdWLN\n5AqTW3haigOM4NpkpiTpZXnD7fpd8lwmmReYPdAsubw18RbfcFVVlwn5IgLC\nsTTP10Wge4hcadigF8gEYjtWY9ZxCw+6iCaccauhwJ/ZrBqpyRQnbRPpfM9l\nAc/Ir9vWk6pfuuFQymfzqBSJskgIYAmmGXTc+crZQsU3Q0cEaExF/n61nMYa\n0fvO\r\n=wZTq\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIESAYdUUGgwd6TChVATeiHBhxRXnqEKPsLtsX1vcaNwkAiEAslRR6gvERz5zc7P+kcP8w+cp0rCE7YPsj2NWBDBUuPM="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.4.2-nightly.157326457.1_1585688530757_0.11556810327897882"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.5.0":{"name":"@litexa/apl","version":"0.5.0","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha './test/**/*.spec.js'","test:file":"npx mocha"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"89b994293c4b99a342b9306ed4d90528fee81d3d","_id":"@litexa/apl@0.5.0","_nodeVersion":"10.19.0","_npmVersion":"lerna/3.20.2/node@v10.19.0+x64 (linux)","dist":{"integrity":"sha512-KW4SvN34B5yLgWl5AFpvCs6emwRtSJS46ggK245LPNcL82eDhmhBq/wasfJeTLIW+BxjCWjmFM0Eq/Eldh/sZQ==","shasum":"f49d32cca4478c39feb48de037b661e8aa5c11ed","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.5.0.tgz","fileCount":29,"unpackedSize":124051,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJehQyqCRA9TVsSAnZWagAALA8P/2+kcVgMDmz3SGz1xVNE\n05jDJP1wckkflJG/2m55ogHlkJytaofnEIMEcUSj1BWG8jglYVhyeWTOu7r2\n+o6Z9HtC3s7UzjCtDpFL+z+E9Keu0dwsUzjQ2vKacvV4CrQunjJAYSvuFujE\nipEWrLCt7D9YX5BjD2Y3a0ZgODaVIcMjMo3f6+SzbUWzjrivdIu01UDaUl+u\n16vX/DZ7qf1K2qZUajiLi8Xa7A6z3F+kyzvSGdfpve1Mz9/6CHi/bcz/YUHU\nMS3L8byLtEkMviw5KhXutw9/gE3vYCjG2c7ty8HXR7Z/mO33dkzy7Igg0yYI\nGKrn8bvCGGFyF2Z2VP90YQ65hKa63COAmwsw9kqwnDGOYVnVMX1uVhVnbKsU\nrGEzyOn2+bZk4LwPt2w8eGglOUHR7vBw7NNFz1RYQZTCc2E0E1PRTcfWPTa8\nS8ChscWkaNrQAYCxEKeBcT9p5uSyBFRRNo4QVQ9sAmveMkBPCdskkftbpG/6\nLNESJWOTe2QSB02DHQ+MCqoHwS38tA6OEMMqHRRxIVOjpK/LtTE2J/OJROr6\nXi80hu/hatW8jDEkvFzpaw1Xi8Eqyc0JxaIg0Kb5hd6makC+/Y9UrlvQA5jh\n1M6nf3inVLRfLZzi+0uTskUqxWyukzrcQV3YxtOsN3MQHVqhQIwoRLrgrTGa\nkS0J\r\n=OfQ2\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDkZJ68rA/rUb6BC2lNMKPCoZuMeGnCU5lfgzH6v700qgIgRU5/+hUSkf6YXYt27EfHaYUiNG7Ct809LoB9aWX+lHU="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.5.0_1585777834023_0.7875709179602675"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.5.1":{"name":"@litexa/apl","version":"0.5.1","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha './test/**/*.spec.js'","test:file":"npx mocha"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"12aed72dbe659ee9d246eda215be4e7c94a15ee6","_id":"@litexa/apl@0.5.1","_nodeVersion":"10.21.0","_npmVersion":"lerna/3.22.0/node@v10.21.0+x64 (linux)","dist":{"integrity":"sha512-8RdiwCPsbkyxO6Nb6swsaozJE5Gu8Php3CzSczq8kRC17mZbCu/5eDnA2IpyQGnByf/KaxL9eIOxGO46vytIiQ==","shasum":"38db463e104cf8f376ef6df09456f4d7b98a4abc","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.5.1.tgz","fileCount":29,"unpackedSize":124196,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJe4/3/CRA9TVsSAnZWagAAh6MP/0To8CZyDDXUwGBCRKr3\nxVwhfXsXhyeR6RiE6eYhG6z5/sIgLQXgPsMN4GFAv6P4ulT/b7xStBi+pswn\n1yOMIUE23GEVaYrcxpbiW1xoHEwm9aFz35ziZhvpwEn7VASK3CCXStlQt8t1\n8HNFDFcldS/qKLdcj74+2SzfL2tPPwtJrxRJCPGTCjQYpQGo4ZHftO/C4Ik1\nhE9V3rDUYARmWrLkZGm6JQQRClTz5Jw2iT8Bqxx7rabdAd0F2iKTEHJ2Y+iE\n5AMlwLlXHx9Xt0zycDUEP+NuvdRORIEa8NpXgGuhhyex+JCZeKTmIj9/dabE\nICUAvwbdfuCdMaud2FFThl8AXLO4eu2e4/LPHabzuDivW3OKqP8ubJJSsUlb\naZBn+6ejDbxwSnDAj+daREc5Na+OXpVZeCOd4qlPhE7Vh/YNHNYN6/efmISg\ncdLNEq/YXFU9CYTYa/q0ABxjUMJjTVls7vd29jtG1u0eVGXBg3dE9EB8GYU7\nsvN45/M+1OjmAW72ywbvcx0DxrsmWDGGDwHss0mx3xymUaGA+jYMs7xYk1sL\nkN13Z+gd7tbLB1vnCeNtP7+7oCTTnZd731fmQYIQaDNRwQ3nu/FHuYvZ5fA7\nXXwiV5mIwBbiQDbKJb0Mc5Her31OGeY674hydAGd/WPe4IrEOLkrzYNGqOrC\nBPYL\r\n=sjw8\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCiWd184VHQaoh8sfuffV8yHc853w6Mx0Pii2HrMx5kYQIgBF3LLgq79nCEobTuFKJAeBfQDMqWsztxfk9OXJSeoS4="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.5.1_1591999999375_0.2677193981343622"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.6.0":{"name":"@litexa/apl","version":"0.6.0","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha './test/**/*.spec.js'","test:file":"npx mocha"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"7652d56addc4fbc53b4fba8de27bc7f307109cb3","_id":"@litexa/apl@0.6.0","_nodeVersion":"10.21.0","_npmVersion":"lerna/3.22.0/node@v10.21.0+x64 (linux)","dist":{"integrity":"sha512-Mv1HyQrG+VIcOk2vi4zFTFbdv7I6hGqwsSlSmbbsBWQZnoRWqNTUi2tU1YlE1VwoiaWsClEZMYBS9vXVl8NLKQ==","shasum":"6699ffd3e8d6ee109f48843e470fe3a92942af22","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.6.0.tgz","fileCount":29,"unpackedSize":124340,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJe6CqyCRA9TVsSAnZWagAA+p0QAIAZUFeFrzku2HTxQ0oU\nlYeVRh7dCj+e1mlgUuWTW+3omjvlQMGeYE/ifbuGmSpE6Z4osqq7T5fNlFnI\nihqW2Bq7NI3HsaA6Y6F8fcpU/g34QKoGabBlW29l677WJsvg7hITHQB93Le8\n7CwKF+tglaqubQZW3n/qM9z37OUZCDj8veW/IrVSL13WI8PcVb3mjtSmUtbX\noWVMf5XqOUxAbFmkHB8pTn05+AQeyPNUxLG6iQjwiESSwSJ6gNk/iToeoCRj\n4jeGNK9Rzyep33zUBc8otYw1v3Pyamlbq4gILqh5W3DNJlI+YIYUP1fTsvkt\nOS2IkIogVNjVIPYTyvythyH/7PrD1X6O03nhzcoYvoCEBN7wgowaAaITSPYi\n/p7LmgzVtsM1Z3kxguKLzwmiyvlYF7JQ/Jmt8OjrP3GC8z0mGgtt95UzhQWh\nhQl9YRkv9SlGHGkunU34Edf5uAI9+s5NFZv1LXAT1QTsWKFFecqVE3+LcuRI\nlIPY8wo/FM0QY7tD5cJKNxO84A3jXombO8qSSsrHjQ7DoDR5ggmdhDKvKlFL\n21Ah3karsRoq8pxIvXBHo4+ty4mC0jlsOMbLlXoHvPjIjtNd8F/Xbz7+CprV\nYnpLgqt1SWc4ixs77nLLEa0ot3CApH69hJxtG1oY8VKbh/K/dsXMFXFXOh5V\nZWAo\r\n=N9Ih\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDdOZEkBN/15L2fZ2qeBrpw5MJMDlFYbChcC0QG2eZf4wIgDoWFBpdhwsCzohl1kYPanUDBsGmYrfJWqdv21QfNl7E="}]},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.6.0_1592273586030_0.011908105738482666"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.7.0":{"name":"@litexa/apl","version":"0.7.0","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha './test/**/*.spec.js'","test:file":"npx mocha"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"bfb1e3d6cd40f3fbe3491a1f4512539cdcf7b9c2","_id":"@litexa/apl@0.7.0","_nodeVersion":"10.22.1","_npmVersion":"lerna/3.22.1/node@v10.22.1+x64 (linux)","dist":{"integrity":"sha512-GEcFyMOd6vw95cMLJocJCnUy/5aDBCsjSnAKGcenaye+52LQoPaEWKMflPnPsMRFYW1DcqBwO8pnD2H60cfnhg==","shasum":"74c5c30a56643af744d1a91502441d6e3927c388","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.7.0.tgz","fileCount":29,"unpackedSize":124484,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJfd6sICRA9TVsSAnZWagAAdKYP/A3/Fg8109lNyqemosO3\n9X0UDcLFv+75Fhv7rI4itgbh1URiSAJhofSuBa26HZluAd4c2OKxPmp9LU5p\n5LIDnY+0zGgRZlMOAktaQj6/2aDwVurHRDGEcqhctswALcqCJDOzNqrrcOp6\nOgZpnOrCqa/aDX73KNS6mBnuKWuPQ8gfClNAygAmxHH5AVDQz6xcP/x9NURz\niTenyM59jDOuqa0fRwXdZgTlG+hN8biFBb5LNm6hv6g1hfvZoZIjk7bBRrhr\nA/nkKV+ckIxsoYJkwu2XB43E+02mjAwqfY5XZybJ8wW+PH6ssgL7+E66dAzN\nmC43TyorQ8qxkY/4rrKcR6EYOm1B6jaHSN6DAroMEQPiosaKx/A1dBQKI2CA\nKfYmnJrmOWMz0RINS2n8yvcv1L9N6M4F5Ivk3Zyekl80XVVdZhuWflqyY6kO\nNgrHCfh74uUOdA4RNgAT/ZeMLj+yjTK7ODYAEJEwopiiiy8cykZmo8tpPXsg\nWm8KXfwEOiIoRQhn5HmrDy8v68Gf5R7rtJqfrfyQmpV/h2ks2A+y4sXeTwAD\nibUveiCXCBKmv23lZIaK7mB0/E7dm2sNR2GtlomTovVTg6hnN0pFObpoJCgc\neNcLGPfHrBTvs1VIfhFG9U1R9CghGxnQatT0GYmyEadXTJkDvOHNscn2N3Em\nql0M\r\n=BM8+\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCICDTuXaC4ZjrjVw3/n9PfhFiitNIJaC2kHi49GQRnl8JAiAn8B6uGIgEUCJ597nP2wcEhPv6JnGp7qIgtkDcS3qAaQ=="}]},"maintainers":[{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"}],"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builder@amazon.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.7.0_1601678088051_0.5137616934339109"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.7.2":{"name":"@litexa/apl","version":"0.7.2","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha './test/**/*.spec.js'","test:file":"npx mocha"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"4e9de1b4d975db48ade88264c869be8ebc30401c","_id":"@litexa/apl@0.7.2","_nodeVersion":"10.23.0","_npmVersion":"lerna/3.22.1/node@v10.23.0+x64 (linux)","dist":{"integrity":"sha512-jhUO62RfXqyQWP43MHEaCmoRKpdQqSvG+G5SBKtA1BLhgUEGLXLUwUR0QHuBcZHtwpZ7rm12s5qrH/LKaFkIyg==","shasum":"f4696619ab3ce67e74fe3be65dcd99295daa4060","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.7.2.tgz","fileCount":29,"unpackedSize":124629,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJf67vjCRA9TVsSAnZWagAAhXoP/1foFG09ers9qZ+qx4Wg\n8qhO9JOtDjSX8gGfa2z48TqCNONFjR4bgjNioUY7sNQGbMvRCTXflN2llxQT\nw4Idn1nsy69hYfDxwNbpuM01evfd0DLPOLzwsIOy0HWsGF7oSfQvrC7M8h2/\naxKI//SKz7WqBUGQQDyVx6lD5itvJLfPU82CvnJc0uvFwDzQ58j1G5iDEh5s\nuOP+nWMC2eBAqm2m8QmH5FP/yHxaN3Dyu8eldrUOItUPZSEfwctL0SpUbm73\nQEW/j+/k4Pf+r6fzWnAGX7fqEg0EAJNrir31IGFw1XZPcjUHFrdK5tDm3VvF\nRiYxaSxWB3ScAr+WK2iP0i5JbeCTbeK8KlTbcuR9NGtyQ16uNnWnfwQsg1DA\nM1tGtDSLQGQEZelOkuzaE9PGsiuxEDwyIt1tlM75SXaH/4COLusoxqjUVB1u\nCr7YXyvlm959QPgjBrlGI5J9TjW8A7Qzj0hGNSGypFiVrZNqcggkJ+DvdQ9b\nZCxDnhQTCbP9pfmB1DGksvirQ1G4Xn52Db7kti59G34gvOGFqAVu52Wta2Zy\n/oAm+AJC5bIH/FrjMPqYd5uHa5bncYOWwHkmfky3xZ0YSmCiCgT7DnywZUly\nAXLWWLnzBus84qv9LFC6TS9uE+yBpykVucEGRiOO+5oveEeTaAdqNwbHjjP9\naR4U\r\n=IMST\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIAYVvIwmYJYwr4PWu7I7tUHMZHJ8YfzOof4kUkdkpmdvAiEA7MQyX5nvNx7WOtSqGtv1nCSUHWZjRZ2OiLPPNINJuyo="}]},"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builders@amazon.com"},"directories":{},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builders@amazon.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.7.2_1609284578608_0.19878287197038458"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.8.0":{"name":"@litexa/apl","version":"0.8.0","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha './test/**/*.spec.js'","test:file":"npx mocha"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"1433954be45b5d6dabe3a3282775c30830858395","_id":"@litexa/apl@0.8.0","_nodeVersion":"10.24.1","_npmVersion":"lerna/4.0.0/node@v10.24.1+x64 (darwin)","dist":{"integrity":"sha512-ByKVVGiTX05JlMRWlowS5Wyj7gkBPhCAFwcMBE9mOR+eGjqyvklfH9sPLpuhMS+IVrCHBg95hDljDgCMp+Tr6A==","shasum":"245ebc03e9365fb2d499d23a191bb019822752cd","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.8.0.tgz","fileCount":29,"unpackedSize":124629,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJh7xF/CRA9TVsSAnZWagAAtgYQAJYSGsDQZFjJE2sVypEl\n6aQCGCEtGyvt/pCvn7ce9bNGADNoRZvpPmXXC0URhAFa3SceaKqKxlmpuTqY\nrVqypQ0AW/IOo0o2ziF9qRqSA6MXqPngyBMZ2H/Ewtju2yqTD1l9M6UgYwot\nyNrANDiA8ybLig33HiV0pjyENm5tpT+x5y1fDvkS0lrLfKN90UXdFq/dpVl9\ncTBnne6Mt0Bzewk4uJd6o+buv4AFc/3QDdVXGDVg6WyDSV7U61lIhlIaBDPk\nMGucsUxtVSOzpHjA2Sz8N5pujw9qDTgpSTRiOkDLeFUczRT7MGg+ot4RGwmU\nmW29y3mmddBKkm8u59R+XG2FOCoTrYOzyPNBBS5lxhOlffls2UUTr4TvlSy2\ntSO2SK+jESf9My7+ZdNPnaNRcjFMez+1tzq+W9YVEY0GtCXAi2rbNHFtPFoc\nFEq2a1dg4r8ombQF4CY7ZBw2/9QdXKIUqt8Fb3fJXWCjtgqIWTkZQLYuKB4l\n43QjDkCXB8aBNxcqqEua1txpaWA19yjNxuVxfApkyPjwJYCAeyr3lIToqao7\nIw6/V4nfDA1sthZkWOCxFYwL80vB80AAeUDY7hB3S2HzXWgw/nu1LGqscCia\nM/+2kDfvQ0iSVqjgofrRj2ziV1Huo2gZ2UsMlNkLvWAvfuXQVxeyHBKloYBK\noyN2\r\n=xgRS\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDOZvUf9CQ3tuREi9l5R1NIx1W6qgJPsvF7VFzk0ZCzxAIgBxhT3Su0ETgA2BRPPYD4uIQGPNxencBfRpWDMs1Ivy8="}]},"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builders@amazon.com"},"directories":{},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builders@amazon.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.8.0_1643057535363_0.318238198817266"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"0.9.0":{"name":"@litexa/apl","version":"0.9.0","description":"This module adds support for APL directives to Litexa.","scripts":{"audit:fix":"npm audit fix","build":"npm run clean && npm install","clean":"npx rimraf node_modules","compile":"npx rollup --config rollup.config.js","coverage":"npx nyc npm test && node ../../cacheCoverage.js","postinstall":"npm run compile","test":"npx mocha './test/**/*.spec.js'","test:file":"npx mocha"},"author":{"name":"Amazon"},"keywords":["Alexa","Skill","APL","SDK","Litexa"],"license":"Apache-2.0","dependencies":{"rollup":"1.10.1","rollup-plugin-commonjs":"9.3.4","rollup-plugin-node-resolve":"4.2.3"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"homepage":"https://litexa.com","gitHead":"1433954be45b5d6dabe3a3282775c30830858395","_id":"@litexa/apl@0.9.0","_nodeVersion":"14.18.3","_npmVersion":"8.15.0","dist":{"integrity":"sha512-3gy8kHLDokkS567XwfbaTMieFunOTyH4nGWN+UTRUgh3YcH52enqMdYdVJKrglUIlk1Ipy4VQdtT2DjnuVJ8uQ==","shasum":"57c488588263129d48c43b2a454e6b5c312c9f38","tarball":"https://registry.npmjs.org/@litexa/apl/-/apl-0.9.0.tgz","fileCount":29,"unpackedSize":124629,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQC4iB0I/uRfPuC3FOMVhNEHgty1W2+ONAOikXJKyMbZJAIhAL/nfhGGnm9TiuOscuMIy17W2W0zFtrf65pQLQ7Tj55w"}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJkQwBnACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmqomxAAn9BB68rmEk3R/hDvba16LvkfI0fXYdkstjcxF8Qf8xqKPnyh\r\nM5NgS5F4pxNezGJInmCDpKBrribPA1DEgcQ6vZVpwbRnG2EKgdVk7gE1AUpV\r\n5vB88K+w/6XHrPJyIvwVv+52wYjcSelx8o1nALNxTIexJ+nliSDt3o5PFnt4\r\nlPyFIfvH3SeSf336FMM6II3e5op9fR3+NhLdySjUY4i7a6IHjm2XpF6EMmUc\r\nRYAeOaPE6+rMSWpUDngDbZAxMEuH0sFBX/dX/ZayWkABKzbVpOEpyF1YrqhN\r\nW9yifkydIi8xIBOhPGKIP09ZyWkVjwWhpmP8AmjkR+deJoPUeDLWdmkONmUH\r\nJPprRrsKw5KBGdi41uyXt5uNna6qv2sIIlvSyH55Bstca+7iHrHgGwf3l097\r\nwj2waZddb2U9Cmf0LFjfRYvHRlWYkJkk8YrakVanf1csfwxHfUUQDTX4YvNy\r\nc9Q8Vq+JbPDHj8D/6oKQp85TvN6xoHBKrH5IVoZtoMfr1nTO+IXbKnmOO9Mq\r\ncEoxYX2ZLxWrM98UqXWwuqY0SO0rwzb+cKATz3ECowumoWxnlp4k24mvrMSU\r\nOSeN24TtViBhV7C2pDmymUCq4gtWitznNN/Qu1K9DgL4hUPc7YbsXJf4+rjA\r\nXgrlCuMQJd/d8Tv+f7QQymhKuWyDSdEd664=\r\n=IyE3\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"alexa-games-builder","email":"alexa-games-npm-builders@amazon.com"},"directories":{},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builders@amazon.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/apl_0.9.0_1682112615109_0.025558987252411347"},"_hasShrinkwrap":false,"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."}},"time":{"created":"2019-05-03T19:28:39.574Z","0.0.2":"2019-05-03T19:28:39.735Z","modified":"2023-04-21T21:34:54.525Z","0.0.3":"2019-05-03T22:08:36.171Z","0.1.1":"2019-05-06T19:08:26.018Z","0.1.4-nightly.110967595.1":"2019-05-07T22:33:48.884Z","0.1.4-nightly.111120854.1":"2019-05-08T22:35:50.511Z","0.1.4-nightly.111132236.2":"2019-05-09T01:25:51.864Z","0.1.4":"2019-05-09T21:49:11.463Z","0.1.5-nightly.112154138.0":"2019-05-16T23:05:39.841Z","0.1.5-nightly.112295593.0":"2019-05-17T23:06:54.780Z","0.1.5-nightly.112335225.0":"2019-05-18T23:05:32.856Z","0.1.5-nightly.112374729.0":"2019-05-19T23:05:50.241Z","0.1.5-nightly.112519784.0":"2019-05-20T23:07:10.413Z","0.1.5-nightly.112682969.0":"2019-05-21T23:07:49.674Z","0.1.5":"2019-05-22T21:29:40.633Z","0.1.6-nightly.116497869.0":"2019-06-21T23:43:20.611Z","0.1.6-nightly.116537503.0":"2019-06-22T23:21:54.788Z","0.1.6-nightly.116575979.0":"2019-06-23T23:23:43.112Z","0.1.6-nightly.116725281.0":"2019-06-24T23:24:51.589Z","0.1.6-nightly.116894862.0":"2019-06-25T23:25:02.177Z","0.1.6-nightly.117061114.0":"2019-06-26T23:24:33.884Z","0.1.6":"2019-07-04T00:06:47.890Z","0.1.7-nightly.118656676.0":"2019-07-10T18:52:35.822Z","0.1.7-nightly.118827687.0":"2019-07-11T18:45:11.427Z","0.1.7-nightly.118977469.0":"2019-07-12T18:42:49.235Z","0.1.7-nightly.119038144.0":"2019-07-13T18:42:52.960Z","0.1.7-nightly.119075289.0":"2019-07-14T18:42:03.831Z","0.1.7-nightly.119201138.0":"2019-07-15T18:43:45.954Z","0.1.7-nightly.119523712.0":"2019-07-17T18:47:37.063Z","0.1.7-nightly.119894509.3":"2019-07-20T18:46:14.754Z","0.1.7-nightly.119933063.3":"2019-07-21T18:47:07.839Z","0.1.7-nightly.120058190.3":"2019-07-22T18:48:37.178Z","0.1.7-nightly.120260087.3":"2019-07-23T18:52:13.557Z","0.1.7-nightly.120755988.3":"2019-07-25T18:52:29.858Z","0.1.7-nightly.120897975.3":"2019-07-26T18:50:33.053Z","0.1.7-nightly.120951880.3":"2019-07-27T18:50:23.702Z","0.1.7-nightly.120985351.3":"2019-07-28T18:50:26.386Z","0.1.7-nightly.121138444.4":"2019-07-29T18:51:58.480Z","0.1.7-nightly.121301407.4":"2019-07-30T18:52:07.002Z","0.1.7-nightly.121465221.4":"2019-07-31T18:51:54.481Z","0.1.7-nightly.121654298.4":"2019-08-01T18:52:22.609Z","0.1.7-nightly.121796953.4":"2019-08-02T18:55:41.077Z","0.1.7-nightly.121850486.4":"2019-08-03T18:55:04.928Z","0.1.7-nightly.121882823.4":"2019-08-04T18:55:48.161Z","0.1.7-nightly.122004222.4":"2019-08-05T19:35:07.893Z","0.1.7-nightly.122490147.7":"2019-08-08T18:56:15.251Z","0.1.7-nightly.122635955.7":"2019-08-09T18:56:07.623Z","0.1.7-nightly.122691933.7":"2019-08-10T18:56:44.581Z","0.1.7-nightly.122723633.7":"2019-08-11T18:56:55.591Z","0.1.7-nightly.122873740.7":"2019-08-12T18:57:56.979Z","0.1.7-nightly.123051848.7":"2019-08-13T18:59:45.621Z","0.1.7-nightly.123273511.7":"2019-08-14T19:00:34.198Z","0.1.7-nightly.123413273.7":"2019-08-15T18:59:48.293Z","0.2.0":"2019-09-19T01:14:37.384Z","0.3.0":"2019-10-12T00:21:31.824Z","0.3.1":"2019-10-14T22:57:10.951Z","0.3.2-nightly.143460678.10":"2020-01-07T20:19:41.076Z","0.3.2-nightly.143626239.10":"2020-01-08T20:19:34.531Z","0.3.2-nightly.144576404.16":"2020-01-15T20:22:59.737Z","0.3.2-nightly.144807869.16":"2020-01-16T20:22:26.782Z","0.4.0":"2020-01-30T00:35:18.200Z","0.4.2-nightly.157326457.1":"2020-03-31T21:02:10.960Z","0.5.0":"2020-04-01T21:50:34.146Z","0.5.1":"2020-06-12T22:13:19.474Z","0.6.0":"2020-06-16T02:13:06.177Z","0.7.0":"2020-10-02T22:34:48.236Z","0.7.2":"2020-12-29T23:29:38.780Z","0.8.0":"2022-01-24T20:52:15.550Z","0.9.0":"2023-04-21T21:30:15.339Z"},"maintainers":[{"name":"alexa-games-admin","email":"alexa-games-npm-admins@amazon.com"},{"name":"alexa-games-builder","email":"alexa-games-npm-builders@amazon.com"}],"description":"This module adds support for APL directives to Litexa.","homepage":"https://litexa.com","keywords":["Alexa","Skill","APL","SDK","Litexa"],"repository":{"type":"git","url":"git+https://github.com/alexa-games/litexa.git"},"author":{"name":"Amazon"},"bugs":{"url":"https://github.com/alexa-games/litexa/issues"},"license":"Apache-2.0","readme":"# Litexa APL\n\nThe [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\nsupports curating visual experiences on compatible Alexa-enabled screen devices.\n\n## APL Directives\n\nThere are two different APL directives:\n\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html):\nSends a required `document` with graphical layouts and components, and optional `datasources`.\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html):\nSends one or more `commands`, which are tied to a `document` (in the same or a past response),\nand execute in sequence upon arrival.\n\nThis module supports easily building, sending, and validating APL directives. Please find the information on how to\ninstall and use this module (along with some general APL usage information) below.\n\n**WARNING**: The [Display.RenderTemplate](https://developer.amazon.com/docs/custom-skills/display-interface-reference.html)\ndirective (as supported by the `@litexa/render-template` extension) is not compatible with these APL directives.\nThe two can still both be used in the same skill, as long as they aren't sent in the same response. If they are,\nthe APL directive(s) will take precedence and the `Display.RenderTemplate` directive will be removed!\n\n## Installation\n\nThe module can be installed globally, which makes it available to any of your Litexa projects:\n\n```bash\nnpm install -g @litexa/apl\n```\n\nIf you alternatively prefer installing the extension locally inside your Litexa project for the sake of tracking the\ndependency, just run the following inside of your Litexa project directory:\n\n```bash\nnpm install --save @litexa/apl\n```\n\nThis should result in the following directory structure:\n\n```stdout\nproject_dir\n├── litexa\n└── node_modules\n    └── @litexa\n        └── apl\n```\n\n## New Statement\n\nWhen installed, the module adds a new `apl` statement to Litexa's syntax, which can be used to build and send APL\ndirectives from within Litexa.\n\nThe `apl` statement supports the following attributes:\n\n* `document` ... requires a [Document](#document) `object`\n* `data` ... requires a [Data](#data) `object`\n* `commands` ... requires either a single `object` or `array` of [Commands](#commands) `objects`\n* `token` ... requires a `String` identifier to be attached to the APL directives\n\nThere are two options for supplying the objects required by `document`, `data`, and `commands`:\n\n1. Use a (quoted or unquoted) path to a JSON file. This path should be relative to your skill's `litexa` directory.\nDoing this will assign the JSON file's contents to the indicated attribute (and throw a compile-time error, if the\nfile can't be found). This option is meaningful for anything static (e.g. a fixed `document`).\n\n    For example, assuming the following project structure:\n\n    ```stdout\n    project_dir\n    └── litexa\n        └── my_doc.json\n        └── apl\n            └── my_data.json\n    ```\n\n    The above files could be referenced like so:\n\n    ```coffeescript\n      apl\n        document: my_doc.json\n        data: apl/my_data.json\n    ```\n\n2. Use a function in external code to generate the `object`/`array` and supply the output. This option is meaningful\nfor anything dynamic (e.g. `data` or `commands` which depend on certain parameters).\n\n    ```javascript\n      function generateMyData(args) {\n        // ...\n      }\n    ```\n\n    ```coffeescript\n      local myData = generateMyData(args)\n      apl\n        data: myData\n    ```\n\nMore information on how to use each of these attributes is provided below.\n\n### Document\n\nAs a reminder, every `APL.RenderDocument` directive is required to have a document (this means sending only data is not\npossible).\n\nHere's an example for sending a `document` with minimal properties via `apl`.\n\n```coffeescript\napl my_doc.json\n\n# The above shorthand for specifying a document is equivalent to:\napl\n  document: my_doc.json\n```\n\n```json\n// my_doc.json\n{\n  \"type\": \"APL\",\n  \"version\": \"1.0\",\n  \"mainTemplate\": {\n    // required components for APL to inflate on the device upon activation\n  }\n}\n```\n\n**TIP:** `apl` will automatically add default values for `type` and `version`, if missing.\n\nBeyond the required `mainTemplate`, a `document` can optionally include `import`, `resources`, `styles`, and `layouts`.\nFor more information on these, please refer to the official\n[APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html) documentation.\n\n**TIP:** If you prefer, you can specify a `document` that wraps either or both of `document` and `data`. This is also\nthe format provided by any [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?) exports, so\ndirectly referencing any exported examples as your `document` will work.\n\n```json\n// my_doc.json:\n{\n  \"document\": {\n    // your APL document\n  },\n  \"data\": { // or alias: \"datasources\"\n    // your APL data\n  }\n}\n```\n\n**TIP:** To customize behavior per device, you can use the data-bound `viewport` variable in `when` conditionals,\nto check device properties. Here are a couple examples:\n\n```json\n\"resources\": [\n  {\n    \"description\": \"Stock color for the light theme\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#151920\"\n    }\n  },\n  {\n    \"description\": \"Stock color for the dark theme\",\n    \"when\": \"${viewport.theme == 'dark'}\",\n    \"colors\": {\n      \"colorTextPrimary\": \"#f0f1ef\"\n    }\n  }\n]\n\"layouts\": {\n  \"items\": [\n    {\n      \"when\": \"${viewport.shape == 'round'}\",\n      \"type\": \"Container\",\n      (...)\n      // use this container, if running on the Echo Spot\n    }\n    {\n      \"type\": \"Container\",\n      (...)\n      // otherwise, use this container\n    }\n  ]\n}\n```\n\nFor more information on `viewport` and which characteristics of the display device it includes, please refer to the\n[Viewport Property](https://developer.amazon.com/docs/alexa-presentation-language/apl-viewport-property.html)\ndocumentation.\n\n### Data\n\nAs a reminder, every `APL.RenderDocument` directive can optionally include \"datasources\". This data is a collection of\nskill-author defined objects which can then be referenced in an APL document's components.\n\nHere's an example of sending some `data` via `apl`, and using it in a `document`:\n\n```coffeescript\napl\n  document: my_doc.json\n  data: my_data.json\n```\n\n```json\n// my_data.json\n// datasources:\n{\n  \"myDataObject\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"title\": \"This is myDataObject's title.\"\n    }\n  }\n}\n```\n\nThe above `data` is then accessed with the parameter `payload`:\n\n```json\n// my_doc.json\n// document:\n{\n  \"mainTemplate\": {\n    \"parameters\": [\n      \"payload\"\n    ],\n    \"item\": {\n      \"type\": \"Text\",\n      \"text\": \"${payload.myDataObject.title}\"\n    }\n  }\n}\n```\n\n**WARNING:** The data reference \"payload\" is the default, but could be replaced with any `String`. However, it is\nimportant to only have a single `String` in `parameters` (adding anything else will break the document).\n\nFor more information on what kind of `data` you can use, please refer to the\n[APL Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\ndocumentation.\n\n### Commands\n\nAs a reminder, the `APL.ExecuteCommands` directive is sent with a single command `object`, or an `array`\nof multiple commands. These commands are then executed in sequence.\n\nHere's an example of using `commands` via `apl`, to show pages in a `document`'s `Pager`:\n\n```coffeescript\napl\n  document: my_pager.json\n  commands: pager_commands.json\n```\n\n```json\n// my_pager.json:\n{\n  \"mainTemplate\": {\n    \"item\": [\n      {\n        \"type\": \"Pager\",\n        \"id\": \"pagerComponentId\",\n        \"items\": [\n          {\n            \"type\": \"Text\",\n            \"text\": \"Page 1\" // page 1 will inflate first\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          },\n          {\n            \"type\": \"Text\",\n            \"hint\": \"Page 2\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n```json\n// pager_commands.json\n[\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 1 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\", // above Pager's ID\n    \"value\": 2 // turn to page 2\n  },\n  {\n    \"type\": \"Idle\",\n    \"delay\": 2000 // let page 2 show for 2 secs\n  },\n  {\n    \"type\": \"SetPage\",\n    \"componentId\": \"pagerComponentId\",\n    \"value\": 3 // turn to page 3\n  }\n]\n```\n\n**TIP:** You can send `commands` without a `document` or `data`. If a `document` is active on the device, the `commands`\nwill execute accordingly. Otherwise, they will be ignored.\n\nThis means you can send a `document` at some point in your skill, and then choose to send detached `commands`\nin future responses.\n\n### Tokens\n\nThe `apl` `token` defaults to \"DEFAULT_TOKEN\", if not specified. It's important to note that an `ExecuteCommands`\ndirective's token must match the displaying `RenderDocument`'s token for the commands to run.\n\n**WARNING:** As of March 2018, commands with tokens not matching the active document incorrectly do work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They are properly suppressed\non APL-compatible devices.\n\nAdditional to insuring that `commands` only run atop the intended `document`, tokens can also be used to allocate\n[User Events](#user-events), as demonstrated farther below.\n\n### Merging Fragments\n\nThe `apl` statement supports aggregating multiple instances of `document`, `data`, `commands`. What does this mean?\nIf your skill encounters multiple `apl` statements before sending a response (e.g. `apl` statements in different\n`states`), it will aggregate any such \"fragments\" before sending them in APL directives. Here's an example:\n\n```coffeescript\nstateOne\n  apl doc_one.json\n    data: data_one.json\n    commands: commands_one.json\n  -> stateOne\nstateTwo\n  apl doc_two.json\n    data: data_two.json\n    commands: commands_two.json\n  -> stateThree\nstateThree\n  apl\n    document: [\"doc_three.json\"]\n    data: data_three.json\n    commands: commands_three.json\n\n# The above state sequence would merge all three documents,\n# data, and commands prior to sending the response.\n```\n\nThis behavior is useful for adding state-specific content or instructions to your skill's APL behavior, or\ninterleaving `commands` with Litexa `say` or `soundEffect` statements.\n\n**WARNING:** Since the `document` can only meaningfully have one `mainTemplate` (i.e. active template), any\nconsecutively encountered `document` fragments that have a `mainTemplate` will overwrite the previous `mainTemplate`\n(with a logged warning)!\n\nMake sure any possible state flow with at least one `apl` `document` always finds a valid `mainTemplate`, and wouldn't\naccidentally overwrite a previous `document`'s required `mainTemplate`.\n\n**NOTE:** If a Litexa state flow encounters consecutive `apl` `token`s prior to sending a response, it will simply use the\nlatest.\n\n### Referencing Assets\n\nBeyond using existing URLs, it is possible to reference `assets` files in any `apl` `document` or `data`.\nTo do so, simply add the placeholder prefix `assets://` to your file's name. For example:\n\n```json\n  {\n    \"type\": \"Image\",\n    \"source\": \"assets://my_image.jpg\",\n    \"width\": 300,\n    \"height\": 300\n  }\n```\n\nAssuming there's a `my_image.jpg` in your `assets` directory, the above reference would then be replaced with the\nS3 link of the deployed file.\n\n### Interleaving Sound\n\nLitexa's `say` and `soundEffect` are usually added to the response\n[outputSpeech](https://developer.amazon.com/docs/custom-skills/request-and-response-json-reference.html#outputspeech-object).\nHowever, any `outputSpeech` is spoken *before* APL commands are executed.\n\nUsing the `apl` statement, if a `document` is pending, `say` and `soundEffect` will be converted to APL commands and\ninterleave in the expected sequence. For example:\n\n```coffeescript\napl\n  document: apl_doc.json\n  data: apl_data.json\n  commands: apl_commands.json\n\nsay \"turning page\"\napl\n  commands: turn_page.json\n\nsoundEffect page_chime.mp3\nsay \"page turned\"\n```\n\nwould produce the following output sequence:\n\n1. APL would execute commands in `apl_commands.json`\n2. Alexa would say \"turning page\"\n3. APL would execute commands in `turn_page.json`\n4. Alexa would play the sound effect `page_chime.mp3`\n5. Alexa would say \"page turned\"\n\n**NOTE:** The above sequencing will only take place if a `document` is found before sending the response.\n\nReason: Converting any sound output to APL requires insertions in the `document`. Creating a new `document` to\naccomplish this might unintentionally replace an active `document` on the device.\n\nSummary: If no `document` is pending, no interleaving will take place, and any `say` or `soundEffect` will normally\nplay through `outputSpeech`. In the above example, if no `apl` `document` were defined, the output sequence would be\n2-4-5-1-3.\n\n**WARNING:** As of March 2018, sound effects incorrectly do not work on the\n[ASK Developer Console](https://developer.amazon.com/alexa/console/ask). They do however work on APL-compatible devices.\n\n## User Events\n\nAPL can trigger user events back to the skill when the user presses an on-screen\n[TouchWrapper](https://developer.amazon.com/docs/alexa-presentation-language/apl-touchwrapper.html).\nHere's an example:\n\n```json\n{\n  \"type\": \"TouchWrapper\",\n  \"id\": \"My Touchable\",\n  \"item\": {\n    \"type\": \"Text\",\n    \"text\": \"I am a touchable that will send an event back to the skill.\"\n  },\n  \"onPress\": {\n      \"type\": \"SendEvent\",\n      \"arguments\": [\n          \"I am coming from My Touchable.\"\n      ]\n  }\n}\n```\n\nA skill user touching the touchable would then trigger this `Alexa.Presentation.APL.UserEvent`:\n\n```json\n{\n  \"type\": \"Alexa.Presentation.APL.UserEvent\",\n  \"requestId\": \"...\",\n  \"timestamp\": \"...\",\n  \"locale\": \"en-US\",\n  \"arguments\": [\n      \"I am coming from My Touchable.\"\n  ],\n  \"components\": {},\n  \"source\": {\n      \"type\": \"TouchWrapper\",\n      \"handler\": \"Press\",\n      \"id\": \"My Touchable\",\n      \"value\": false\n  },\n  \"token\": \"This is the token of the APL document that sourced this event.\"\n}\n```\n\nYou can optionally handle any such user events in your code with something like:\n\n```coffeescript\n## In litexa:\nwhen Alexa.Presentation.APL.UserEvent\n  handleUserEvent($request)\n```\n\n```javascript\n// In your external code (e.g. JavaScript):\nfunction handleUserEvent(request) {\n  switch(request.token) {\n    // could ignore a token from an outdated document\n  }\n  switch(request.source.id) {\n    // could trigger behavior specific to this touchable\n    // (e.g. send command to scroll a visible list)\n  }\n  switch(request.arguments) {\n    // could send and evaluate something like data-bound arguments\n  }\n}\n```\n\n## Intent Handling Requirements\n\nWhen using an APL directive, the built-in `AMAZON.HelpIntent` must be handled by the skill (i.e. included in at\nleast one `when` listener). This can be done via state-specific handlers, or a `global` handler:\n\n```coffeescript\nglobal\n  when AMAZON.HelpIntent\n    -> helpState\n```\n\n## Checking APL Support\n\nIf APL is not supported on the device running your skill, any `apl` statements will be ignored, and everything else\nwill work normally (e.g. `say` and `soundEffect` will run via `outputSpeech` instead of APL commands).\n\nTo check APL support at runtime, the following command can be used from within Litexa or external code:\n\n```coffeescript\nif APL.isEnabled()\n  # say \"APL is supported on this device.\"\nelse\n  # say \"APL is not supported on this device.\"\n```\n\n**TIP:** This availability check should be used to curate any skill for both APL and non-APL devices.\n\n## Relevant Resources\n\nFor more information, please refer to the official APL documentation:\n\n* [Alexa Presentation Language](https://developer.amazon.com/docs/alexa-presentation-language/apl-overview.html)\n* [Render Document Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-render-document-skill-directive.html)\n* [Data Sources and Transformers](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-source.html)\n* [Execute Commands Directive](https://developer.amazon.com/docs/alexa-presentation-language/apl-execute-command-directive.html)\n* [APL Document](https://developer.amazon.com/docs/alexa-presentation-language/apl-document.html)\n* [APL Data Types](https://developer.amazon.com/docs/alexa-presentation-language/apl-data-types.html)\n* [APL Standard Commands](https://developer.amazon.com/docs/alexa-presentation-language/apl-standard-commands.html)\n* [APL Authoring Tool](https://developer.amazon.com/alexa/console/ask/displays/?)\n","readmeFilename":"README.md"}