├── .node-version ├── .browserslistrc ├── .babelrc ├── src ├── translations │ ├── zh-cn.json │ ├── fr.json │ └── en.json ├── images │ ├── dots.gif │ ├── logo.png │ ├── spinner.gif │ ├── logo-small.png │ └── logo.svg ├── index.css ├── javascripts │ ├── locations │ │ └── ticket_sidebar.js │ ├── lib │ │ ├── helpers.js │ │ └── i18n.js │ └── modules │ │ └── app.js ├── templates │ └── iframe.html └── manifest.json ├── .gitignore ├── .github ├── CODEOWNERS ├── workflows │ ├── codeql.yaml │ └── actions.yml └── pull_request_template.md ├── postcss.config.js ├── .travis.yml ├── spec ├── polyfills │ └── createRange.js ├── mocks │ └── mock.js ├── helpers.spec.js ├── i18n.spec.js └── app.spec.js ├── jest.config.js ├── DEPLOY.md ├── webpack ├── translations-loader.js └── translations-plugin.js ├── doc ├── adrs │ └── replace-migration-scaffold-with-clean-scaffold-in-master-branch.md └── i18n.md ├── webpack.config.js ├── package.json ├── README.md └── LICENSE /.node-version: -------------------------------------------------------------------------------- 1 | 18.12.1 2 | -------------------------------------------------------------------------------- /.browserslistrc: -------------------------------------------------------------------------------- 1 | # Browsers that we support 2 | last 2 version 3 | -------------------------------------------------------------------------------- /.babelrc: -------------------------------------------------------------------------------- 1 | { 2 | "presets": ["@babel/preset-env", "@babel/preset-react"] 3 | } 4 | -------------------------------------------------------------------------------- /src/translations/zh-cn.json: -------------------------------------------------------------------------------- 1 | { 2 | "default": { 3 | "organizations": "组织" 4 | } 5 | } -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | tmp/ 2 | dist/ 3 | node_modules/ 4 | coverage/ 5 | npm-debug.log 6 | yarn-error.log 7 | -------------------------------------------------------------------------------- /src/images/dots.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zendesk/app_scaffold/master/src/images/dots.gif -------------------------------------------------------------------------------- /src/images/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zendesk/app_scaffold/master/src/images/logo.png -------------------------------------------------------------------------------- /src/images/spinner.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zendesk/app_scaffold/master/src/images/spinner.gif -------------------------------------------------------------------------------- /src/translations/fr.json: -------------------------------------------------------------------------------- 1 | { 2 | "default": { 3 | "organizations": "organizations" 4 | } 5 | } -------------------------------------------------------------------------------- /src/images/logo-small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zendesk/app_scaffold/master/src/images/logo-small.png -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # CODEOWNERS file 2 | # This file defines who should review code changes in this repository. 3 | 4 | * @zendesk/wattle 5 | -------------------------------------------------------------------------------- /postcss.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | plugins: [ 3 | require('postcss-preset-env'), 4 | require('postcss-import') 5 | ] 6 | } 7 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | node_js: 3 | - "6.11.5" 4 | cache: yarn 5 | branches: 6 | only: [master] 7 | script: yarn test 8 | dist: trusty 9 | -------------------------------------------------------------------------------- /src/index.css: -------------------------------------------------------------------------------- 1 | .loader { 2 | left: 50%; 3 | position: absolute; 4 | top: 50%; 5 | transform: translate(-50%, -50%); 6 | width: 40px; 7 | } 8 | 9 | -------------------------------------------------------------------------------- /src/javascripts/locations/ticket_sidebar.js: -------------------------------------------------------------------------------- 1 | // need to import basic garden css styles 2 | import '@zendeskgarden/css-bedrock' 3 | 4 | import App from '../modules/app' 5 | 6 | /* global ZAFClient */ 7 | const client = ZAFClient.init() 8 | 9 | client.on('app.registered', function (appData) { 10 | return new App(client, appData) 11 | }) 12 | -------------------------------------------------------------------------------- /spec/polyfills/createRange.js: -------------------------------------------------------------------------------- 1 | // jsdom createRange polyfill 2 | export default () => { 3 | document.createRange = () => ({ 4 | createContextualFragment: (templateString) => { 5 | const template = document.createElement('template') 6 | template.innerHTML = templateString 7 | return template.content 8 | } 9 | }) 10 | } 11 | -------------------------------------------------------------------------------- /jest.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | verbose: true, 3 | testEnvironmentOptions: { 4 | url: 'http://localhost/' 5 | }, 6 | testEnvironment: 'jsdom', 7 | collectCoverage: true, 8 | globals: { 9 | ZAFClient: { 10 | init: () => {} 11 | } 12 | }, 13 | coveragePathIgnorePatterns: [ 14 | '/spec' 15 | ], 16 | roots: ['./spec'] 17 | } 18 | -------------------------------------------------------------------------------- /src/translations/en.json: -------------------------------------------------------------------------------- 1 | { 2 | "app": { 3 | "name": "Example App", 4 | "short_description": "Short Description", 5 | "long_description": "Long Description", 6 | "installation_instructions": "Configure the following app settings, then click Install:...", 7 | "title": "Example App" 8 | }, 9 | "default": { 10 | "organizations": "organizations" 11 | } 12 | } -------------------------------------------------------------------------------- /src/templates/iframe.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
10 | 11 |
12 | <% _.forEach(htmlWebpackPlugin.options.vendorJs, function(js) { %><% }); %> 13 | 14 | 15 | -------------------------------------------------------------------------------- /src/manifest.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "Example App", 3 | "author": { 4 | "name": "John Doe", 5 | "email": "support@zendesk.com", 6 | "url": "https://www.zendesk.com" 7 | }, 8 | "defaultLocale": "en", 9 | "private": true, 10 | "location": { 11 | "support": { 12 | "ticket_sidebar": { 13 | "url": "assets/iframe.html", 14 | "flexible": true 15 | } 16 | } 17 | }, 18 | "version": "1.0", 19 | "frameworkVersion": "2.0" 20 | } 21 | -------------------------------------------------------------------------------- /DEPLOY.md: -------------------------------------------------------------------------------- 1 | Note: Run commands in the root app directory. 2 | 3 | Compile the app for DEV 4 | =============== 5 | 1) `yarn install` 6 | 2) `yarn run watch` 7 | 3) Open a new command line window in the root app directory 8 | 4) `zat server -p dist` - Serves the app to your Zendesk instance with `?zat=true` 9 | 10 | Compile the app for PROD 11 | =============== 12 | 1) `yarn install` 13 | 2) `yarn run build` 14 | 15 | To run the tests 16 | =============== 17 | 1) `yarn install` 18 | 2) `yarn test` 19 | -------------------------------------------------------------------------------- /.github/workflows/codeql.yaml: -------------------------------------------------------------------------------- 1 | name: "CodeQL public repository scanning" 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | - master 8 | schedule: 9 | - cron: "0 0 * * *" 10 | pull_request_target: 11 | types: [opened, synchronize, reopened] 12 | workflow_dispatch: 13 | 14 | permissions: 15 | contents: read 16 | security-events: write 17 | actions: read 18 | packages: read 19 | 20 | jobs: 21 | trigger-codeql: 22 | uses: zendesk/prodsec-code-scanning/.github/workflows/codeql_advanced_shared.yml@production 23 | -------------------------------------------------------------------------------- /spec/mocks/mock.js: -------------------------------------------------------------------------------- 1 | export const CLIENT = { 2 | _origin: 'zendesk.com', 3 | get: (prop) => { 4 | if (prop === 'currentUser') { 5 | return Promise.resolve({ 6 | currentUser: { 7 | locale: 'en', 8 | name: 'Sample User' 9 | } 10 | }) 11 | } 12 | return Promise.resolve({ 13 | [prop]: null 14 | }) 15 | } 16 | } 17 | 18 | export const ORGANIZATIONS = { 19 | organizations: [ 20 | { id: 1, name: 'Organization A' }, 21 | { id: 2, name: 'Organization B' } 22 | ], 23 | next_page: null, 24 | previous_page: null, 25 | count: 1 26 | } 27 | -------------------------------------------------------------------------------- /src/images/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 4 | 6 | 8 | 10 | 11 | -------------------------------------------------------------------------------- /.github/workflows/actions.yml: -------------------------------------------------------------------------------- 1 | name: repo-checks 2 | 3 | on: 4 | pull_request: 5 | push: 6 | branches: 7 | - master 8 | 9 | jobs: 10 | main: 11 | name: nodejs 12 | runs-on: ubuntu-latest 13 | env: 14 | NPM_CONFIG_PROGRESS: "false" 15 | DISABLE_SPRING: 1 16 | steps: 17 | - uses: zendesk/checkout@v2 18 | - uses: zendesk/setup-node@v3 19 | with: 20 | node-version: 18.12.1 21 | - name: before_install 22 | run: | 23 | # clear out node binstubs before rvm fetches ruby 24 | # c.f. https://github.com/travis-ci/travis-ci/issues/5092 25 | rm -f ui/node_modules/.bin/which 26 | npm set config progress false 27 | npm set config color false 28 | - name: lint_and_tests 29 | run: | 30 | yarn install 31 | yarn lint 32 | yarn test 33 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | (Title field) 2 | [OFFAPPS-XXX] Short description 3 | 4 | ## Description 5 | Develop what, but also why this PR exists. The "Why" is as much, if not more important than the "What". I use this approach very often when I write commit messages, because if the code is clear enough it should already answer the "what" question. The "why" is often more subtle. 6 | 7 | ## Tasks 8 | - [ ] Write tests 9 | 10 | ## Implementation notes 11 | I don't always use this section, but I do when I find there's something particularly tricky end/or nifty in the code. 12 | 13 | ## References 14 | [Support ticket](https://subdomain.zendesk.com/xxxx) 15 | [Jira story](https://subdomain.atlassian.net/browse/BUG-1) 16 | [Invision design](https://google.com) 17 | 18 | ## Screenshots (if needed) 19 |
20 | Screenshot 1 21 | 22 |
23 | 24 |
25 | Screenshot 2 26 | 27 |
28 | 29 | ## CCs 30 | Anyone specific? 31 | Unless there's a good reason not to: 32 | @zendesk/apps-migration 33 | If translation-related: 34 | @zendesk/localization 35 | 36 | ## Risks 37 | * [HIGH | medium | low] Does it work across browsers (including IE!)? 38 | * [HIGH | medium | low] Does it work in the different products (Support, Chat, Connect)? 39 | * [HIGH | medium | low] Are there any performance implications? 40 | * [HIGH | medium | low] Any security risks? 41 | * [HIGH | medium | low] What features does this touch? 42 | -------------------------------------------------------------------------------- /webpack/translations-loader.js: -------------------------------------------------------------------------------- 1 | /** 2 | * { 3 | * name: 'test app', 4 | * author: { 5 | * title: 'the author', 6 | * value: 'mr programmer' 7 | * }, 8 | * app: { 9 | * instructions: 'install', 10 | * steps: { 11 | * click: 'this button' 12 | * } 13 | * } 14 | * } 15 | * 16 | * becomes 17 | * 18 | * { 19 | * name: 'test app', 20 | * author: 'mr programmer', 21 | * app.instructions: 'install', 22 | * app.steps.click: 'this button' 23 | * } 24 | */ 25 | /* eslint-disable array-callback-return */ 26 | function translationFlatten (object, currentKeys = []) { 27 | const res = {} 28 | 29 | Object.keys(object).map( 30 | key => { 31 | const value = object[key] 32 | 33 | if (typeof value === 'object') { 34 | if (value.title && value.value) { 35 | const flattenedKey = [...currentKeys, key].join('.') 36 | res[flattenedKey] = value.value 37 | } else { 38 | Object.assign( 39 | res, 40 | translationFlatten(value, [...currentKeys, key]) 41 | ) 42 | } 43 | } else { 44 | const flattenedKey = [...currentKeys, key].join('.') 45 | res[flattenedKey] = value 46 | } 47 | } 48 | ) 49 | 50 | return res 51 | } 52 | /* eslint-enable array-callback-return */ 53 | 54 | function TranslationsLoader (content) { 55 | let translationsInput 56 | try { 57 | translationsInput = JSON.parse(content) 58 | } catch (error) { 59 | console.error(error) 60 | process.exit(1) 61 | } 62 | 63 | const compiledTranslations = translationFlatten(translationsInput) 64 | 65 | return `module.exports = ${JSON.stringify(compiledTranslations)}` 66 | } 67 | 68 | module.exports = TranslationsLoader 69 | -------------------------------------------------------------------------------- /webpack/translations-plugin.js: -------------------------------------------------------------------------------- 1 | const path = require('path') 2 | const fs = require('fs') 3 | const JS_INDENT = 2 4 | 5 | const marketplaceKeys = [ 6 | 'name', 7 | 'description', 8 | 'short_description', 9 | 'long_description', 10 | 'installation_instructions', 11 | 'parameters' 12 | ] 13 | 14 | class TranslationsPlugin { 15 | constructor (options) { 16 | this.options = options 17 | } 18 | 19 | // Defines `apply` method in it's prototype. 20 | apply (compiler) { 21 | // Specifies webpack's event hook to attach itself. 22 | compiler.hooks.emit.tapAsync('TranslationsPlugin', (compilation, callback) => { 23 | Object.assign( 24 | compilation.assets, 25 | buildMarketplaceTranslationFile('en.json', this.options.path) 26 | ) 27 | callback() 28 | }) 29 | } 30 | } 31 | 32 | function buildMarketplaceTranslationFile (filename, filepath) { 33 | let translationsInput 34 | try { 35 | translationsInput = JSON.parse(fs.readFileSync(path.resolve(filepath, filename))) 36 | } catch (err) { 37 | console.error(err) 38 | process.exit(1) 39 | } 40 | 41 | const translationsPath = `../translations/${filename}` 42 | const marketplaceTranslations = extractMarketplaceTranslation(translationsInput, filename) 43 | 44 | return { 45 | [translationsPath]: { 46 | size: () => marketplaceTranslations.length, 47 | source: () => marketplaceTranslations 48 | } 49 | } 50 | } 51 | 52 | function extractMarketplaceTranslation (translations, filename) { 53 | const translationsOutput = { 54 | _warning: `AUTOMATICALLY GENERATED FROM $/src/translations/${filename} - DO NOT MODIFY THIS FILE DIRECTLY`, 55 | app: {} 56 | } 57 | 58 | marketplaceKeys.forEach( 59 | key => { 60 | if (translations.app[key]) translationsOutput.app[key] = translations.app[key] 61 | } 62 | ) 63 | 64 | return JSON.stringify(translationsOutput, null, JS_INDENT) 65 | } 66 | 67 | module.exports = TranslationsPlugin 68 | -------------------------------------------------------------------------------- /doc/adrs/replace-migration-scaffold-with-clean-scaffold-in-master-branch.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "ADR: Replace migration Scaffold with clean Scaffold in Master Branch" 3 | date: 2018-08-16 4 | draft: false 5 | status: "Accepted" 6 | --- 7 | 8 | # ADR: Replace migration Scaffold with clean Scaffold in Master Branch 9 | 10 | ## Context 11 | At the moment, the master branch has the scaffold specifically built to help developers migrate v1 apps to v2. From monitor, the majority usage comes from [App Migrator](https://github.com/zendesk/zendesk_app_migrator) and [ZAT](https://github.com/zendesk/zendesk_apps_tools) which use the master branch as the download source. 12 | It is more helpful to show developers coming directly to this repo a clean (from scratch) scaffold, one usable as a starting point to build new apps respecting our current conventions out of the box. 13 | 14 | ## Decision 15 | 16 | ### New app scaffold 17 | A new *clean* app scaffold has been built on branch [offapps-migration](https://github.com/zendesk/app_scaffold/tree/offapps-migration) based on branch [from-scratch](https://github.com/zendesk/app_scaffold/tree/from-scratch) 18 | 19 | ### Move migration scaffold into App Migrator repository 20 | Migration scaffold in master branch will be moved into [App Migrator](https://github.com/zendesk/zendesk_app_migrator), used and maintained as a *built-in* template resource 21 | 22 | ### Move new app scaffold to master branch 23 | 24 | ### Add support in [ZAT](https://github.com/zendesk/zendesk_apps_tools) to create new app with the new scaffold 25 | * New command option `zat new --scaffold` will create a v2 app using the new app scaffold. 26 | 27 | ## Status 28 | 29 | Accepted 30 | 31 | ## Consequences 32 | 33 | * Auto migration from v1 to v2 are completely handled by [App Migrator](https://github.com/zendesk/zendesk_app_migrator), no external resource required, maintenance of the scaffold template should be done in App Migrator repo 34 | * This repo is focusing on building/maintaining v2 app scaffolds for both external and internal use -------------------------------------------------------------------------------- /src/javascripts/lib/helpers.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Resize App container 3 | * @param {ZAFClient} client ZAFClient object 4 | * @param {Number} max max height available to resize to 5 | * @return {Promise} will resolved after resize 6 | */ 7 | export function resizeContainer (client, max = Number.POSITIVE_INFINITY) { 8 | const newHeight = Math.min(document.body.clientHeight, max) 9 | return client.invoke('resize', { height: newHeight }) 10 | } 11 | 12 | /** 13 | * Helper to render a dataset using the same template function 14 | * @param {Array} set dataset 15 | * @param {Function} getTemplate function to generate template 16 | * @param {String} initialValue any template string prepended 17 | * @return {String} final template 18 | */ 19 | export function templatingLoop (set, getTemplate, initialValue = '') { 20 | return set.reduce((accumulator, item, index) => { 21 | return `${accumulator}${getTemplate(item, index)}` 22 | }, initialValue) 23 | } 24 | 25 | /** 26 | * Render template 27 | * @param {String} replacedNodeSelector selector of the node to be replaced 28 | * @param {String} htmlString new html string to be rendered 29 | */ 30 | export function render (replacedNodeSelector, htmlString) { 31 | const fragment = document.createRange().createContextualFragment(htmlString) 32 | const replacedNode = document.querySelector(replacedNodeSelector) 33 | 34 | replacedNode.parentNode.replaceChild(fragment, replacedNode) 35 | } 36 | 37 | /** 38 | * Helper to escape unsafe characters in HTML, including &, <, >, ", ', `, = 39 | * @param {String} str String to be escaped 40 | * @return {String} escaped string 41 | */ 42 | export function escapeSpecialChars (str) { 43 | if (typeof str !== 'string') throw new TypeError('escapeSpecialChars function expects input in type String') 44 | 45 | const escape = { 46 | '&': '&', 47 | '<': '<', 48 | '>': '>', 49 | '"': '"', 50 | "'": ''', 51 | '`': '`', 52 | '=': '=' 53 | } 54 | 55 | return str.replace(/[&<>"'`=]/g, function (m) { return escape[m] }) 56 | } 57 | -------------------------------------------------------------------------------- /src/javascripts/lib/i18n.js: -------------------------------------------------------------------------------- 1 | import manifest from '../../manifest.json' 2 | 3 | // map to store the key/translation pairs of the loaded language 4 | let translations 5 | 6 | /** 7 | * Replace placeholders in the given string with context 8 | * @param {String} str string with placeholders to be replaced 9 | * @param {Object} context object contains placeholder/value pairs 10 | * @return {String} formatted string 11 | */ 12 | function parsePlaceholders (str, context) { 13 | const regex = /{{(.*?)}}/g 14 | const matches = [] 15 | let match 16 | 17 | do { 18 | match = regex.exec(str) 19 | if (match) matches.push(match) 20 | } while (match) 21 | 22 | return matches.reduce((str, match) => { 23 | const newRegex = new RegExp(match[0], 'g') 24 | return str.replace(newRegex, context[match[1]] || '') 25 | }, str) 26 | } 27 | 28 | class I18n { 29 | constructor (locale) { 30 | this.loadTranslations(locale) 31 | } 32 | 33 | tryRequire (locale) { 34 | try { 35 | return require(`../../translations/${locale}.json`) 36 | } catch (e) { 37 | return null 38 | } 39 | } 40 | 41 | /** 42 | * Translate key with currently loaded translations, 43 | * optional context to replace the placeholders in the translation 44 | * @param {String} key 45 | * @param {Object} context object contains placeholder/value pairs 46 | * @return {String} translated string 47 | */ 48 | t (key, context) { 49 | const keyType = typeof key 50 | if (keyType !== 'string') throw new Error(`Translation key must be a string, got: ${keyType}`) 51 | 52 | const template = translations[key] 53 | if (!template) throw new Error(`Missing translation: ${key}`) 54 | if (typeof template !== 'string') throw new Error(`Invalid translation for key: ${key}`) 55 | 56 | return parsePlaceholders(template, context) 57 | } 58 | 59 | loadTranslations (locale = 'en') { 60 | translations = this.tryRequire(locale) || 61 | this.tryRequire(locale.replace(/-.+$/, '')) || 62 | translations || 63 | this.tryRequire('en') 64 | } 65 | } 66 | 67 | export default new I18n(manifest.defaultLocale) 68 | -------------------------------------------------------------------------------- /doc/i18n.md: -------------------------------------------------------------------------------- 1 | ## Using the I18n module 2 | 3 | The I18n module provides a helper called `i18n.t` that you can use to localize your application. 4 | 5 | ### Setup 6 | 7 | Put a `defaultLocale` property into your `manifest.json` file, otherwise it will use english (en) 8 | 9 | Add your translation files as `src/translations/XX.json` where `XX` is a locale such as `en-US`, `de`, or `zh`. 10 | 11 | A simple translation file might look like this: 12 | 13 | ```json 14 | { 15 | "hello": "Hello!", 16 | "goodbye": "Bye {{name}}!", 17 | "formal": { 18 | "farewell": "Farewell, friend." 19 | } 20 | } 21 | ``` 22 | 23 | The "app" section in translation files is used *only* for public app listings in the Zendesk Marketplace. For these listings, we only allow English. The "app" sections in other translation files will be ignored. 24 | 25 | ### Initialization 26 | 27 | When you know which locale you want to use, call `i18n.loadTranslations(locale)` where `locale` is a string like `en-US`, `de`, `zh`. This will load the strings under the matching file in `src/translations`. For example, you could use 28 | 29 | ```javascript 30 | import i18n from 'i18n'; 31 | 32 | const zafClient = ZAFClient.init(); 33 | zafClient.get('currentUser.locale').then((data) => { 34 | const locale = data['currentUser.locale']; 35 | i18n.loadTranslations(locale); 36 | }); 37 | ``` 38 | 39 | ## Reference 40 | 41 | ### i18n.loadTranslations(locale) 42 | 43 | Sets the locale to be used by `i18n.t()` 44 | 45 | #### Arguments 46 | 47 | * `locale`: String representing the filename of the required translation JSON file. 48 | 49 | ### i18n.t(key, context) 50 | 51 | Returns a translated string using a key that is available in the relevant translation file (found in `src/translations/XX.json`). 52 | 53 | #### Arguments 54 | 55 | * `key`: The key assigned to the string in the JSON file. Dots may be used to access nested objects. 56 | * `context`: An object with named values to be interpolated into the resulting string. 57 | 58 | #### Returns 59 | 60 | A translated string generated by keying into the JSON file and interpolating any placeholders. 61 | 62 | #### Example 63 | 64 | ```javascript 65 | i18n.t('hello'); // returns "Hello!" 66 | i18n.t('goodbye', { name: 'Yak' }); // returns "Bye Yak!" 67 | i18n.t('formal.farewell'); // returns "Farewell, friend." 68 | ``` 69 | -------------------------------------------------------------------------------- /webpack.config.js: -------------------------------------------------------------------------------- 1 | const path = require('path') 2 | const { CleanWebpackPlugin } = require('clean-webpack-plugin') 3 | const CopyWebpackPlugin = require('copy-webpack-plugin') 4 | const MiniCssExtractPlugin = require('mini-css-extract-plugin') 5 | const HtmlWebpackPlugin = require('html-webpack-plugin') 6 | const TranslationsPlugin = require('./webpack/translations-plugin') 7 | 8 | const externalAssets = { 9 | js: [ 10 | 'https://assets.zendesk.com/apps/sdk/2.0/zaf_sdk.js' 11 | ] 12 | } 13 | 14 | module.exports = { 15 | entry: { 16 | app: [ 17 | '@babel/polyfill', 18 | './src/javascripts/locations/ticket_sidebar.js', 19 | './src/index.css' 20 | ] 21 | }, 22 | output: { 23 | filename: '[name].js', 24 | path: path.resolve(__dirname, 'dist/assets') 25 | }, 26 | module: { 27 | rules: [ 28 | { 29 | test: /\.js$/, 30 | exclude: /node_modules/, 31 | loader: 'babel-loader', 32 | options: { 33 | presets: ['@babel/preset-env', '@babel/preset-react'] 34 | } 35 | }, 36 | { 37 | type: 'javascript/auto', 38 | test: /\.json$/, 39 | include: path.resolve(__dirname, './src/translations'), 40 | use: './webpack/translations-loader' 41 | }, 42 | { 43 | test: /\.(sa|sc|c)ss$/, 44 | use: [ 45 | MiniCssExtractPlugin.loader, 46 | { loader: 'css-loader', options: { url: false } }, 47 | 'postcss-loader' 48 | ] 49 | } 50 | ] 51 | }, 52 | 53 | plugins: [ 54 | // Empties the dist folder 55 | new CleanWebpackPlugin({ 56 | verbose: true, 57 | cleanOnceBeforeBuildPatterns: [path.join(process.cwd(), 'dist/**/*')] 58 | }), 59 | 60 | // Copy over static assets 61 | new CopyWebpackPlugin({ 62 | patterns: [ 63 | { from: 'src/manifest.json', to: '../[name][ext]' }, 64 | { from: 'src/images/*', to: './[name][ext]' } 65 | ] 66 | }), 67 | 68 | new MiniCssExtractPlugin({ 69 | filename: '[name].css' 70 | }), 71 | 72 | new TranslationsPlugin({ 73 | path: path.resolve(__dirname, './src/translations') 74 | }), 75 | 76 | new HtmlWebpackPlugin({ 77 | warning: 'AUTOMATICALLY GENERATED FROM ./src/templates/iframe.html - DO NOT MODIFY THIS FILE DIRECTLY', 78 | vendorJs: externalAssets.js, 79 | template: './src/templates/iframe.html', 80 | filename: 'iframe.html' 81 | }) 82 | ] 83 | } 84 | -------------------------------------------------------------------------------- /spec/helpers.spec.js: -------------------------------------------------------------------------------- 1 | /* eslint-env jest */ 2 | import { resizeContainer, templatingLoop, render, escapeSpecialChars as escape } from '../src/javascripts/lib/helpers' 3 | import createRangePolyfill from './polyfills/createRange' 4 | 5 | if (!document.createRange) { 6 | createRangePolyfill() 7 | } 8 | 9 | const client = { 10 | invoke: jest.fn() 11 | } 12 | const dataSet = [1, 2, 3] 13 | function mockGetTemplate (item) { 14 | return `${item}-` 15 | } 16 | 17 | describe('resizeContainer', () => { 18 | it('client.invoke has been called', () => { 19 | resizeContainer(client) 20 | expect(client.invoke).toHaveBeenCalled() 21 | }) 22 | }) 23 | 24 | describe('templatingLoop', () => { 25 | it('generate html with data set and template function', () => { 26 | expect(templatingLoop(dataSet, mockGetTemplate, '-')).toBe('-1-2-3-') 27 | }) 28 | 29 | it('return empty string if data set and initial value is empty', () => { 30 | expect(templatingLoop([], mockGetTemplate)).toBe('') 31 | }) 32 | }) 33 | 34 | describe('render', () => { 35 | it('should replace target dom node with the given HTML string', () => { 36 | document.body.innerHTML = '
' 37 | expect(document.querySelectorAll('#placeholder').length).toBe(1) 38 | 39 | render('#placeholder', '
') 40 | expect(document.querySelectorAll('#placeholder').length).toBe(0) 41 | expect(document.querySelectorAll('#app').length).toBe(1) 42 | }) 43 | }) 44 | 45 | describe('escapeSpecialChars', () => { 46 | it('should throw error if the passed in argument type is not String', function () { 47 | expect(() => { 48 | escape(1) 49 | }).toThrow() 50 | }) 51 | 52 | it('should escape open/close html tags', () => { 53 | expect(escape('')).toBe('<script></script>') 54 | }) 55 | 56 | it('should escape ampersand', () => { 57 | expect(escape('a && b')).toBe('a && b') 58 | }) 59 | 60 | it('should escape quotes and back tick', () => { 61 | expect(escape('"string" \'string\' `string`')).toBe('"string" 'string' `string`') 62 | }) 63 | 64 | it('should escape equal sign', () => { 65 | expect(escape('a = b')).toBe('a = b') 66 | }) 67 | 68 | it('should escape unsafe tags and characters', () => { 69 | expect(escape('Test Ticket for Text App')).toBe('Test Ticket for Text App</a><script>javascript:alret(1);</script>') 70 | }) 71 | }) 72 | -------------------------------------------------------------------------------- /src/javascripts/modules/app.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Example app 3 | **/ 4 | import React from 'react' 5 | import { render } from 'react-dom' 6 | import { ThemeProvider, DEFAULT_THEME } from '@zendeskgarden/react-theming' 7 | import { Grid, Row, Col } from '@zendeskgarden/react-grid' 8 | import { UnorderedList } from '@zendeskgarden/react-typography' 9 | import I18n from '../../javascripts/lib/i18n' 10 | import { resizeContainer, escapeSpecialChars as escape } from '../../javascripts/lib/helpers' 11 | 12 | const MAX_HEIGHT = 1000 13 | const API_ENDPOINTS = { 14 | organizations: '/api/v2/organizations.json' 15 | } 16 | 17 | class App { 18 | constructor (client, _appData) { 19 | this._client = client 20 | 21 | // this.initializePromise is only used in testing 22 | // indicate app initilization(including all async operations) is complete 23 | this.initializePromise = this.init() 24 | } 25 | 26 | /** 27 | * Initialize module, render main template 28 | */ 29 | async init () { 30 | const currentUser = (await this._client.get('currentUser')).currentUser 31 | 32 | I18n.loadTranslations(currentUser.locale) 33 | 34 | const organizationsResponse = await this._client 35 | .request(API_ENDPOINTS.organizations) 36 | .catch(this._handleError.bind(this)) 37 | 38 | const organizations = organizationsResponse ? organizationsResponse.organizations : [] 39 | 40 | const appContainer = document.querySelector('.main') 41 | 42 | render( 43 | 44 | 45 | 46 | 47 | Hi {escape(currentUser.name)}, this is a sample app 48 | 49 | 50 | 51 | 52 | {I18n.t('default.organizations')}: 53 | 54 | {organizations.map(organization => ( 55 | 56 | {escape(organization.name)} 57 | 58 | ))} 59 | 60 | 61 | 62 | 63 | , 64 | appContainer 65 | ) 66 | return resizeContainer(this._client, MAX_HEIGHT) 67 | } 68 | 69 | /** 70 | * Handle error 71 | * @param {Object} error error object 72 | */ 73 | _handleError (error) { 74 | console.log('An error is handled here: ', error.message) 75 | } 76 | } 77 | 78 | export default App 79 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "app_scaffold", 3 | "version": "2.0.0", 4 | "description": "A scaffold for developers to build ZAF v2 apps", 5 | "keywords": [ 6 | "zendesk", 7 | "app", 8 | "framework" 9 | ], 10 | "author": "Zendesk", 11 | "license": "Apache-2.0", 12 | "engines": { 13 | "node": ">=18.12.1" 14 | }, 15 | "scripts": { 16 | "test": "jest", 17 | "watch": "webpack --watch --mode development", 18 | "build:dev": "webpack --mode development", 19 | "build": "webpack --mode production", 20 | "lint": "standard", 21 | "start": "zat server -p ./dist --unattended" 22 | }, 23 | "devDependencies": { 24 | "@babel/core": "^7.16.0", 25 | "@babel/eslint-parser": "^7.16.5", 26 | "@babel/polyfill": "^7.12.1", 27 | "@babel/preset-env": "^7.20.2", 28 | "@babel/preset-react": "^7.18.6", 29 | "@testing-library/react": "^12.1.5", 30 | "babel-jest": "^29.3.1", 31 | "babel-loader": "^9.1.0", 32 | "clean-webpack-plugin": "^4.0.0", 33 | "copy-webpack-plugin": "^11.0.0", 34 | "css-loader": "^6.7.3", 35 | "html-webpack-plugin": "^5.5.0", 36 | "jest": "^29.3.1", 37 | "jest-environment-jsdom": "^29.3.1", 38 | "mini-css-extract-plugin": "^2.7.2", 39 | "postcss": "^8.4.31", 40 | "postcss-import": "^15.1.0", 41 | "postcss-loader": "^7.0.2", 42 | "postcss-preset-env": "^7.8.3", 43 | "standard": "^17.0.0", 44 | "webpack": "^5.94.0", 45 | "webpack-cli": "^5.0.1" 46 | }, 47 | "dependencies": { 48 | "@zendeskgarden/css-bedrock": "^9.0.0", 49 | "@zendeskgarden/react-accordions": "^8.62.0", 50 | "@zendeskgarden/react-avatars": "^8.62.0", 51 | "@zendeskgarden/react-breadcrumbs": "^8.62.0", 52 | "@zendeskgarden/react-buttons": "^8.62.0", 53 | "@zendeskgarden/react-chrome": "^8.62.0", 54 | "@zendeskgarden/react-colorpickers": "^8.62.0", 55 | "@zendeskgarden/react-datepickers": "^8.62.0", 56 | "@zendeskgarden/react-dropdowns": "^8.62.0", 57 | "@zendeskgarden/react-forms": "^8.62.0", 58 | "@zendeskgarden/react-grid": "^8.62.0", 59 | "@zendeskgarden/react-loaders": "^8.62.0", 60 | "@zendeskgarden/react-modals": "^8.62.0", 61 | "@zendeskgarden/react-notifications": "^8.62.0", 62 | "@zendeskgarden/react-pagination": "^8.62.0", 63 | "@zendeskgarden/react-tables": "^8.62.0", 64 | "@zendeskgarden/react-tabs": "^8.62.0", 65 | "@zendeskgarden/react-tags": "^8.62.0", 66 | "@zendeskgarden/react-theming": "^8.62.0", 67 | "@zendeskgarden/react-tooltips": "^8.62.0", 68 | "@zendeskgarden/react-typography": "^8.62.0", 69 | "react": "^16.8.0", 70 | "react-dom": "^16.8.0", 71 | "styled-components": "^5.3.6" 72 | } 73 | } 74 | -------------------------------------------------------------------------------- /spec/i18n.spec.js: -------------------------------------------------------------------------------- 1 | /* eslint-env jest */ 2 | import i18n from '../src/javascripts/lib/i18n' 3 | 4 | const mockEN = { 5 | one: 'the first translation', 6 | 'two.one': 'the second translation for: {{fname}}', 7 | 'two.two': 'the second translation for: {{fname}}-{{lname}}', 8 | 'three.one.one': 'the third translation from {{name}} for {{name}} should be {{name}}', 9 | four: {} 10 | } 11 | 12 | describe('i18n', () => { 13 | beforeAll(() => { 14 | i18n.loadTranslations('en') 15 | 16 | jest.mock('../src/translations/en', () => { 17 | return mockEN 18 | }) 19 | 20 | jest.mock('../src/translations/fr', () => { 21 | throw new Error('no such file') 22 | }) 23 | }) 24 | 25 | describe('#loadTranslations', () => { 26 | it('return undefined for fr and fallback to en', () => { 27 | i18n.loadTranslations('fr') 28 | const result = i18n.t('one') 29 | expect(result).toBe('the first translation') 30 | }) 31 | }) 32 | 33 | describe('#tryRequire', () => { 34 | it('returns a json if the file exists', () => { 35 | const result = i18n.tryRequire('en') 36 | expect(result).toEqual(mockEN) 37 | }) 38 | 39 | it('returns null if the file doesn\'t exist', () => { 40 | const result = i18n.tryRequire('fr') 41 | expect(result).toBe(null) 42 | }) 43 | }) 44 | 45 | describe('#t', () => { 46 | it('returns a string', () => { 47 | const result = i18n.t('one') 48 | expect(result).toBe('the first translation') 49 | }) 50 | 51 | it('interpolates one string', () => { 52 | const result = i18n.t('two.one', { 53 | fname: 'Olaf' 54 | }) 55 | expect(result).toBe('the second translation for: Olaf') 56 | }) 57 | 58 | it('interpolates multiple strings', () => { 59 | const result = i18n.t('two.two', { 60 | fname: 'Olaf', 61 | lname: 'K' 62 | }) 63 | expect(result).toBe('the second translation for: Olaf-K') 64 | }) 65 | 66 | it('interpolates duplicates strings', () => { 67 | const result = i18n.t('three.one.one', { 68 | name: 'Olaf' 69 | }) 70 | expect(result).toBe('the third translation from Olaf for Olaf should be Olaf') 71 | }) 72 | 73 | it('should throw error if translate keyword is not string', function () { 74 | expect(() => { 75 | i18n.t({}) 76 | }).toThrow() 77 | }) 78 | 79 | it('should throw error if translation is not a string', function () { 80 | expect(() => { 81 | i18n.t('four') 82 | }).toThrow() 83 | }) 84 | 85 | it('should throw error if translate keyword is missing in the language file', function () { 86 | expect(() => { 87 | i18n.t('five') 88 | }).toThrow() 89 | }) 90 | }) 91 | }) 92 | -------------------------------------------------------------------------------- /spec/app.spec.js: -------------------------------------------------------------------------------- 1 | /* eslint-env jest, browser */ 2 | import App from '../src/javascripts/modules/app' 3 | import i18n from '../src/javascripts/lib/i18n' 4 | import { CLIENT, ORGANIZATIONS } from './mocks/mock' 5 | import { unmountComponentAtNode } from 'react-dom' 6 | import { act } from 'react-dom/test-utils' 7 | import { configure } from '@testing-library/react' 8 | import { screen } from '@testing-library/dom' 9 | 10 | const mockEN = { 11 | 'app.name': 'Example App', 12 | 'app.title': 'Example App', 13 | 'default.organizations': 'organizations' 14 | } 15 | 16 | describe('Example App', () => { 17 | beforeAll(() => { 18 | configure({ testIdAttribute: 'data-test-id' }) 19 | 20 | i18n.loadTranslations('en') 21 | 22 | jest.mock('../src/translations/en', () => { 23 | return mockEN 24 | }) 25 | }) 26 | 27 | describe('Rendering', () => { 28 | let appContainer = null 29 | 30 | beforeEach(() => { 31 | appContainer = document.createElement('section') 32 | appContainer.classList.add('main') 33 | document.body.appendChild(appContainer) 34 | }) 35 | 36 | afterEach(() => { 37 | unmountComponentAtNode(appContainer) 38 | appContainer.remove() 39 | appContainer = null 40 | }) 41 | 42 | it('render with current username and organizations successfully', (done) => { 43 | act(() => { 44 | CLIENT.request = jest.fn().mockReturnValueOnce(Promise.resolve(ORGANIZATIONS)) 45 | CLIENT.invoke = jest.fn().mockReturnValue(Promise.resolve({})) 46 | 47 | const app = new App(CLIENT, {}) 48 | app.initializePromise.then(() => { 49 | const descriptionElement = screen.getByTestId('sample-app-description') 50 | expect(descriptionElement.textContent).toBe('Hi Sample User, this is a sample app') 51 | 52 | const organizations = screen.getByTestId('organizations') 53 | expect(organizations.childElementCount).toBe(2) 54 | 55 | const organizationA = screen.getByTestId('organization-1') 56 | expect(organizationA.textContent).toBe('Organization A') 57 | const organizationB = screen.getByTestId('organization-2') 58 | expect(organizationB.textContent).toBe('Organization B') 59 | done() 60 | }) 61 | }) 62 | }) 63 | 64 | it('render with current username but no organizations since api errors', (done) => { 65 | act(() => { 66 | CLIENT.request = jest.fn().mockReturnValueOnce(Promise.reject(new Error('a fake error'))) 67 | const app = new App(CLIENT, {}) 68 | const errorSpy = jest.spyOn(app, '_handleError') 69 | 70 | app.initializePromise.then(() => { 71 | const descriptionElement = screen.getByTestId('sample-app-description') 72 | expect(descriptionElement.textContent).toBe('Hi Sample User, this is a sample app') 73 | 74 | const organizations = screen.getByTestId('organizations') 75 | expect(organizations.childElementCount).toBe(0) 76 | 77 | expect(errorSpy).toBeCalled() 78 | 79 | done() 80 | }) 81 | }) 82 | }) 83 | }) 84 | }) 85 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | *Use of this software is subject to important terms and conditions as set forth in the License file* 2 | 3 | # App Scaffold 4 | 5 | ## Description 6 | This repo contains a scaffold to help developers build [apps for Zendesk products](https://developer.zendesk.com/apps/docs/apps-v2/getting_started). 7 | 8 | ## Getting Started 9 | 10 | ### Dependencies 11 | - [Node.js](https://nodejs.org/en/) >= 18.12.1 12 | - [Ruby](https://www.ruby-lang.org/) = 2.6.x 13 | 14 | ### Setup 15 | 1. Clone or fork this repo 16 | 2. Change (`cd`) into the `app_scaffold` directory 17 | 3. Run `yarn install` 18 | 19 | You can use either `yarn` or `npm` as package manager and run the scripts with the corresponding commands. 20 | 21 | To run your app locally in Zendesk, you need the latest [Zendesk Apps Tools (ZAT)](https://github.com/zendesk/zendesk_apps_tools). 22 | 23 | ### Running locally 24 | 25 | To serve the app to your Zendesk instance with `?zat=true`, run 26 | 27 | ``` 28 | yarn run watch 29 | zat server -p dist 30 | ``` 31 | 32 | ## But why? 33 | The App Scaffold includes many features to help you maintain and scale your app. Some of the features provided by the App Scaffold are listed below. However, you don't need prior experience in any of these to be able to use the scaffold successfully. 34 | 35 | - [ES6 (ES2015)](https://babeljs.io/docs/learn-es2015/) 36 | 37 | ECMAScript 6, also known as ECMAScript 2015, is the latest version of the ECMAScript standard. The App Scaffold includes the [Babel compiler](https://babeljs.io/) to transpile your code to ES5. This allows you to use ES6 features, such as classes, arrow functions and template strings even in browsers that haven't fully implemented these features. 38 | 39 | - [Zendesk Garden](https://garden.zendesk.com/) React UI components 40 | 41 | Collection of React components for Zendesk products. You’ll find components built to respond to a range of user input devices, tuned to handle right-to-left layouts, and finessed with just the right touch of subtle animation. 42 | 43 | - [Webpack 5](https://webpack.github.io/) module bundler 44 | 45 | Webpack is a module bundler, we use it to bundle up Javascript modules for use as web applications, also to perform tasks like transforming and transpiling, etc. 46 | 47 | - [PostCSS](https://postcss.org//) stylesheets 48 | 49 | PostCSS transforms stylesheets with JS plugins. These plugins can lint your CSS, support variables and mixins, transpile future CSS syntax, inline images, and more. 50 | 51 | - [StandardJS](https://standardjs.com/) JS linting 52 | 53 | StandardJS is a Javascript style guide, it helps catching style issues or code errors, and automatically formats code for you. 54 | 55 | - [Jest](https://jestjs.io/) Javascript testing framework 56 | 57 | Jest is bundled with JSDom and built on top of Jasmine. It's more than just a ReactJS testing framework. In the Zendesk Apps team, we use it for unit and integration testing of the Official Apps. It also includes a good test coverage toolset out of the box. 58 | 59 | ## Folder structure 60 | 61 | The folder and file structure of the App Scaffold is as follows: 62 | 63 | | Name | Description | 64 | |:----------------------------------------|:---------------------------------------------------------------------------------------------| 65 | | [`.github/`](#.github) | The folder to store PULL_REQUEST_TEMPLATE.md, ISSUE_TEMPLATE.md and CONTRIBUTING.md, etc | 66 | | [`dist/`](#dist) | The folder in which webpack packages the built version of your app | 67 | | [`spec/`](#spec) | The folder in which all of your test files live | 68 | | [`src/`](#src) | The folder in which all of your source JavaScript, CSS, templates and translation files live | 69 | | [`webpack/`](#src) | translations-loader and translations-plugin to support i18n in the application | 70 | | [`.babelrc`](#packagejson) | Configuration file for Babel.js | 71 | | [`.browserslistrc`](#packagejson) | Configuration file for browserslist | 72 | | [`jest.config.js`](#packagejson) | Configuration file for Jest | 73 | | [`package.json`](#packagejson) | Configuration file for Project metadata, dependencies and build scripts | 74 | | [`postcss.config.js`](#packagejson) | Configuration file for PostCSS | 75 | | [`webpack.config.js`](#webpackconfigjs) | Configuration file that webpack uses to build your app | 76 | 77 | #### dist 78 | The dist directory is created when you run the app building scripts. You will need to package this folder when submitting your app to the Zendesk Apps Marketplace, It is also the folder you will have to serve when using [ZAT](https://developer.zendesk.com/apps/docs/apps-v2/getting_started#zendesk-app-tools). It includes your app's manifest.json file, an assets folder with all your compiled JavaScript and CSS as well as HTML and images. 79 | 80 | #### spec 81 | The spec directory is where all your tests and test helpers live. Tests are not required to submit/upload your app to Zendesk and your test files are not included in your app's package, however it is good practice to write tests to document functionality and prevent bugs. 82 | 83 | #### src 84 | The src directory is where your raw source code lives. The App Scaffold includes different directories for JavaScript, stylesheets, templates, images and translations. Most of your additions will be in here (and spec, of course!). 85 | 86 | #### webpack 87 | This directory contains custom tooling to process translations at build time: 88 | 89 | - translations-loader.js is used by Webpack to convert .json translation files to JavaScript objects, for the app itself. 90 | - translations-plugin.js is used to extract compulsory translation strings from the en.json file that are used to display metadata about your app on the Zendesk Apps Marketplace. 91 | 92 | 93 | #### .babelrc 94 | [.babelrc](https://babeljs.io/docs/en/babelrc.html) is the configuration file for babel compiler. 95 | 96 | #### .browserslistrc 97 | .browserslistrc is a configuration file to specify browsers supported by your application, some develop/build tools read info from this file if it exists in your project root. At present, our scaffolding doesn't reply on this file, [default browserslist query](https://github.com/browserslist/browserslist#queries) is used by [Babel](https://babeljs.io/docs/en/babel-preset-env/) and [PostCSS](https://github.com/csstools/postcss-preset-env#browsers) 98 | 99 | #### jest.config.js 100 | [jest.config.js](https://jestjs.io/docs/en/configuration.html) is the configuration file for Jest 101 | 102 | #### package.json 103 | package.json is the configuration file for [Yarn](https://yarnpkg.com/), which is a package manager for JavaScript. This file includes information about your project and its dependencies. For more information on how to configure this file, see [Yarn package.json](https://yarnpkg.com/en/docs/package-json). 104 | 105 | #### postcss.config.js 106 | postcss.config.js is the configuration file for [PostCSS](https://postcss.org/) 107 | 108 | #### webpack.config.js 109 | webpack.config.js is a configuration file for [webpack](https://webpack.github.io/). Webpack is a JavaScript module bundler. For more information about webpack and how to configure it, see [What is webpack](http://webpack.github.io/docs/what-is-webpack.html). 110 | 111 | ## Helpers 112 | The App Scaffold provides some helper functions in `/src/javascripts/lib/helpers.js` to help building apps. 113 | 114 | ### I18n 115 | The I18n (internationalization) module in `/src/javascripts/lib/i18n.js` provides a `t` method to look up translations based on a key. For more information, see [Using the I18n module](https://github.com/zendesk/app_scaffold/blob/master/doc/i18n.md). 116 | 117 | ## Parameters and Settings 118 | If you need to test your app with a `parameters` section in `dist/manifest.json`, foreman might crash with a message like: 119 | 120 | > Would have prompted for a value interactively, but zat is not listening to keyboard input. 121 | 122 | To resolve this problem, set default values for parameters or create a `settings.yml` file in the root directory of your app scaffold-based project, and populate it with your parameter names and test values. For example, using a parameters section like: 123 | 124 | ```json 125 | { 126 | "parameters": [ 127 | { 128 | "name": "myParameter" 129 | } 130 | ] 131 | } 132 | ``` 133 | 134 | create a `settings.yml` containing: 135 | 136 | ```yaml 137 | myParameter: 'some value!' 138 | ``` 139 | 140 | ## Testing 141 | 142 | The App Scaffold is currently setup for testing with [Jest](https://jestjs.io/). To run specs, run 143 | 144 | ``` 145 | yarn test 146 | ``` 147 | 148 | Specs live under the `spec` directory. 149 | 150 | ## Deploying 151 | 152 | To check that your app will pass the server-side validation check, run 153 | 154 | ``` 155 | zat validate --path=dist 156 | ``` 157 | 158 | If validation is successful, you can upload the app into your Zendesk account by running 159 | 160 | ``` 161 | zat create --path=dist 162 | ``` 163 | 164 | To update your app after it has been created in your account, run 165 | 166 | ``` 167 | zat update --path=dist 168 | ``` 169 | 170 | Or, to create a zip archive for manual upload, run 171 | 172 | ``` 173 | zat package --path=dist 174 | ``` 175 | 176 | taking note of the created filename. 177 | 178 | For more information on the Zendesk Apps Tools please see the [documentation](https://developer.zendesk.com/apps/docs/apps-v2/getting_started#zendesk-app-tools). 179 | 180 | ## External Dependencies 181 | External dependencies are defined in [webpack.config.js](https://github.com/zendesk/app_scaffold/blob/master/webpack.config.js). This ensures these dependencies are included in your app's `index.html`. 182 | 183 | ## Contribute 184 | * Put up a PR into the master branch. 185 | * CC and get a +1 from @zendesk/vegemite. 186 | 187 | ## Bugs 188 | Submit Issues via [GitHub](https://github.com/zendesk/app_scaffold/issues/new) or email support@zendesk.com. 189 | 190 | ## Useful Links 191 | Links to maintaining team, confluence pages, Datadog dashboard, Kibana logs, etc 192 | - https://developer.zendesk.com/ 193 | - https://github.com/zendesk/zendesk_apps_tools 194 | - https://webpack.github.io 195 | - https://developer.zendesk.com/documentation/apps/build-an-app/using-react-in-a-support-app/ 196 | 197 | ## Copyright and license 198 | Copyright 2018 Zendesk 199 | 200 | Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. 201 | 202 | You may obtain a copy of the License at 203 | http://www.apache.org/licenses/LICENSE-2.0 204 | Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. 205 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "{}" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright {yyyy} {name of copyright owner} 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | --------------------------------------------------------------------------------