pixelindustries/elegant-asgard

Provides a powerful and elegant way to manage (CRUD) your Eloquent models with AsgardCMS

1.0.0-alpha4 2015-06-25 12:45 UTC

README

PXL icon

Build Status Coverage Status Code Climate SensioLabs

Overview

Elegant Asgard provides a simple and powerful way to manage your application's Eloquent models. Elegant generates your CMS dynamically by analyzing your models. Furthermore, thanks to the powerful and flexible role-based permissions system that AsgardCMS comes with, you have fine-grained control regarding which roles have what permissions over your models.

It's important to note that Elegant functions in a non-obtrusive and non-destructive way. Elegant will never change your models in any way, nor will Elegant modify your database. Elegant solely analyzes your models and underlying datastructure. In other words, Elegant is a drop-in solution which you can safely remove later at any time without affecting your application's inner workings. It simply provides a dynamic and flexible CRUD user interface on top of your models.

Requirements

Elegant is built as a module which you can use within your existing Asgard installation. As such, Elegant cannot be used as a standalone package without Asgard. For more information regarding Asgard, please refer to the official AsgardCMS github page.

Installation

In the root of your existing AsgardCMS project, simply pull in Elegant via composer:

composer require pixelindustries/elegant-asgard

Elegant's internals

Elegants keeps a local file called elegant.json in your application's storage_path(). This file contains serialized information that Elegant uses as a means of storing all data regarding to Elegant's settings and knowlegde about your models. It is highly recommended to add and track this file into your VCS, so the CMS is ready to go when you're deploying your whole application on another server.

Permissions

Elegant dynamically creates permissions within Asgard for your models, with the exception of one static set of permissions for the Model Settings component that ships with Elegant. After installing Elegant, you should assign the elegant.modelsettings.index and elegant.modelsettings.edit permissions for user roles that need to do administrative actions within the CMS. After that, you should see the sidebar update:

elegant 1

This component is the administrative panel of Elegant itself, where certain settings per model can be edited, such as display or positioning of fields. This functionality is currently under development.

Do keep in mind that since Elegant creates permissions dynamically, you will have to assign the relevant permissions that are generated to the roles that need them. In other words, if you're not seeing your models show up in the sidebar for example, always check the permissions first:

elegant 2

In order for your models to show up in the sidebar, you need to assign the index permission to the corresponding user role. For example, when we assign that permission to the above models, the sidebar will be as follows:

elegant 3

Refreshing Elegant's knowledge about your models

When you add new models in your application or simply make a change to an existing model (such as adding a package or changing the underlying datamodel of the model), you should refresh Elegant's knowledge about your models. This can be done using a simply artisan command-line command:

php artisan elegant:refresh

Optionally, you can use the --force flag in order to completely whipe the local storage file that Elegant keeps and force the system to start with a fresh one.