Merge branch 'master' of github.com:Lissy93/dashy into DOCS/updates-to-docs

docs/configuring.md

@@ -54,6 +54,7 @@ To disallow any changes from being written to disk via the UI config editor, set
 
 **Field** | **Type** | **Required**| **Description**
 --- | --- | --- | ---
+**`language`** | `string` | _Optional_ | The 2 (or 4-digit) [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, e.g. `en` or `en-GB`. This must be a language that the app has already been [translated](https://github.com/Lissy93/dashy/tree/master/src/assets/locales) into. If your language is unavailable, Dashy will fallback to English. By default Dashy will attempt to auto-detect your language, although this may not work on some privacy browsers.
 **`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping each of your services and display their status as a dot next to each item. This can be overridden by setting `statusCheck` under each item. Defaults to `false`
 **`statusCheckInterval`** | `boolean` | _Optional_ | The number of seconds between checks. If set to `0` then service will only be checked on initial page load, which is usually the desired functionality. If value is less than `10` you may experience a hit in performance. Defaults to `0`
 **`backgroundImg`** | `string` | _Optional_ | Path to an optional full-screen app background image. This can be either remote (http) or local (/). Note that this will slow down initial load

docs/developing.md

@@ -1,22 +1,22 @@
 
-## Developing
+# Developing
 
-This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture. 
+This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture.
+If you're adding new features, you may want to check out the [Development Guides](./docs/development-guides.md) docs, for tutorials covering basic tasks.
 
 - [Setting up the Development Environment](#setting-up-the-dev-environment)
 - [Resources for Beginners](#resources-for-beginners)
 - [Style Guide](#style-guide)
 - [Frontend Components](#frontend-components)
-- [Common Tasks](#common-tasks)
 - [Project Structure](#directory-structure)
 - [Dependencies and Packages](#dependencies-and-packages)
 
-### Setting up the Dev Environment
+## Setting up the Dev Environment
 
-#### Prerequisites
+### Prerequisites
 You will need either the latest or LTS version of **[Node.js](https://nodejs.org/)** to build and serve the application and **[Git](https://git-scm.com/downloads)** to easily fetch the code, and push any changes. If you plan on running or deploying the container, you'll also need **[Docker](https://docs.docker.com/get-docker/)**. To avoid any unexpected issues, ensure you've got at least **[NPM](https://www.npmjs.com/get-npm)** V 7.5 or **[Yarn](https://classic.yarnpkg.com/en/docs/install/#windows-stable)** 1.22 (you may find [NVM](https://github.com/nvm-sh/nvm) helpful for switching/ managing versions).
 
-#### Running the Project
+### Running the Project
 
 1. Get Code: `git clone git@github.com:Lissy93/dashy.git`
 2. Navigate into the directory: `cd dashy`
@@ -25,7 +25,7 @@ You will need either the latest or LTS version of **[Node.js](https://nodejs.org
 
 Dashy should now be being served on http://localhost:8080/. Hot reload is enabled, so making changes to any of the files will trigger them to be rebuilt and the page refreshed.
 
-#### Project Commands
+### Project Commands
 
 - `yarn dev` - Starts the development server with hot reloading
 - `yarn build` - Builds the project for production, and outputs it into `./dist`
@@ -47,7 +47,7 @@ Note:
 - If you are using NPM, replace `yarn` with `npm run`
 - If you are using Docker, precede each command with `docker exec -it [container-id]`. Container ID can be found by running `docker ps`
 
-### Environmental Variables
+## Environmental Variables
 - `PORT` - The port in which the application will run (defaults to `4000` for the Node.js server, and `80` within the Docker container)
 - `NODE_ENV` - Which environment to use, either `production`, `development` or `test`
 - `VUE_APP_DOMAIN` - The URL where Dashy is going to be accessible from. This should include the protocol, hostname and (if not 80 or 443), then the port too, e.g. `https://localhost:3000`, `http://192.168.1.2:4002` or `https://dashy.mydomain.com`
@@ -58,7 +58,7 @@ If you do add new variables, ensure that there is always a fallback (define it i
 
 Any environmental variables used by the frontend are preceded with `VUE_APP_`. Vue will merge the contents of your `.env` file into the app in a similar way to the ['dotenv'](https://github.com/motdotla/dotenv) package, where any variables that you set on your system will always take preference over the contents of any `.env` file.
 
-### Environment Modes
+## Environment Modes
 Both the Node app and Vue app supports several environments: `production`, `development` and `test`. You can set the environment using the `NODE_ENV` variable (either with your OS, in the Docker script or in an `.env` file - see [Environmental Variables](#environmental-variables) above).
 
 The production environment will build the app in full, minifying and streamlining all assets. This means that building takes longer, but the app will then run faster. Whereas the dev environment creates a webpack configuration which enables HMR, doesn't hash assets or create vendor bundles in order to allow for fast re-builds when running a dev server. It supports sourcemaps and other debugging tools, re-compiles and reloads quickly but is not optimized, and so the app will not be as snappy as it could be. The test environment is intended for test running servers, it ignores assets that aren't needed for testing, and focuses on running all the E2E, regression and unit tests. For more information, see [Vue CLI Environment Modes](https://cli.vuejs.org/guide/mode-and-env.html#modes).
@@ -67,7 +67,7 @@ By default:
 - `production` is used by `yarn build` (or `vue-cli-service build`) and `yarn build-and-start` and `yarn pm2-start`
 - `development` is used by `yarn dev` (or `vue-cli-service serve`)
 - `test` is used by `yarn test` (or `vue-cli-service test:unit`)
-### Resources for Beginners
+## Resources for Beginners
 New to Web Development? Glad you're here! Dashy is a pretty simple app, so it should make a good candidate for your first PR. Presuming that you already have a basic knowledge of JavaScript, the following articles should point you in the right direction for getting up to speed with the technologies used in this project:
 - [Introduction to Vue.js](https://v3.vuejs.org/guide/introduction.html)
 - [Vue.js Walkthrough](https://www.taniarascia.com/getting-started-with-vue/)
@@ -82,7 +82,7 @@ New to Web Development? Glad you're here! Dashy is a pretty simple app, so it sh
 
 As well as Node, Git and Docker- you'll also need an IDE (e.g. [VS Code](https://code.visualstudio.com/) or [Vim](https://www.vim.org/)) and a terminal (Windows users may find [WSL](https://docs.microsoft.com/en-us/windows/wsl/) more convenient). 
 
-### Style Guide
+## Style Guide
 
 Linting is done using [ESLint](https://eslint.org/), and using the [Vue.js Styleguide](https://github.com/vuejs/eslint-config-standard), which is very similar to the [AirBnB Stylguide](https://github.com/airbnb/javascript). You can run `yarn lint` to report and fix issues. While the dev server is running, issues will be reported to the console automatically. Any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged. Linting is also run as a git pre-commit hook
 
@@ -99,7 +99,7 @@ The most significant things to note are:
 
 For the full styleguide, see: [github.com/airbnb/javascript](https://github.com/airbnb/javascript) 
 
-### Frontend Components
+## Frontend Components
 
 All frontend code is located in the `./src` directory, which is split into 5 sub-folders:
 - Components - All frontend web components are located here. Each component should have a distinct, well defined and simple task, and ideally should not be too long. The components directory is organised into a series of sub-directories, representing a specific area of the application
@@ -116,37 +116,21 @@ The structure of the components directory is similar to that of the frontend app
 
 <p align="center"><img src="https://i.ibb.co/wJCt0Lq/dashy-page-structure.png" width="600"/></p>
 
-### Common Tasks
-
-#### Creating a new theme
-
-See [Theming](./theming.md)
-
-#### Adding a new option in the config file
-
-All application config is specified in `./public/conf.yml` - see [Configuring Docs](./configuring.md) for info. Before adding a new option in the config file, first ensure that there is nothing similar available, that is is definitely necessary, it will not conflict with any other options and most importantly that it will not cause any breaking changes. Ensure that you choose an appropriate and relevant section to place it under.
-
-Checklist:
-- Update the [Schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js) with the parameters for your new option
-- Set a default value (if required) within [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js)
-- Document the new value in [`configuring.md`](./configuring.md)
-- Test that the reading of the new attribute is properly handled, and will not cause any errors when it is missing or populated with an unexpected value
-
-#### Updating Dependencies
+### Updating Dependencies
 
 Running `yarn upgrade` will updated all dependencies based on the ranges specified in the `package.json`. The `yarn.lock` file will be updated, as will the contents of `./node_modules`, for more info, see the [yarn upgrade documentation](https://classic.yarnpkg.com/en/docs/cli/upgrade/). It is important to thoroughly test after any big dependency updates.
 
-### Development Tools
+## Development Tools
 
-#### Performance - Lighthouse
+### Performance - Lighthouse
 The easiest method of checking performance is to use Chromium's build in auditing tool, Lighthouse. To run the test, open Developer Tools (usually F12) --> Lighthouse and click on the 'Generate Report' button at the bottom.
 
-#### Dependencies - BundlePhobia
+### Dependencies - BundlePhobia
 [BundlePhobia](https://bundlephobia.com/) is a really useful app that lets you analyze the cost of adding any particular dependency to an application
 
-### Directory Structure
+## Directory Structure
 
-#### Files in the Root: `./`
+### Files in the Root: `./`
 ```
 ╮
 ├── package.json        # Project meta-data, dependencies and paths to scripts
@@ -163,7 +147,7 @@ The easiest method of checking performance is to use Chromium's build in auditin
 ╯
 ```
 
-#### Frontend Source: `./src/`
+### Frontend Source: `./src/`
 
 ```
 ./src
@@ -219,17 +203,17 @@ The easiest method of checking performance is to use Chromium's build in auditin
 ```
 ---
 
-### Dependencies and Packages
+## Dependencies and Packages
 
 During development I made the conscious decision to not reinvent the wheel if not necessary. It is often really tempting to try an build everything yourself, but sometimes it's just not practical. Often there's packages out there, developed by amazing individuals which are probably built better than I could have done. That being said, I have looked through the code of most these dependencies, to verify that they are both legitimate and efficient.
 
 The following packages are used. Full credit, and massive kudos to each of their authors.
 
-#### Core
+### Core
 
 At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as well as it's services. Styling is done with [SCSS](https://github.com/sass/sass), JavaScript is currently [Babel](https://github.com/babel/babel), (but I am in the process of converting to [TypeScript](https://github.com/Microsoft/TypeScript)), linting is done with [ESLint](https://github.com/eslint/eslint), the config is defined in [YAML](https://github.com/yaml/yaml), and there is a simple [Node.js](https://github.com/nodejs/node) server to serve up the static app.
 
-#### Frontend Components
+### Frontend Components
 
 - [`vue-select`](https://github.com/sagalbot/vue-select) - Dropdown component by @sagalbot `MIT`
 - [`vue-js-modal`](https://github.com/euvl/vue-js-modal) - Modal component by @euvl `MIT`
@@ -241,23 +225,23 @@ At it's core, the application uses [Vue.js](https://github.com/vuejs/vue), as we
 - [`vue-prism-editor`](https://github.com/koca/vue-prism-editor) - Lightweight code editor by @koca `MIT`
   - Forked from [`prism.js`](https://github.com/PrismJS/prism) `MIT`
 
-#### Utilities
+### Utilities
 
 - [`crypto-js`](https://github.com/brix/crypto-js) - Encryption implementations by @evanvosberg and community `MIT`
 - [`axios`](https://github.com/axios/axios) - Promise based HTTP client by @mzabriskie and community `MIT`
 - [`ajv`](https://github.com/ajv-validator/ajv) - JSON schema Validator by @epoberezkin and community `MIT`
 
-#### Server
+### Server
 
 - [`connect`](https://github.com/senchalabs/connect) - Minimilistic middleware layer for chaining together Node.js requests handled by the server file `MIT`
 - [`serve-static`](https://github.com/expressjs/serve-static) - Lightweight static Node file server `MIT`
 
-##### External Services
+#### External Services
 The 1-Click deploy demo uses [Play-with-Docker Labs](https://play-with-docker.com/). Code is hosted on [GitHub](https://github.com), Docker image is hosted on [DockerHub](https://hub.docker.com/), and the demos are hosted on [Netlify](https://www.netlify.com/).
 
-### Notes
+## Notes
 
-#### Known Warnings
+### Known Warnings
 
 When running the build command, several warnings appear. These are not errors, and do not affect the security or performance of the application. They will be addressed in a future update
 

docs/development-guides.md

@@ -0,0 +1,113 @@
+# Development Guides
+
+A series of short tutorials, to guide you through the most common development tasks. 
+
+Sections:
+- [Creating a new theme](#creating-a-new-theme)
+- [Adding Translations](#adding-translations)
+- [Adding a new option in the config file](#adding-a-new-option-in-the-config-file)
+
+## Creating a new theme
+
+See [Theming](./theming.md)
+
+## Adding Translations
+
+Dashy is using [vue-i18n](https://vue-i18n.intlify.dev/guide/) to manage multi-language support.
+
+Adding a new language is pretty straightforward, with just three steps:
+
+##### 1. Create a new Language File
+Create a new JSON file in `./src/assets/locales` name is a 2-digit [ISO-639 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) for your language, E.g. for German `de.json`, French `fr.json` or Spanish `es.json` - You can find a list of all ISO codes at [iso.org](https://www.iso.org/obp/ui).
+If your language is a specific dialect or regional language, then use the Posfix [CLDR](http://cldr.unicode.org/) format, where, e.g. `en-GB.json` (British), `es-MX.json` (Spanish, in Mexico) or `zh-CN.json` (Chinese, simplified) - A list of which can be found [here](https://github.com/unicode-org/cldr-json/blob/master/cldr-json/cldr-core/availableLocales.json)
+
+
+##### 2. Translate!
+Using [`en.json`](https://github.com/Lissy93/dashy/tree/master/src/assets/locales/en.json) as an example, translate the JSON values to your language, while leaving the keys as they are. It's fine to leave out certain items, as if they're missing they will fall-back to English. If you see any attribute which include curly braces (`{xxx}`), then leave the inner value of these braces as is, as this is for variables.
+
+```json
+{
+  "theme-maker": {
+    "export-button": "Benutzerdefinierte Variablen exportieren",
+    "reset-button": "Stile zurücksetzen für",
+    "show-all-button": "Alle Variablen anzeigen",
+    "save-button": "Speichern",
+    "cancel-button": "Abbrechen",
+    "saved-toast": "{theme} Erfolgreich aktualisiert",
+    "reset-toast": "Benutzerdefinierte Farben für {theme} entfernt"
+  },
+}
+```
+
+##### 3. Add your file to the app
+
+In [`./src/utils/languages.js`](https://github.com/Lissy93/dashy/tree/master/src/utils/languages.js), you need to do 2 small things:
+
+First import your new translation file, do this at the top of the page.
+E.g. `import de from '@/assets/locales/de.json';`
+
+Second, add it to the array of languages, e.g:
+```javascript
+export const languages = [
+  {
+    name: 'English',
+    code: 'en',
+    locale: en,
+    flag: '🇬🇧',
+  },
+  {
+    name: 'German', // The name of your language
+    code: 'de', // The ISO code of your language
+    locale: de, // The name of the file you imported (no quotes)
+    flag: '🇩🇪', // An optional flag emoji
+  },
+];
+```
+You can also add your new language to the readme, under the [Language Switching](https://github.com/Lissy93/dashy#language-switching-) section and optionally include your name/ username if you'd like to be credited for your work. Done!
+
+If you are not comfortable with making pull requests, or do not want to modify the code, then feel free to instead send the translated file to me, and I can add it into the application. I will be sure to credit you appropriately. 
+
+# Adding a new option in the config file
+
+This section is for, if you're adding a new component or setting, that requires an additional item to be added to the users config file.
+
+All of the users config is specified in `./public/conf.yml` - see [Configuring Docs](./configuring.md) for info.
+Before adding a new option in the config file, first ensure that there is nothing similar available, that is is definitely necessary, it will not conflict with any other options and most importantly that it will not cause any breaking changes. Ensure that you choose an appropriate and relevant section to place it under.
+
+Next decide the most appropriate place for your attribute:
+- Application settings should be located under `appConfig`
+- Page info (such as text and metadata) should be under `pageInfo`
+- Data relating to specific sections should be under `section[n].displayData`
+- And for setting applied to specific items, it should be under `item[n]`
+
+In order for the user to be able to add your new attribute using the Config Editor, and for the build validation to pass, your attribute must be included within the [ConfigSchema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js). You can read about how to do this on the [ajv docs](https://ajv.js.org/json-schema.html). Give your property a type and a description, as well as any other optional fields that you feel are relevant. For example:
+
+```json
+"fontAwesomeKey": {
+  "type": "string",
+  "pattern": "^[a-z0-9]{10}$",
+  "description": "API key for font-awesome",
+  "example": "0821c65656"
+}
+```
+or
+```json
+"iconSize": {
+  "enum": [ "small", "medium", "large" ],
+  "default": "medium",
+  "description": "The size of each link item / icon"
+}
+```
+
+Next, if you're property should have a default value, then add it to [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js). This ensures that nothing will break if the user does not use your property, and having all defaults together keeps things organised and easy to manage.
+
+If your property needs additional logic for fetching, setting or processing, then you can add a helper function within [`ConfigHelpers.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigHelpers.js).
+
+Finally, add your new property to the [`configuring.md`](./configuring.md) API docs. Put it under the relevant section, and be sure to include field name, data type, a description and mention that it is optional.  If your new feature needs more explaining, then you can also document it under the relevant section elsewhere in the documentation.
+
+Checklist:
+- [] Ensure the new attribute is actually necessary, and nothing similar already exists 
+- [] Update the [Schema](https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js) with the parameters for your new option
+- [] Set a default value (if required) within [`defaults.js`](https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js)
+- [] Document the new value in [`configuring.md`](./configuring.md)
+- [] Test that the reading of the new attribute is properly handled, and will not cause any errors when it is missing or populated with an unexpected value