diff --git a/.github/workflows/blank.yml b/.github/workflows/blank.yml new file mode 100644 index 00000000..d5be4189 --- /dev/null +++ b/.github/workflows/blank.yml @@ -0,0 +1,21 @@ +# Lints code merged into master branch +name: Lint Code Base +on: + push: + pull_request: + branches: [master] +jobs: + build: + name: Lint Code Base + runs-on: ubuntu-latest + steps: + - name: Checkout Code + uses: actions/checkout@v2 + with: + fetch-depth: 0 + - name: Lint Code Base + uses: github/super-linter@v4 + env: + VALIDATE_ALL_CODEBASE: false + DEFAULT_BRANCH: master + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/cache-artifacts.yml b/.github/workflows/cache-artifacts.yml new file mode 100644 index 00000000..498ce16e --- /dev/null +++ b/.github/workflows/cache-artifacts.yml @@ -0,0 +1,13 @@ +# Caches artifacts, including NPM dependencies, to speed up build times +name: Caching Atrifacts +on: push +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/cache@v2 + with: + path: ~/.npm + key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} + restore-keys: | + ${{ runner.os }}-node- diff --git a/.github/workflows/dependency-updates-summary.yml b/.github/workflows/dependency-updates-summary.yml new file mode 100644 index 00000000..145064a5 --- /dev/null +++ b/.github/workflows/dependency-updates-summary.yml @@ -0,0 +1,18 @@ +# Shows changes to yarn.lock in PR comment +# Useful for easily understanding dependency changes +name: Yarn Lock Changes +on: [pull_request] +jobs: + check: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + - name: Yarn Lock Changes + uses: Simek/yarn-lock-changes@main + with: + token: ${{ secrets.GITHUB_TOKEN }} + collapsibleThreshold: '25' + failOnDowngrade: 'false' + path: 'yarn.lock' + updateComment: 'true' diff --git a/.github/workflows/generate-contributors.yml b/.github/workflows/generate-contributors.yml index f2416011..02fe2e6d 100644 --- a/.github/workflows/generate-contributors.yml +++ b/.github/workflows/generate-contributors.yml @@ -1,3 +1,5 @@ +# Generates an image showing profile picture of everyone who'se contributed to Dashy +# Which is embeded in the Readme Credits section, as they deserve some recognition name: Contributors on: schedule: diff --git a/.github/workflows/get-size.yml b/.github/workflows/get-size.yml new file mode 100644 index 00000000..2b602fd0 --- /dev/null +++ b/.github/workflows/get-size.yml @@ -0,0 +1,9 @@ +# Adds a comment to new PRs, showing the compressed size and size difference of new code +name: Compressed Size +on: [pull_request] +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: preactjs/compressed-size-action@v2 diff --git a/.github/workflows/issue-translator.yml b/.github/workflows/issue-translator.yml new file mode 100644 index 00000000..501e9ebd --- /dev/null +++ b/.github/workflows/issue-translator.yml @@ -0,0 +1,18 @@ +# Will translate any issues opened in foraign language, and add the English translation as a comment +name: 'Issue Translator' +on: + issue_comment: + types: [created] + issues: + types: [opened] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: tomsun28/issues-translate-action@v2.5 + with: + BOT_GITHUB_TOKEN: ${{ secrets.BOT_GITHUB_TOKEN }} + BOT_LOGIN_NAME: liss-bot + IS_MODIFY_TITLE: true + CUSTOM_BOT_NOTE: It looks like this issue isn't in English - not a problem, here's the translation! 🇬🇧 diff --git a/.github/workflows/label-sponsors.yml b/.github/workflows/label-sponsors.yml new file mode 100644 index 00000000..f7d129bd --- /dev/null +++ b/.github/workflows/label-sponsors.yml @@ -0,0 +1,18 @@ +# Adds a label to any issues raised by a sponsor of Lissy93/Dashy +# In order to allow their request can be prioritized +name: Label sponsors +on: + pull_request: + types: [opened] + issues: + types: [opened] +jobs: + build: + name: is-sponsor-label + runs-on: ubuntu-latest + steps: + - uses: JasonEtco/is-sponsor-label-action@v1 + with: + label: Priority Request - Sponsor 💖 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/security-scanning.yml b/.github/workflows/security-scanning.yml new file mode 100644 index 00000000..228b2f2e --- /dev/null +++ b/.github/workflows/security-scanning.yml @@ -0,0 +1,19 @@ +# Uses Snyk to check for potential vulnerabilities, then sends results to GH security tab +name: Check for vulnerabilities with Snyk +on: push +jobs: + security: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@master + - name: Run Snyk to check for vulnerabilities + uses: snyk/actions/node@master + continue-on-error: true + env: + SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }} + with: + args: --sarif-file-output=snyk.sarif + - name: Upload result to GitHub Code Scanning + uses: github/codeql-action/upload-sarif@v1 + with: + sarif_file: snyk.sarif diff --git a/README.md b/README.md index 6d279f4e..5e495cb9 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ - Easy single-file YAML-based configuration, which can also be configured directly through the UI - Small bundle size, fully responsive UI and PWA makes the app easy to use on any device - Easy to setup with Docker, or on bare metal, or with 1-Click cloud deployment +- Multi-language support, with additional languages coming soon - Plus lots more... ## Demo ⚡ @@ -304,6 +305,21 @@ From the Settings Menu in Dashy, you can download, backup, edit and rest your co --- +## Language Switching 🌎 + +Dashy has the ability to support multiple languages and locales. When available, you're language should be automatically detected and applied on load, based on your browser or systems settings. But you can also select a language through the UI, under Config --> Switch Language. + +Alternatively, set you're language in the config file, under `appConfig.language`. The language must be specified as either a 2-digit [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (such as `en`), or where available, the 2-digit code followed by a region or dialect (e.g. `en-GB`). + +#### Supported Languages +- 🇬🇧 **English**: `en` + +#### Add your Language +I would love for Dashy to be available and comfortable to use for all, including non-native English speakers. If you speak another language, and have a few minutes to sapir, you're help with translating it would be very much appreciated. +There's not too much text to translate, and it's all located in [a single JSON file](https://github.com/Lissy93/dashy/tree/master/src/assets/locales), and you don't have to translate it all, as any missing items will just fallback to English. For more info, see the [Development Guides Docs](https://github.com/Lissy93/dashy/blob/master/docs/development-guides.md#adding-translations), and feel free to reach out if you need any support. + +--- + ## Sections & Items 🗃️ Dashy is made up of a series of sections, each containing a series of items. diff --git a/docs/assets/CONTRIBUTORS.svg b/docs/assets/CONTRIBUTORS.svg index 4a3cf1a8..01a754f2 100644 --- a/docs/assets/CONTRIBUTORS.svg +++ b/docs/assets/CONTRIBUTORS.svg @@ -3,10 +3,13 @@ + + + - + - + \ No newline at end of file diff --git a/docs/configuring.md b/docs/configuring.md index 1216c6ab..f577197d 100644 --- a/docs/configuring.md +++ b/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 diff --git a/docs/developing.md b/docs/developing.md index de600bfd..0d085507 100644 --- a/docs/developing.md +++ b/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

-### 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 diff --git a/docs/development-guides.md b/docs/development-guides.md new file mode 100644 index 00000000..f05282ca --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/user-guide.md b/docs/user-guide.md deleted file mode 100644 index 60d2c549..00000000 --- a/docs/user-guide.md +++ /dev/null @@ -1,125 +0,0 @@ -## User Guide - -This article outlines how to use the application. If you are instead looking for deployment instructions, see [Deployment](/docs/deployment.md) and [Configuring](/docs/configuring.md) - -### Contents -- [Searching](#searching) -- [Keyboard Shortcuts](#keyboard-shortcuts) -- [Theme Switching](#theme-switching) -- [Visual Options](#visual-options) -- [Opening Items](#opening-items) -- [Sections and Items](#sections-and-items) -- [Icons](#icons) -- [Metadata](#metadata) -- [Editing Config](#editing-config) -- [Managing Config Data](#managing-config-data) - -### Searching - -A key requirement for any start page is being able to quickly and effectively find the item your looking for. For Dashy, a lot of thought was put into the most intuitive method to filter links. - -To start searching, simply start typing. Your search term will show up in the filter field in the upper-left section, and results will be filtered accordingly. - -The following properties are used to filter items by: -- Title / Item name -- Provider - The optional field, indicating the provider of a given app or service -- URL - Only the base URL is searched, the protocol and parameters are omitted -- Description - -**[⬆️ Back to Top](#user-guide)** - -### Keyboard Shortcuts - -Many people find using the keyboard significantly more efficient than having to reach for the mouse. And so Dashy has a series of keybindings and shortcuts to enable you to navigate through items quickly. - -Once you've searched for a given item, you can then tab through the list (or Shift + Tab to go backwards) until you've found the item you're looking for. You can also use the arrow keys to navigate up, down, left and right through the grid. To launch an item, just hit enter. You can also open an item in a new tab with Ctrl + Enter, or open the item in a pop-up modal with Alt + Enter. To close an open popup item, or any open menus, just hit Esc. - -**[⬆️ Back to Top](#user-guide)** - -### Theme Switching - -You can change the current theme using the dropdown menu in the upper-right-hand quadrant. Your selected theme will be stored in local storage, and applied next time you load the page. For more information on customizing the look and feel of Dashy, see [Themeing Docs](/docs/theming.md) - -**[⬆️ Back to Top](#user-guide)** - -### Visual Options - -There are several pre-built layout options to choose from depending on your requirements. Like the theme these options will be remembered in browser storage and applied on load. - -The first is Layout. This determines how sections are organised on the screen. This can be set to either grid (auto), horizontal or vertical. Vertical layout will cause each section to take up the full width of the screen, and minimum height. Horizontal is the opposite, where every section is on the same row, and spans the full height of the screen. - -Next there's icon size. This changes the size of the item and it's icon. It can be useful to use a smaller size when there are a lot of items, or a larger size if you commonly access Dashy from a touch screen tablet. - -![layout-options](https://i.ibb.co/NnzF82t/available-layout-options.png) - -**[⬆️ Back to Top](#user-guide)** - -### Opening Items - -There are three methods of opening items. Clicking (or hitting Enter on a selected item) will use the default method, specified in the config file, under `item.target`. You can use Ctrl + Click or Ctrl + Enter to open and item in a new tab. - -You can also use Alt + Click or Alt + Enter, to open an item in a popup window. You can use drag the tab in the bottom-right corner of the pop-up to resize it. To close an item opened in a pop-up, click the close button, use the Esc key, or click anywhere outside the popup. - -![Example of a pop-up opened item](https://i.ibb.co/zSnznFF/dashy-popup.png) - -**[⬆️ Back to Top](#user-guide)** - -### Sections and Items - -The main content in Dashy is defined as an array of sections, each of which contains an array of items. You can have as many sections as you need, and each section can have an unlimited amount of items. If you are using the grid layout, then it works better, visually if each of your sections have similar number of items. - -Sections are collapsible, which is useful for those sections which contain less used applications, or are particularly long. The collapse state of a given section is remembered (stored in local storage), and applied on load. - -Sections also have several optional properties, which are specified under `section.displayData`, and let you set certain display settings. A full list of options can be found in the [configuring docs](/docs/configuring.md). - - -``` - ┌─────────────────────────────────────────────────────┐ - │ Title │ - │ Sub-Title/ Description Link 1 Link 2 │ - ├──────────────┬─────────────────┬────────────────────┤ - │ Search │ │ Display Options │ - ├──────────────┘ └────────────────────┤ - │ │ - │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ - │ │ Section 1 │ │ Section 2 │ │ Section 3 │ │ - │ ├──────────────┤ ├──────────────┤ ├──────────────┤ │ - │ │ ┌───┐ ┌───┐ │ │ ┌───┐ ┌───┐ │ │ ┌───┐ ┌───┐ │ │ - │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ └───┘ └───┘ │ │ └───┘ └───┘ │ │ └───┘ └───┘ │ │ - │ │ ┌───┐ ┌───┐ │ │ ┌───┐ ┌───┐ │ │ ┌───┐ ┌───┐ │ │ - │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ - │ │ └───┘ └───┘ │ │ └───┘ └───┘ │ │ └───┘ └───┘ │ │ - │ └──────────────┘ └──────────────┘ └──────────────┘ │ - │ │ - ├─────────────────────────────────────────────────────┤ - └─────────────────────────────────────────────────────┘ -``` - -**[⬆️ Back to Top](#user-guide)** - -### Icons - -Both sections and items can have an icon associated with them. There are several options for specifying icons. You can let the icon be automatically resolved and fetched from the items associated URL, by setting it's value to `favicon`. You can use a font-awesome icon, by specifying it's name and category, e.g. `fas fa-rocket`. Or you can pass in a URL, either to a locally hosted or remote image. For local images, you can put them in `./public/item-icons/` and then reference them just by the file name. - -**[⬆️ Back to Top](#user-guide)** - -### Metadata - -Basic site information, displayed in the header and footer can be set from the UI. This includes: title, sub-title, footer text, and nav-bar links. Click the wrench icon in the upper-right corner, then go to the Site Metadata tab. Fill in your new data, and hit save. The page will be refreshed, and your changes will appear. These settings are stored under `pageInfo` in the config, and if set through the UI, will only be applied locally. - -**[⬆️ Back to Top](#user-guide)** - -### Editing Config - -The config file can be edited from the UI, but take note that changes are only applied locally. You will need to either export this data into your conf.yml, or use the cloud backup and sync feature. - -To make changes to the config file, click the wrench icon in the upper-left hand corner. Then go to the Config tab. Here you'll find a JSON editor. You can switch from tree mode to plain-text mode if you find that easier. And parsing or validation issues will be displayed at the bottom of the screen. - -**[⬆️ Back to Top](#user-guide)** - -### Managing Config Data - -You can download, backup or reset local config data directly from the UI. To apply config to Dashy on other devices, you will need to either download the config file, or use the cloud backup and sync feature. To download config, click the Wrench icon, in the upper-right hand corner, and then go to Download. Similarly, for cloud backup, click the Cloud icon in the upper right corner, and fill in the required fields. For detailed instructions, and technical information about backup and sync, please see the [Cloud Backup Documentation](/docs/backup-restore.md). You can also Reset all local settings from the config menu. This will not effect any data saved in your systems `conf.yml` file. - -**[⬆️ Back to Top](#user-guide)** diff --git a/package.json b/package.json index 95db1abe..d1196a42 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "Dashy", - "version": "1.4.1", + "version": "1.4.2", "license": "MIT", "main": "server", "scripts": { @@ -31,6 +31,7 @@ "v-tooltip": "^2.1.3", "vue": "^2.6.10", "vue-cli-plugin-yaml": "^1.0.2", + "vue-i18n": "^8.25.0", "vue-js-modal": "^2.0.0-rc.6", "vue-material-tabs": "^0.1.2", "vue-prism-editor": "^1.2.2", @@ -40,6 +41,7 @@ "vue-toasted": "^1.1.28" }, "devDependencies": { + "@architect/sandbox": "^3.7.4", "@vue/cli-plugin-babel": "^4.5.12", "@vue/cli-plugin-eslint": "^4.5.12", "@vue/cli-plugin-pwa": "^4.5.12", diff --git a/src/App.vue b/src/App.vue index 806c33e4..7d7faee4 100644 --- a/src/App.vue +++ b/src/App.vue @@ -17,6 +17,7 @@ import { localStorageKeys, splashScreenTime, visibleComponents as defaultVisibleComponents, + language as defaultLanguage, } from '@/utils/defaults'; const Accumulator = new ConfigAccumulator(); @@ -70,9 +71,33 @@ export default { this.isLoading = false; } }, + /* Checks local storage, then appConfig, and if a custom language is specified, its applied */ + applyLanguage() { + let language = defaultLanguage; // Language to apply + const availibleLocales = this.$i18n.availableLocales; // All available locales + + // If user has specified a language, locally or in config, then check and apply it + const usersLang = localStorage[localStorageKeys.LANGUAGE] || this.appConfig.language; + if (usersLang && availibleLocales.includes(usersLang)) { + language = usersLang; + } else { + // Otherwise, attempt to apply language automatically, based on their system language + const usersBorwserLang1 = window.navigator.language || ''; // e.g. en-GB or or '' + const usersBorwserLang2 = usersBorwserLang1.split('-')[0]; // e.g. en or undefined + if (availibleLocales.includes(usersBorwserLang1)) { + language = usersBorwserLang1; + } else if (availibleLocales.includes(usersBorwserLang2)) { + language = usersBorwserLang2; + } + } + // Apply Language + this.$i18n.locale = language; + document.getElementsByTagName('html')[0].setAttribute('lang', language); + }, }, /* When component mounted, hide splash and initiate the injection of custom styles */ mounted() { + this.applyLanguage(); this.hideSplash(); if (this.appConfig.customCss) { const cleanedCss = this.appConfig.customCss.replace(/<\/?[^>]+(>|$)/g, ''); diff --git a/src/assets/interface-icons/config-language.svg b/src/assets/interface-icons/config-language.svg new file mode 100644 index 00000000..613b9e31 --- /dev/null +++ b/src/assets/interface-icons/config-language.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/src/assets/locales/en.json b/src/assets/locales/en.json new file mode 100644 index 00000000..9b69980b --- /dev/null +++ b/src/assets/locales/en.json @@ -0,0 +1,136 @@ +{ + "home": { + "no-results": "No Search Results", + "no-data": "No Data Configured" + }, + "search": { + "search-label": "Search", + "search-placeholder": "Start typing to filter", + "clear-search-tooltip": "Clear Search" + }, + "login": { + "title": "Dashy", + "username-label": "Username", + "password-label": "Password", + "login-button": "Login", + "remember-me-label": "Remember me for", + "remember-me-never": "Never", + "remember-me-hour": "4 Hours", + "remember-me-day": "1 Day", + "remember-me-week": "1 Week" + }, + "config": { + "main-tab": "Config", + "view-config-tab": "View Config", + "edit-config-tab": "Edit Config", + "custom-css-tab": "Custom Styles", + "heading": "Configuration Options", + "download-config-button": "Download Config", + "edit-config-button": "Edit Config", + "edit-css-button": "Edit Custom CSS", + "cloud-sync-button": "Enable Cloud Sync", + "edit-cloud-sync-button": "Edit Cloud Sync", + "rebuild-app-button": "Rebuild Application", + "change-language-button": "Change App Language", + "reset-settings-button": "Reset Local Settings", + "app-info-button": "App Info", + "app-version-note": "Dashy version", + "backup-note": "It is recommend to make a backup of your configuration before making changes.", + "reset-config-msg-l1": "This will remove all user settings from local storage, but won't effect your 'conf.yml' file.", + "reset-config-msg-l2": "You should first backup any changes you've made locally, if you want to use them in the future.", + "reset-config-msg-l3": "Are you sure you want to proceed?", + "data-cleared-msg": "Data cleared successfully", + "actions-label": "Actions", + "copy-config-label": "Copy Config", + "data-copied-msg": "Config has been copied to clipboard", + "reset-config-label": "Reset Config", + "css-save-btn": "Save Changes", + "css-note-label": "Note", + "css-note-l1": "You will need to refresh the page for your changes to take effect.", + "css-note-l2": "Styles overrides are only stored locally, so it is recommended to make a copy of your CSS.", + "css-note-l3": "To remove all custom styles, delete the contents and hit Save Changes" + }, + "settings": { + "theme-label": "Theme", + "layout-label": "Layout", + "layout-auto": "Auto", + "layout-horizontal": "Horizontal", + "layout-vertical": "Vertical", + "item-size-label": "Item Size", + "item-size-small": "Small", + "item-size-medium": "Medium", + "item-size-large": "Large", + "config-launcher-label": "Config" + }, + "language-switcher": { + "title": "Change Application Language", + "dropdown-label": "Select a Language", + "save-button": "Save", + "success-msg": "Language Updated to" + }, + "theme-maker": { + "title": "Theme Configurator", + "export-button": "Export Custom Variables", + "reset-button": "Reset Styles for", + "show-all-button": "Show All Variables", + "save-button": "Save", + "cancel-button": "Cancel", + "saved-toast": "{theme} Updated Successfully", + "copied-toast": "Theme data for {theme} copied to clipboard", + "reset-toast": "Custom Colors for {theme} Removed" + }, + "config-editor": { + "save-location-label": "Save Location", + "location-local-label": "Apply Locally", + "location-disk-label": "Write Changes to Config File", + "save-button": "Save Changes", + "valid-label": "Config is Valid", + "status-success-msg": "Task Complete", + "status-fail-msg": "Task Failed", + "success-msg-disk": "Config file written to disk successfully", + "success-msg-local": "Local changes saved successfully", + "success-note-l1": "The app should rebuild automatically.", + "success-note-l2": "This may take up to a minute.", + "success-note-l3": "You will need to refresh the page for changes to take effect.", + "error-msg-save-mode": "Please select a Save Mode: Local or File", + "error-msg-cannot-save": "An error occurred saving config", + "error-msg-bad-json": "Error in JSON, possibly malformed", + "warning-msg-validation": "Validation Warning" + }, + "app-rebuild": { + "title": "Rebuild Application", + "rebuild-note-l1": "A rebuild is required for changes written to the conf.yml file to take effect.", + "rebuild-note-l2": "This should happen automatically, but if it hasn't, you can manually trigger it here.", + "rebuild-note-l3": "This is not required for modifications stored locally.", + "rebuild-button": "Start Build", + "rebuilding-status-1": "Building...", + "rebuilding-status-2": "This may take a few minutes", + "error-permission": "You do no have permission to trigger this action", + "success-msg": "Build completed succesfully", + "fail-msg": "Build operation failed", + "reload-note": "A page reload is now required for changes to take effect", + "reload-button": "Reload Page" + }, + "cloud-sync": { + "title": "Cloud Backup & Restore", + "intro-l1": "Cloud backup and restore is an optional feature, that enables you to upload your config to the internet, and then restore it on any other device or instance of Dashy.", + "intro-l2": "All data is fully end-to-end encrypted with AES, using your password as the key.", + "intro-l3": "For more info, please see the", + "backup-title-setup": "Make a Backup", + "backup-title-update": "Update Backup", + "password-label-setup": "Choose a Password", + "password-label-update": "Enter your Password", + "backup-button-setup": "Backup", + "backup-button-update": "Update Backup", + "backup-id-label": "Your Backup ID", + "backup-id-note": "This is used to restore from backups later. So keep it, along with your password somewhere safe.", + "restore-title": "Restore a Backup", + "restore-id-label": "Restore ID", + "restore-password-label": "Password", + "restore-button": "Restore", + "backup-error-unknown": "Unable to process request", + "backup-error-password": "Incorrect password. Please enter your current password.", + "backup-success-msg": "Completed Successfully", + "restore-success-msg": "Config Restored Successfully" + } +} \ No newline at end of file diff --git a/src/components/Configuration/CloudBackupRestore.vue b/src/components/Configuration/CloudBackupRestore.vue index 8c1b5261..36b00f8d 100644 --- a/src/components/Configuration/CloudBackupRestore.vue +++ b/src/components/Configuration/CloudBackupRestore.vue @@ -1,55 +1,55 @@