@vue-layout/basic 🍙
A package containing basic components,
to build for example multi level navigation menus.
Note
The package is still in development and the API is still subject to change.
Besides, the documentation still needs to be expanded
Table of Contents
Installation
$ npm i --save @vue-layout/basic
Usage
To use the navigation component, a constant must be defined,
which satisfy the type: NavigationProvider
.
The implementation will provide different navigation elements for each tier
.
The tier
is a numeric value, which can reach from 0 to n (infinity).
module.ts
import {
NavigationElement,
NavigationProvider
} from "@vue-layout/basic";
const primaryItems : NavigationElement[] = [
{
name: 'Home',
url: '/',
icon: 'fa fa-home'
},
{
name: 'About',
url: '/about',
icon: 'fa fa-info'
}
]
export const navigationProvider : NavigationProvider = {
async hasTier(tier: number): Promise<boolean> {
return Promise.resolve(tier === 1);
},
async getElements(tier: number, items: NavigationElement[]): Promise<NavigationElement[]> {
switch (tier) {
case 0:
return primaryItems;
}
},
async getElementsActive(url: string): Promise<NavigationElement[]> {
if (url === '/') {
return [
primaryItems[0]
]
}
if (url === '/about') {
return [
primaryItems[1]
]
}
return undefined;
}
};
The next step is to create the vue entrypoint.
index.ts
import {
buildNavigation,
createPlugin
} from '@vue-layout/basic';
import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { navigationProvider } from './module';
const app = createApp();
app.use(createPlugin({
navigationProvider
}));
const router = createRouter({
history: createWebHistory(),
routes: [
],
});
app.use(router);
(async () => {
const url = router?.currentRoute?.value?.fullPath;
await buildNavigation({ url });
app.mount('#app');
})();
After those steps are completed, the NavigationComponents
SFC can be placed anywhere, if registered globally.
<template>
<div>
<navigation-components :tier="0" />
<navigation-components :tier="1" />
</div>
</template>
Functions
buildNavigation
▸ function
buildNavigation(context?: NavigationBuildContext
): Promise
<void
>
Build all navigation tiers, by url
or active elements
.
Example
URL
import { buildNavigation } from '@vue-layout/basic';
await buildNavigation({
url: '/'
});
This will call the getElementsActive
method of the NavigationProvider
implementation,
to calculate the active elements
.
items
import { buildNavigation } from '@vue-layout/basic';
await buildNavigation({
items: [
{id: 'default', tier: 0, name: 'Home'}
]
})
This element
array will be provided as second argument as context to the getElements
method of
the NavigationProvider
implementation, to build a specific tier navigation.
buildNavigationWithRoute
▸ function
buildNavigationWithRoute(context?: Partial<NavigationBuildRouteContext>
): Promise
<void
>
Build all navigation tiers, by route
(url) or by interpreting the metaKey
attribute of
a route component.
Example
route
import { RouteLocation } from 'vue-router';
import { buildNavigationWithRoute } from '@vue-layout/basic';
const route : RouteLocation = {
fullPath: '/',
...
};
await buildNavigationWithRoute({
route
})
This method call is under the hood equal to: buildNavigation({url: '/'})
.
metaKey
import { defineComponent } from 'vue';
import { buildNavigationWithRoute } from '@vue-layout/basic';
const metaKey = 'navigation';
const pageComponent = defineComponent({
meta: {
[metaKey]: [
{id: 'default', tier: 0, name: 'Home'}
]
},
...
});
await buildNavigationWithRoute({
metaKey
})
This method call is under the hood equal to:
buildNavigation({items: [{id: 'default', tier: 0, name: 'Home'}]})
.
Types
NavigationBuildContext
import { Component } from '@vue-layout/basic';
type NavigationBuildContext = {
items?: Component[],
url?: string
};
NavigationBuildRouteContext
import { RouteLocationNormalized } from 'vue-router';
type NavigationBuildRouteContext = {
route: RouteLocationNormalized,
metaKey: string
};
NavigationElement
type NavigationElement = {
id?: string | number,
tier?: number,
name?: string,
url?: string,
urlTarget?: '_self' | '_blank' | '_parent' | '_top' | string,
default?: boolean,
type?: 'separator' | 'link',
icon?: string,
environment?: 'development' | 'production' | 'testing',
display?: boolean,
displayChildren?: boolean,
rootLink?: boolean,
children?: NavigationElement[],
requireLoggedIn?: boolean,
requireLoggedOut?: boolean,
requirePermissions?: string | string[] | ((checker: (name: string) => boolean) => boolean)
[key: string]: any
};
NavigationProvider
import { NavigationElement } from '@vue-layout/basic';
declare type NavigationProvider = {
getElements: (tier: number, items: NavigationElement[]) => Promise<NavigationElement[]>,
getElementsActive: (url: string) => Promise<NavigationElement[]>,
hasTier: (tier: number) => Promise<boolean>
};
Example
For an implementation example, on how to use this library, check out the example
package.
License
Made with 💚
Published under MIT License.