@sedona-cms/core

Sedona CMS

Usage no npm install needed!

<script type="module">
  import sedonaCmsCore from 'https://cdn.skypack.dev/@sedona-cms/core';
</script>

README

Node.js Package


Sedona CMS

Admin Panel for Nuxt.js sites

View Demo · Report Bug


Table of Contents

About the Project

Sedona CMS can create a beautiful and fully customizable admin panel on the frontend site.

Built With

Getting Started

Prerequisites

Setup

  1. Add @sedona-cms/core dependency to your project
npm i @sedona-cms/core # or yarn add @sedona-cms/core

  1. Add @sedona-cms/core to the modules section of nuxt.config.js

  2. Create sedona.config.json in project root and create admin folder in src root. Will be fixed

  3. Add plugin in client mode

admin.client.js

export default async function (ctx) {
  // check for user logged in
  await ctx.$adminLoader.load()
}

nuxt.config.js

export default {
  modules: ['@sedona-cms/core'],
  plugins: ['~plugins/admin.client.js'],
}

Usage

Config

sedona.config.json has two main sections.

  1. toolbar – toolbar customization, adding buttons, changing title
  2. items – menu customization, add items, sections and subitems

Config file has json schema. This tool helps validate config when module loading. And edit the file without errors.

Editing the config file may be handier with WebStorm or VS Code.

  1. Webstorm – Languages and Frameworks -> Schemas and DTDs -> JSON Schema Mappings

Toolbar Configuration

toolbar section (object)

type ToolbarConfig = {
  showHome: boolean
  title: string
  buttons: ToolbarButton[]
}

type ToolbarButton = {
  title: string
  icon: string
  component: string
}

Menu Items Configuration

A menu item may be of 3 display variants:

  1. item – a simple menu item
  2. header – a subheader item (not clickable)
  3. section – an item can navigate to another menu list

Examples:

Simple menu item with required fields only

{
  "title": "Post List",
  "type": "item",
  "component": "posts/posts-view"
}

Simple menu item with all available fields

{
  "title": "Post List",
  "type": "item",
  "component": "posts/posts-view",
  "icon": "edit",
  "subTitle": "Managment posts",
  "params": {
    "lang": "ru"
  }
}

Menu item

type MenuItem = SimpleMenuItem | HeaderMenuItem | SectionMenuItem

Simple menu item

type SimpleMenuItem = {
  id?: string
  title?: string
  subTitle?: string
  icon?: string
  type: 'item'
  component?: string | Function
  params?: {
    [key: string]: any
  }
  conditions?: MenuItemCondition[]
}

Header menu item

type HeaderMenuItem = {
  id?: string
  title?: string
  type: 'header'
  conditions?: MenuItemCondition[]
}

Section menu item

type SectionMenuItem = {
  id?: string
  title?: string
  subTitle?: string
  icon?: string
  type: 'section'
  items?: MenuItem[]
  conditions?: MenuItemCondition[]
}

The Visibility of Menu Items

By default, all menu items show on each page on site. This behavior may be changed in the config file.

The visibility depends on a current Vue route. All components have a property $route. Use the $route property in conditions you can change the visibility of menu items on-site pages.

The $route properties that can be used in conditions:

  1. name
  2. path
  3. meta

Type of conditions that can be used.

  1. =
  2. regex

Examples:

The menu item shows only on-page about. The item shows only on pages when the condition returns true $route.name === 'about'

{
  "title": "Test",
  "type": "item",
  "component": "posts/posts-view",
  "conditions": [
    {
      "field": "name",
      "value": "about"
    }
  ]
}

The menu item shows only on page about or index. The item shows only on pages when the condition returns true $route.name === 'about' || $route.name === 'index'

{
  "title": "Test",
  "type": "item",
  "component": "posts/posts-view",
  "conditions": [
    {
      "field": "name",
      "value": "about"
    },
    {
      "field": "name",
      "value": "index"
    }
  ]
}

Save Panel

Each admin view can have a save panel. The Save Panel is a panel in a bottom with a button.

Enable the save panel

Add save attribute to menu item configuration:

{
  "title": "Post Edit",
  "type": "item",
  "icon": "edit",
  "component": "posts/post-edit",
  "save": true
}

You can change the Save Panel options:

{
  "title": "Post Edit",
  "type": "item",
  "icon": "edit",
  "component": "posts/post-edit",
  "save": {
    "label": "Save Post",
    "color": "brown-5",
    "size": "xl"

}

Set disabled state for the Save Panel

In posts/post-edit:

<script>
  import { eventBus } from '@sedona-cms/core/lib/utils/event-bus'

  export default {
    name: 'PostEdit',
    mounted() {
      eventBus.emit('core:save-disable', true)
    },
  }
</script>

Set loading state for the Save Panel

In posts/post-edit:

<script>
  import { eventBus } from '@sedona-cms/core/lib/utils/event-bus'

  export default {
    name: 'PostEdit',
    methods: {
      save() {
        eventBus.emit('core:save-loading', true)
        // A request here
        eventBus.emit('core:save-loading', false)
      },
    },
  }
</script>

Catch click event

<script>
  import { eventBus } from '@sedona-cms/core/lib/utils/event-bus'

  export default {
    name: 'PostEdit',
    mounted() {
      eventBus.on('core:save-click', this.save)
    },
    beforeDestroy() {
      eventBus.off('core:save-click', this.save)
    },
    methods: {
      save() {},
    },
  }
</script>

Lock Navigation

Sometimes we need to lock navigation in Admin Panel. For example when form fill and not saved yet. Navigation API will may to lock navigation in Admin Panel and on the site.

Lock navigation

this.$sedona.navigate.lock()

  • Arguments:
    • globally
  • Example:
export default {
  name: 'PostEdit',
  methods: {
    onChange() {
      this.$sedona.navigate.lock()
    },
  },
}

Unlock navigation

this.$sedona.navigate.unlock()

  • Arguments:
  • Example:
export default {
  name: 'PostEdit',
  methods: {
    onChange() {
      this.$sedona.navigate.lock()
    },
    onSave() {
      this.$sedona.navigate.unlock()
    },
  },
}

Check for is navigation lock

export default {
  name: 'PostEdit',
  computed: {
    buttonDisable() {
      return this.$sedona.navigation.isLock
    },
  },
}

Programmatic Navigation

Examples:

Go to PostView and provide postId prop

export default {
  name: 'Posts',
  methods: {
    goToPost() {
      this.$sedona.navigate('posts/post-view', {
        postId: 12,
      })
    },
  },
}

Go to component by a path with Save Panel

export default {
  name: 'Posts',
  methods: {
    goToPost() {
      this.$sedona.navigate(
        'posts/post-view',
        {
          postId: 12,
        },
        {
          save: true,
        }
      )
    },
  },
}

Events

Sedona CMS uses own global event bus.

Using example:

import { eventBus } from '@sedona-cms/core/lib/utils/event-bus'

eventBus.on('sedona:loaded', () => console.log('Fired after Sedona Core loaded'))

Used Events:

  • sedona:loaded (no args) – Sedona CMS core loaded

  • sedona:panel-loaded (no args) – Sedona CMS panel loaded

  • core:navigate (item: MenuItem) – change an active panel

  • core:lock-navigate (flag: boolean) – if flag is true to lock a navigation

  • core:save-click (no args) – A click on Save button

  • core:save-loading (boolean) – Set a loading state for Save button

  • core:save-disable (boolean) – Set a disabled state for Save button

Development

  1. Install dependencies
npm ci
  1. Link the package in which it is run
npx npm-self-link
  1. Run watch process
npm run watch # typescript watch process
  1. Run nuxt project from dev directory
npm run dev

Tests

Run unit tests for utils

npm run test:utils

Run unit tests for Vue components with vue-test-utils

npm run test:components

Run e2e test (not implemented yet)

npm run test:e2e

Run all test

npm run test