Skip to content

armgit / dashy

Public Imported from GitHub
0

πŸš€ A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!

✨ Adds alias functionality, to jump strait to app from URL path

Alicia Sykesaa02393ec702
diff --git a/docs/configuring.md b/docs/configuring.md
index 29427262..5dc28671 100644
--- a/docs/configuring.md
+++ b/docs/configuring.md
@@ -270,6 +270,7 @@ For more info, see the **[Authentication Docs](/docs/authentication.md)**
**`icon`** | `string` | _Optional_ | The icon for a given item. Can be a font-awesome icon, favicon, remote URL or local URL. See [`item.icon`](#sectionicon-and-sectionitemicon)
**`target`** | `string` | _Optional_ | The opening method for when the item is clicked, either `newtab`, `sametab`, `modal`, `workspace`, `clipboard`, `top` or `parent`. Where `newtab` will open the link in a new tab, `sametab` will open it in the current tab, and `modal` will open a pop-up modal, `workspace` will open in the Workspace view and `clipboard` will copy the URL to system clipboard (but not launch app). Defaults to `newtab`
**`hotkey`** | `number` | _Optional_ | Give frequently opened applications a numeric hotkey, between `0 - 9`. You can then just press that key to launch that application.
+**`alias`** | `string` | _Optional_ | A short lowercase word which, when visited as a path on your dashboard (e.g. `/some-app`), redirects straight to this item's URL. See [URL Aliases](/docs/searching.md#url-aliases)
**`tags`** | `string[]` | _Optional_ | A list of tags, which can be used for improved search
**`statusCheck`** | `boolean` | _Optional_ | When set to `true`, Dashy will ping the URL associated with the current service, and display its status as a dot next to the item. The value here will override `appConfig.statusCheck` so you can turn off or on checks for a given service. Defaults to `appConfig.statusCheck`, falls back to `false`
**`statusCheckUrl`** | `string` | _Optional_ | If you've enabled `statusCheck`, and want to use a different URL to what is defined under the item, then specify it here
diff --git a/docs/searching.md b/docs/searching.md
index 7dd10e5d..f055c437 100644
--- a/docs/searching.md
+++ b/docs/searching.md
@@ -14,7 +14,7 @@ You can launch a elected app by hitting <kbd>Enter</kbd>. This will open the app
## Tags
-By default, when searching items are filtered by the `title`, (as well as the `url`, `provider` and `description`). If you need to find results based on text which isn't included in these attributes, then you can add `tags` to a given item.
+By default, when searching items are filtered by the `title`, (as well as the `url`, `provider`, `description` and `alias`). If you need to find results based on text which isn't included in these attributes, then you can add `tags` to a given item.
```yaml
items:
@@ -65,6 +65,28 @@ For apps that you use regularly, you can set a custom keybinding. Use the `hotke
In the above example, pressing <kbd>2</kbd> will launch Bookstack. Or hitting <kbd>3</kbd> will open Git in the workspace view.
+## URL Aliases
+
+Set an `alias` on an item, and visiting that word as a path on your dashboard will redirect you straight to the item's URL. This lets you jump to an app by typing `dashy/jelly` into the address bar, without loading the dashboard first.
+
+```yaml
+- title: Jellyfin
+ icon: sh-jellyfin
+ url: https://jellyfin.lab.local
+ alias: jelly
+```
+
+Above, visiting `https://dashy.lab.local/jelly` sends you to Jellyfin. Matching ignores case, and an alias which doesn't match any item shows the 404 page. Aliases are also searchable, so typing `jelly` into Dashy's search will surface Jellyfin.
+
+Some limitations to be aware of:
+- Aliases must be lowercase, may only contain letters, numbers, hyphens and underscores
+- Only items in your main config file are reachable - items on [multi-page](/docs/pages-and-sections.md) sub-pages are not
+- Only `http://` and `https://` item URLs can be redirected to
+- Items hidden from the current user (via `displayData`) are not reachable by their alias (you need to login to a user with access first)
+- Requires history routing (the default). Under `VITE_APP_ROUTING_MODE=hash` the URL would need to be `dashy/#/jelly`
+- It's not possible to create aliases for pages Dashy already uses, including: 'home', 'minimal', 'workspace', 'login', 'download' and '404'
+- If two items share an alias, the first one in the config wins
+
## Web Search
It's possible to launch a web search directly from Dashy, which might be useful if you're using Dashy as your start page. This can be done by typing your query as normal, and then pressing <kbd>⏎</kbd>/Enter. Web search options are configured under `appConfig.webSearch`.
diff --git a/src/main.js b/src/main.js
index 3d290e75..b61360e8 100644
--- a/src/main.js
+++ b/src/main.js
@@ -72,6 +72,9 @@ const handleAuthFailure = (provider, err) => {
const needsOidcLoginPage = () => isOidcLoginPageEnabled() && !isLoggedIn()
&& router.currentRoute.value.name !== 'login';
+/* A guard can abort the first navigation (like an item alias redirect), leaving no route to render */
+const skipMount = () => {};
+
router.isReady().then(() => {
if (isOidcEnabled()) {
initOidcAuth().then((reloading) => {
@@ -86,4 +89,4 @@ router.isReady().then(() => {
} else {
mount();
}
-});
+}, skipMount);
diff --git a/src/router.js b/src/router.js
index f47d232f..a71a9ae3 100644
--- a/src/router.js
+++ b/src/router.js
@@ -20,7 +20,7 @@ import { isOidcEnabled } from '@/utils/auth/OidcAuth';
import { isKeycloakEnabled } from '@/utils/auth/KeycloakAuth';
import { isHeaderAuthEnabled } from '@/utils/auth/HeaderAuth';
import { startingView as defaultStartingView, routePaths } from '@/utils/config/defaults';
-import { VIEW_META } from '@/utils/config/ConfigHelpers';
+import { VIEW_META, getUrlForAlias } from '@/utils/config/ConfigHelpers';
import ErrorHandler from '@/utils/logging/ErrorHandler';
const progress = new Progress({ color: 'var(--progress-bar)' });
@@ -123,6 +123,18 @@ const router = createRouter({
next();
},
},
+ { // Item aliases, where /<alias> redirects straight to that item's URL
+ path: '/:alias',
+ name: 'alias',
+ component: () => import('./views/404.vue'),
+ beforeEnter: (to, from, next) => {
+ const url = getUrlForAlias(store.state.rootConfig?.sections, to.params.alias);
+ if (!url) { next('/404'); return; }
+ window.location.replace(url);
+ progress.end();
+ next(false);
+ },
+ },
{ // Redirect any not-found routed to the 404 view
path: '/:pathMatch(.*)*',
redirect: '/404',
diff --git a/src/utils/Search.js b/src/utils/Search.js
index e3feabb7..71c4f8a0 100644
--- a/src/utils/Search.js
+++ b/src/utils/Search.js
@@ -12,13 +12,13 @@ const haystackCache = new WeakMap();
const buildHaystack = (tile) => {
const {
- title, description, provider, url, tags, subItems,
+ title, description, provider, url, tags, alias, subItems,
} = tile;
const tagsStr = Array.isArray(tags) ? tags.join(' ') : (tags || '');
const subText = Array.isArray(subItems)
? subItems.map((s) => `${s.title || ''} ${s.url || ''}`).join(' ')
: '';
- return normalize(`${title || ''} ${provider || ''} ${description || ''} ${tagsStr} ${url || ''} ${subText}`);
+ return normalize(`${title || ''} ${provider || ''} ${description || ''} ${tagsStr} ${url || ''} ${alias || ''} ${subText}`);
};
const getHaystack = (tile) => {
@@ -32,7 +32,7 @@ const getHaystack = (tile) => {
/**
* Filter tiles based on users search term, and returns a filtered list
- * Will match based on title, description, provider, hostname from url and tags
+ * Will match based on title, description, provider, hostname from url, tags and alias
* Ignores case, special characters and other irrelevant things
* @param {array} allTiles An array of tiles
* @param {string} searchTerm The users search term
diff --git a/src/utils/config/ConfigHelpers.js b/src/utils/config/ConfigHelpers.js
index 42c1bb78..0a2b17a5 100644
--- a/src/utils/config/ConfigHelpers.js
+++ b/src/utils/config/ConfigHelpers.js
@@ -1,9 +1,11 @@
import ConfigAccumulator from '@/utils/config/ConfigAccumalator';
import filterUserSections from '@/utils/CheckSectionVisibility';
+import checkItemVisibility from '@/utils/CheckItemVisibility';
import { languages } from '@/utils/languages';
import {
visibleComponents,
localStorageKeys,
+ routePaths,
language as defaultLanguage,
} from '@/utils/config/defaults';
@@ -189,6 +191,33 @@ export const getCustomKeyShortcuts = (sections) => (sections || [])
.filter((item) => item.hotkey)
.map((item) => ({ hotkey: item.hotkey, url: item.url })));
+/* Paths owned by Dashy's own views, so can never be claimed as an item alias */
+export const RESERVED_ALIASES = Object.freeze(
+ Object.values(routePaths).map((path) => path.replace(/^\//, '')),
+);
+
+/* Lowercases and strips any surrounding slashes, so alias matching is forgiving */
+const normalizeAlias = (alias) => String(alias ?? '').trim().toLowerCase().replace(/^\/+|\/+$/g, '');
+
+/* Redirects must go somewhere absolute and browsable, never to javascript: or a relative path */
+const isRedirectable = (url) => {
+ try { return ['http:', 'https:'].includes(new URL(url).protocol); } catch { return false; }
+};
+
+/**
+ * Returns the URL of the item assigned the given alias, used for /<alias> redirects
+ * Pass the root config's sections, so a redirect never depends on the page being viewed
+ */
+export const getUrlForAlias = (sections, alias) => {
+ const target = normalizeAlias(alias);
+ if (!target || RESERVED_ALIASES.includes(target)) return undefined;
+ const match = filterUserSections(sections || [])
+ .flatMap((section) => section.items || [])
+ .find((item) => item.alias && normalizeAlias(item.alias) === target);
+ if (!match || !checkItemVisibility(match) || !isRedirectable(match.url)) return undefined;
+ return match.url;
+};
+
/**
* Gets the users chosen language. Defaults to English.
* If for any reason a lang code changes, add to legacyAliases for backwards compat
diff --git a/src/utils/config/ConfigSchema.json b/src/utils/config/ConfigSchema.json
index 1b951f1d..f2285736 100644
--- a/src/utils/config/ConfigSchema.json
+++ b/src/utils/config/ConfigSchema.json
@@ -1311,6 +1311,15 @@
"type": "number",
"description": "A numeric shortcut key, between 0 and 9. Useful for quickly launching frequently used applications"
},
+ "alias": {
+ "title": "URL Alias",
+ "type": "string",
+ "pattern": "^[a-z0-9_-]+$",
+ "not": {
+ "enum": ["home", "minimal", "workspace", "login", "download", "404"]
+ },
+ "description": "A short lowercase word which, when visited as a path on your dashboard (e.g. /my-app), redirects straight to this item"
+ },
"rel": {
"title": "rel",
"type": "string",
diff --git a/tests/unit/alias-visibility.test.js b/tests/unit/alias-visibility.test.js
new file mode 100644
index 00000000..9facbcc6
--- /dev/null
+++ b/tests/unit/alias-visibility.test.js
@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@/utils/auth/Auth', () => ({
+ getCurrentUser: () => mockUser,
+ isLoggedInAsGuest: () => mockIsGuest,
+}));
+
+let mockUser = false;
+let mockIsGuest = false;
+
+const { getUrlForAlias } = await import('@/utils/config/ConfigHelpers');
+
+const withItem = (displayData) => [{ items: [{ alias: 'app', url: 'https://app.local', displayData }] }];
+const withSection = (displayData) => [{ displayData, items: [{ alias: 'app', url: 'https://app.local' }] }];
+const setGroups = (info) => { localStorage.getItem.mockReturnValue(info ? JSON.stringify(info) : null); };
+
+describe('getUrlForAlias - visibility rules', () => {
+ beforeEach(() => {
+ mockUser = false;
+ mockIsGuest = false;
+ setGroups(null);
+ });
+
+ it('resolves an item with no visibility rules', () => {
+ expect(getUrlForAlias(withItem(undefined), 'app')).toBe('https://app.local');
+ });
+
+ it('honours hideForUsers on the item', () => {
+ mockUser = { user: 'alice' };
+ expect(getUrlForAlias(withItem({ hideForUsers: ['Alice'] }), 'app')).toBeUndefined();
+ expect(getUrlForAlias(withItem({ hideForUsers: ['bob'] }), 'app')).toBe('https://app.local');
+ });
+
+ it('honours showForUsers on the item', () => {
+ mockUser = { user: 'alice' };
+ expect(getUrlForAlias(withItem({ showForUsers: ['bob'] }), 'app')).toBeUndefined();
+ expect(getUrlForAlias(withItem({ showForUsers: ['alice'] }), 'app')).toBe('https://app.local');
+ });
+
+ it('honours hideForGuests when browsing as a guest', () => {
+ mockIsGuest = true;
+ expect(getUrlForAlias(withItem({ hideForGuests: true }), 'app')).toBeUndefined();
+ mockIsGuest = false;
+ expect(getUrlForAlias(withItem({ hideForGuests: true }), 'app')).toBe('https://app.local');
+ });
+
+ it('honours hideForGroups and hideForRoles', () => {
+ setGroups({ groups: ['devs'], roles: ['viewer'] });
+ expect(getUrlForAlias(withItem({ hideForGroups: ['devs'] }), 'app')).toBeUndefined();
+ expect(getUrlForAlias(withItem({ hideForRoles: ['viewer'] }), 'app')).toBeUndefined();
+ expect(getUrlForAlias(withItem({ hideForGroups: ['admins'] }), 'app')).toBe('https://app.local');
+ });
+
+ it('honours showForGroups and showForRoles', () => {
+ setGroups({ groups: ['devs'], roles: ['viewer'] });
+ expect(getUrlForAlias(withItem({ showForGroups: ['admins'] }), 'app')).toBeUndefined();
+ expect(getUrlForAlias(withItem({ showForGroups: ['devs'] }), 'app')).toBe('https://app.local');
+ expect(getUrlForAlias(withItem({ showForRoles: ['viewer'] }), 'app')).toBe('https://app.local');
+ });
+
+ it('honours the same rules applied at section level', () => {
+ mockUser = { user: 'alice' };
+ expect(getUrlForAlias(withSection({ hideForUsers: ['alice'] }), 'app')).toBeUndefined();
+ expect(getUrlForAlias(withSection({ showForUsers: ['bob'] }), 'app')).toBeUndefined();
+ expect(getUrlForAlias(withSection({ hideForUsers: ['bob'] }), 'app')).toBe('https://app.local');
+ });
+});
diff --git a/tests/unit/config-helpers.test.js b/tests/unit/config-helpers.test.js
index 48a7d112..33fadf39 100644
--- a/tests/unit/config-helpers.test.js
+++ b/tests/unit/config-helpers.test.js
@@ -10,7 +10,10 @@ import {
formatConfigPath,
componentVisibility,
getCustomKeyShortcuts,
+ getUrlForAlias,
+ RESERVED_ALIASES,
} from '@/utils/config/ConfigHelpers';
+import schema from '@/utils/config/ConfigSchema.json';
describe('ConfigHelpers - makePageName', () => {
it('converts page name to lowercase', () => {
@@ -400,3 +403,97 @@ describe('ConfigHelpers - getCustomKeyShortcuts', () => {
expect(getCustomKeyShortcuts(undefined)).toEqual([]);
});
});
+
+describe('ConfigHelpers - getUrlForAlias', () => {
+ const sections = [
+ { name: 'Media', items: [{ title: 'Jellyfin', alias: 'Jelly', url: 'https://jelly.local' }] },
+ { name: 'Widgets Only', widgets: [{ type: 'embed' }] },
+ { name: 'Tools', items: [{ title: 'No alias', url: 'https://nope.local' }] },
+ ];
+
+ it('returns the URL of the item with a matching alias', () => {
+ expect(getUrlForAlias(sections, 'jelly')).toBe('https://jelly.local');
+ });
+
+ it('matches regardless of case, whitespace or surrounding slashes', () => {
+ expect(getUrlForAlias(sections, ' /JELLY/ ')).toBe('https://jelly.local');
+ });
+
+ it('returns undefined when no item claims the alias', () => {
+ expect(getUrlForAlias(sections, 'plex')).toBeUndefined();
+ });
+
+ it('never matches items that have no alias', () => {
+ const noAliases = [{ items: [{ title: 'No alias', url: 'https://nope.local' }] }];
+ expect(getUrlForAlias(noAliases, 'anything')).toBeUndefined();
+ expect(getUrlForAlias(noAliases, '')).toBeUndefined();
+ });
+
+ it('does not let a blank alias be reached by a blank lookup', () => {
+ const blank = [{ items: [{ alias: ' ', url: 'https://blank.local' }] }];
+ expect(getUrlForAlias(blank, '')).toBeUndefined();
+ expect(getUrlForAlias(blank, ' ')).toBeUndefined();
+ });
+
+ it('ignores aliases YAML has coerced to a non-string', () => {
+ const coerced = [{ items: [{ alias: 0, url: 'https://zero.local' }, { alias: false, url: 'https://no.local' }] }];
+ expect(getUrlForAlias(coerced, '0')).toBeUndefined();
+ expect(getUrlForAlias(coerced, 'false')).toBeUndefined();
+ });
+
+ it('refuses to redirect anywhere that is not an absolute http(s) URL', () => {
+ const unsafe = [{
+ items: [
+ { alias: 'xss', url: "javascript:alert('x')" },
+ { alias: 'loop', url: 'loop' },
+ { alias: 'mail', url: 'mailto:[email protected]' },
+ { alias: 'none', title: 'No URL' },
+ ],
+ }];
+ ['xss', 'loop', 'mail', 'none'].forEach((a) => expect(getUrlForAlias(unsafe, a)).toBeUndefined());
+ });
+
+ it('skips items the current user is not allowed to see', () => {
+ const hidden = [{
+ items: [{ alias: 'secret', url: 'https://secret.local', displayData: { showForGroups: ['admins'] } }],
+ }];
+ expect(getUrlForAlias(hidden, 'secret')).toBeUndefined();
+ });
+
+ it('skips items inside a section the current user cannot see', () => {
+ const hidden = [{
+ displayData: { showForGroups: ['admins'] },
+ items: [{ alias: 'secret', url: 'https://secret.local' }],
+ }];
+ expect(getUrlForAlias(hidden, 'secret')).toBeUndefined();
+ });
+
+ it('refuses every reserved word, even when an item claims it', () => {
+ const shadowing = [{
+ items: RESERVED_ALIASES.map((word) => ({ alias: word, url: `https://evil.local/${word}` })),
+ }];
+ RESERVED_ALIASES.forEach((word) => expect(getUrlForAlias(shadowing, word)).toBeUndefined());
+ });
+
+ it('returns undefined for null or undefined sections', () => {
+ expect(getUrlForAlias(null, 'jelly')).toBeUndefined();
+ expect(getUrlForAlias(undefined, 'jelly')).toBeUndefined();
+ });
+});
+
+describe('ConfigSchema - item alias', () => {
+ const aliasSchema = schema.properties.sections.items.properties.items.items.properties.alias;
+ const RESERVED = ['404', 'download', 'home', 'login', 'minimal', 'workspace'];
+
+ it('reserves the same words in the schema as the router does at runtime', () => {
+ expect([...RESERVED_ALIASES].sort()).toEqual(RESERVED);
+ expect([...aliasSchema.not.enum].sort()).toEqual(RESERVED);
+ });
+
+ it.each([
+ ['jelly', true], ['git-tea', true], ['my_app', true], ['app2', true],
+ ['Jelly', false], ['has space', false], ['a/b', false], ['', false],
+ ])('accepts %j in the config: %s', (alias, valid) => {
+ expect(new RegExp(aliasSchema.pattern).test(alias)).toBe(valid);
+ });
+});
diff --git a/tests/unit/search.test.js b/tests/unit/search.test.js
index 5d98efdf..6a8f3e54 100644
--- a/tests/unit/search.test.js
+++ b/tests/unit/search.test.js
@@ -58,6 +58,16 @@ describe('Search - searchTiles', () => {
expect(searchTiles([t], 'primary')).toHaveLength(1);
});
+ it('matches an item by its url alias', () => {
+ const t = tile({
+ title: 'Jellyfin', description: '', provider: '', url: 'https://media.lab', tags: [], alias: 'watchstuff',
+ });
+ expect(searchTiles([t], 'watchstuff')).toHaveLength(1);
+ expect(searchTiles([t], 'WATCHSTUFF')).toHaveLength(1);
+ expect(searchTiles([t], 'watchstuff media')).toHaveLength(1);
+ expect(searchTiles([{ ...t, alias: undefined }], 'watchstuff')).toHaveLength(0);
+ });
+
it('matches across multiple fields when the query has several words', () => {
const t = tile({ title: 'Plex', description: 'Media server', tags: [] });
expect(searchTiles([t], 'plex media')).toHaveLength(1);