Proof of Concept V1

Omschrijving

Voor de PoC (Proof of Concept) wordt er een CMS dashboard gemaakt met het PHP framework Laravel en de package Backpack. Bij LiveWall wordt er veel gewerkt met externe API’s. Één van de meest gebruikte is de Spotify API. De data wordt vanuit de API opgeslagen in de MySQL database. In het CMS moet de data kunnen worden ingezien en bewerkt. Op de CMS homepagina worden grafieken met de spotify gegevens getoont. Om aan te tonen dat het dashboard customizable is wordt het dashboard gemaakt in de huisstijl van spotify. 

Korte beschrijving van de front-end en CMS:

Front-end:

1. User ziet de meest populaire tracks en artiesten uit de database en een Spotify login button.
2. User logt in.
3. User ziet zijn/haar eigen top 15 meest populaire tracks en artiesten en een terug naar home button. 
4. User ziet op de homepagina de top 15 meest populaire tracks en artiesten, nu aangevuld met zijn/haar eigen data. 

Backpack CMS:

1. Een admin logt in.
2. Een admin krijgt een dashboard pagina te zien met grafieken gebaseerd op de data uit de api/database zoals aantal nieuwe gebruikers, hoeveelheid verborgen/zichtbare artiesten en aantal nieuwe nummers en artiesten.
3. Een admin kan naar verschillende pagina’s met tabellen en hier de data beheren van de artiesten en tracks (bewerken en verwijderen). 
4. De data kan bewerkt worden in het CMS zoals het uploaden van een nieuwe album cover of artiest foto. 
5. In de tabel kan de data worden aangepast zodat het niet meer in de front-end wordt getoont. 
6. Een admin kan bij de CMS gebruikers rollen en permissies aanmaken en beheren.

Requirements

Must haves: deze requirements moeten in het eindresultaat terugkomen, zonder deze eisen is het product niet genoeg verbeterd.
Should haves: deze eisen zijn zeer gewenst, maar zonder is het product wel bruikbaar.
Could haves: deze eisen zullen alleen aan bod komen als er tijd genoeg is.
Won't haves: deze eisen zullen in dit project niet aan bod komen maar kunnen in de toekomst, bij een vervolgproject, interessant zijn.

Functional requirements

ID	Requirement	Priority	Geïmplementeerd
FR 1	Mogelijkheid om gemakkelijk de kleuren van het dashboard aan te passen in de code.	Must have	✓
FR 2	Mogelijkheid om gemakkelijk verschillende formaten logo’s toe te voegen aan de navigatie	Must have	✓
FR 3	Mogelijkheid voor customization van elementen van de user interface vanuit een settings pagina in het CMS.	Should have
FR 3.1	Mogelijkheid om de kleur van de navigatie aan te passen.	Should have
FR 3.2	Mogelijkheid om kleur van de knoppen aan te passen.	Should have
FR 3.3	Mogelijkheid om logo aan te passen in de CMS navigatie.	Should have
FR 4	Mogelijkheid om een profiel afbeelding toe te voegen/veranderen als gebruiker in het CMS.	Must have	✓
FR 5	Mogelijkheid om het navigatiemenu in te klappen.	Must have	✓ Dit zit standaard in Backpack
FR 6	Mogelijkheid om Bulk delete acties uit te voeren in een tabel.	Must have	✓
FR 7	Mogelijkheid om globaal te zoeken in een tabel.	Must have	✓ Dit zit standaard bij de list operations
FR 8	Mogelijkheid om contactinformatie te bekijken.	Should have
FR 9	Mogelijkheid om contactinformatie aan te passen voor admin users.	Should have
FR 10	Mogelijkheid om in een wysiwyg editor afbeeldingen te kunnen croppen.	Should have
FR 11	Mogelijkheid om een afbeelding te drag en droppen in een file input field.	Could have
FR 12	Mogelijkheid om een logboek toe te voegen.	Could have
FR 13	Mogelijkheid om uitgebreid te filter, sorteren en zoeken in de tabellen.	Must have	✓
FR 14	Mogelijkheid om verschillende en/of eigen chart libraries te kunnen gebruiken.	Must have	✓
FR 15	Mogelijkheid om users aan te maken in het CMS met  verschillende rollen.	Must have	✓
FR 16	Mogelijkheid voor admin gebruikers om user rollen te beheren.	Must have	✓
FR 17	Mogelijkheid om in te loggen in de front-end met een Spotify Account	Must have	✓
FR 18	De spotify gebruiker ziet op zijn/haar persoonlijke pagina hun top15 artiesten en nummers	Must have	✓
FR 19	De front-end homepagina toont de 15 meest populaire artiesten en nummers gebaseerd op spotify popularity	Must have	✓
FR 20	Grafieken op de dashboard pagina in het CMS tonen data vanuit de database.	Must have	✓
FR 21	Admin gebruikers kunnen nummers en artiesten beheren in een tabel, zoals bewerken en verwijderen.	Must have	✓
FR 21.1	Admin gebruikers kunnen van artiesten/nummers de zichtbaarheid status veranderen.	Must have	✓
FR 21.2	Admin gebruikers kunnen de gegevens van een artiest/nummer bewerken	Must have	✓

 

Non-functional requirements

ID	Requirement	Priority
NFR 1	Security: Customization is alleen mogelijk voor users met de admin rol.	Medium
NFR 2	Security: De admin krijgt niet de mogelijkheid om de admin rol verwijderen.	Medium
NFR 3	Usability: Het CMS moet responsive zijn voor laptop/desktop formaten.	High
NFR 4	Usability: Het CMS moet responsive zijn voor mobile.	Medium
NFR 5	Usability: Alle uitgebreide filter opties op één plek.	High
NFR 6	Usability: De knoppen moeten duidelijk zichtbaar zijn.	High
NFR 7	Usability: De iconen moeten visueel overeenkomen met de functie die zij vertegenwoordigen.	High
NFR 8	Readability: Tekst in tabellen moeten worden afgekapt op woorden niet op karakters.	Medium
NFR 9	Usability: Alle standaard teksten van het CMS moeten beschikbaar zijn in het Nederlands	Medium

Uitwerking PoC-V1

 

PoC-V1 Demo video

1. Database en CRUD pagina’s

Als eerste is de code van het prototype gekopieerd. Het prototype is opgezet met behulp van de video course in de Backpack documentatie waarin Backpack wordt opgezet samen met een aantal CRUD elementen zoals Tags, Categories en Articles.

De code van het prototype is de basis van het proof of concept. In de draft.yml file is de database structuur verder uitgebreid met “SpotifyUser”, “TopArtist” en “TopTrack” inclusief de relaties tussen tabellen. Deze draft.yml wordt uitgevoerd met behulp van blueprint. Met blueprint:build worden alle nodige files voor deze tabellen aangemaakt zoals Migrations en Models. Met php artisan backpack:build wordt automatisch voor alle models zonder een CRUD pagina een CRUD controller aangemaakt. Deze CRUD pagina’s worden ook automatisch toegevoegd in de Routes en in de sitenavigatie file. 

Als laatste moeten de database structuren nog gemigreerd worden naar de (lokale)database met php artisan migrate. Binnen enkele minuten staat de volledige CRUD paginas voor Spotify users, top artiesten en top tracks.

draft.yml file voor het aanmaken van models en migrations met blueprint

2. Spotify API

Met de database en de CRUD pagina’s volledig opgezet is het tijd voor het connecten met de Spotify API. Om gebruik te maken van de spotify API moet er een account worden aangemaakt in het Spotify developers dashboard. In dit dashboard krijg je een Client secret en een Client ID. De Client ID, Client Secret en Redirect URI worden opgeslagen in de .env in het project. 

In de SpotifyController.php wordt er met behulp van Laravel Socialite en de gegevens uit de env file connectie gemaakt met de Spotify API. 

SpotifyController.php waar de Spotify API data wordt opgehaald en opgeslagen in de database

Wat de controller in het kort doet is het verbinden van de api met een request voor bijvoorbeeld alle topartiesten van de user. Er wordt gecontroleerd of de data uit de request al in de database staat. Als dat niet het geval is wordt de data toegevoegd, zo wel wordt er nog gecheckt of de data al gelinkt is met de user. 

Tussen de Spotify User en Topartiesten/Topnummers wordt er gebruik gemaakt van een Many-to-Many relationship. Spotify users kunnen meerdere nummers/artiesten hebben en Nummers/artiesten kunnen meerdere spotify users hebben. Om dit goed te koppelen wordt er gebruik gemaakt van een pivot table. In deze pivot table worden de id’s van gebruikers en van de nummers/artiesten opgeslagen. 

Als alle data gecontroleerd en opgeslagen is wordt het getoont op de front-end overview pagina’s waar de data wordt gedisplayed.

Front-end algemene overview pagina met top15 artiesten en nummers gesorteerd op meest populair op Spotify

3. CRUD controllers en custom buttons

In de controllers files TopArtistCrudController.php en de TopTrackCrudController.php wordt de tabel en velden aangemaakt voor de CRUD view in het CMS. Dit is waar er echt met Backpack wordt gewerkt. 

Boven in de controller worden operations gedefinieerd. Deze operations zijn kant en klare functies van Backpack. In de TopArtistCrudController wordt er gebruikgemaakt van 4 operations:

class TopArtistCrudController extends CrudController
{
    use \Backpack\CRUD\app\Http\Controllers\Operations\ListOperation;
    use \Backpack\CRUD\app\Http\Controllers\Operations\UpdateOperation;
    use \Backpack\CRUD\app\Http\Controllers\Operations\DeleteOperation;
    use \Backpack\CRUD\app\Http\Controllers\Operations\BulkDeleteOperation;

De operations spreken vrij voor zich, de list operation genereert in het CMS een tabel met alle data entries van de bijbehorende tabel. De update en Delete operations genereren een knop voor het updaten en verwijderen van een entry. De bulk delete operation zorgt voor een checkbox bij elke entry en een algemene verwijder knop.

voorbeeld wat de verschillende operations creëreV.

In de setup wordt de model, route en namen gedefinieerd om te bepalen welke data wordt gebruikt in de tabel.

public function setup()
{
    CRUD::setModel(\App\Models\TopArtist::class);
    CRUD::setRoute(config('backpack.base.route_prefix') . '/top-artist');
    CRUD::setEntityNameStrings('top artist', 'top artists');
}

In de setupListOperation wordt bepaald welke kolommen er in de tabel staan en met welke data. In de documentatie over columns kun je alle type kolommen terug vinden vergezeld door een aantal voorbeeld en optionele opties. Er zit ook een kolom type tussen voor relations zodat je direct de data van gerelateerde tabellen kunt displayen in de tabel.

CRUD::addcolumn([
    'name' => 'spotifyusers',
    'label' => 'Gebruiker(s)',
    'type' => 'relationship',
    'orderable' => true,
]);

Verder in de setupListOperation worden de filters aangemaakt. Net als de columns zijn deze uitgebreid gedocumenteerd en zijn er opties om custom filters toe te voegen. Filters worden automatisch toegevoegd aan de filter bar net boven de kolom. 

Als laatste zijn er nog optionele opties zoals pagina lengtes, responsive tabel, orderby etc…

$this->crud->setDefaultPageLength(10); //page length is 10 items
$this->crud->disableResponsiveTable(); //disable tabel responsiveness 
$this->crud->orderBy('id', 'ASC'); //sort table by item id ascending

Custom button in de tabel

Voor het verbergen en tonen van artiesten/nummers in de tabel is er gebruik gemaakt van een custom button. Hiervoor is de documentatie en example gevolgd voor het maken van een custom button met een blade file. 

$this->crud->addButtonFromView('line', 'visibility', 'visibility', 'beginning');

De addButtonFromView method voegt letterlijk de visibility.blade.php file toe die in de resource folder staat. In deze file wordt aan de hand van de status in de database bepaald wat de tekst en waarde is van de knop voor elke entry individueel. 

Bewerken 

Als laatste in de CrudController staat de setupCreateOperation. In dit stuk wordt de pagina gemaakt voor het updaten en creëren van een entry. In het geval van dit POC wordt er alleen gebruik gemaakt van updaten. De opzet van deze field lijkt sprekend op de opzet van de kolommen. Ook deze staan uitgebreid gedocumenteerd met opties voor custom fields.

4. Custom dashboard styling 

Backpack komt standaard met twee verschillende stylingen een blauwe en een paarse variant. In de documentatie staat beschreven dat je de css van het dashboard kan vervangen in de config/backpack/base.php Door één van deze standaard files te kopieëren en je style.css file van te maken kan je de styling van het dashboard overschrijven. De custom file in dit dashboard is de custom-backpack-bundel.scss. In het bovenste deel van de file kan je de variabele kleuren aanpassen, deze worden daarmee gelijk door het gehele dashboard aangepast. Ook de noty alert messages maken gebruik van deze kleuren. 

In de base.php kan je ook een logo toevoegen met gebruik van een html , echter is er voor gekozen om in dit geval een div met de class custom-logo toe te voegen en de image in de custom css in te laden. Dit zal later nog aangepast moeten worden wanneer de customizer geïmplementeerd wordt.

In de Base.php kan je met de standaard geleverde classes van Backpack snel de kleuren van de side en top navigatie aanpassen. Ondanks de redelijk grote keuze uit kleuren kwam er geen overeen met de typische donkere Spotify kleur. Daarom is er de .bg-custom class toegevoegd. In een korte tijd kan de algemene styling van Backpack eenvoudig ge-customized worden. 

Dashboard met de standaard blauwe Backpack styling

Dashboard met de custom Spotify styling

5. Profiel pagina 

De profiel pagina aanpassen kan op verschillende manieren, als je gebruik  wilt maken een ander soort Avatar bijvoorbeeld een Gravatar kan dit veranderd worden in de config/backpack/base.php. Het is in deze file niet mogelijk om een optie te maken waardoor de gebruiker zelf een afbeelding kan uploaden. Daarom worden de files van de user profile gekopieerd en aangepast. 

In de documentatie staat bij het aanpassen van naam en e-mail kort beschreven hoe je deze extra input velden kan toevoegen aan de user profile maar nergens staat specifiek hoe je een image upload functie toevoegt terwijl er in de Backpack demo duidelijk een profielfoto te zien is.

In de User model worden de velden toegevoegd zoals image, telephone en fuction. Deze velden worden ook toegevoegd aan de migration voor de User tabel. In de my_account.blade.php file die gekopieerd is van de Backpack vendor folder wordt in HTML de velden toegevoegd aan het formulier.

In dit geval wordt er ook een veld toegevoegd met JQuery om de afbeelding voor het uploaden te previewen. De profiel afbeelding moet ook toegevoegd worden aan de top navigatie bar. Daarvoor wordt de menu_user_dropdown.blade.php gekopieerd en aangepast.

Als laatste moet de route naar de User Profile worden aangepast zodat deze naar de custom pagina gaat. Dit wordt gedaan in de routes/backpack/base.php waar de controller van de routes worden veranderd naar de custom user profile controller.

De standaard user profile pagina

De custom user profile pagina met nieuwe input velden

6. Taal aanpassen

In de documentatie wordt goed beschreven hoe je de vertaalde strings kunt aanpassen. Standaard komt Backpack al met o.a Nederlandse vertalingen. Je kunt deze files overschrijven om zo eigen vertalingen toe te voegen. Je kan het systeem op deze manier ook makkelijk multilingual maken.

 

7. Authenticatie

Voor de authenticatie is er gebruik gemaakt van de officiële gratis add-on Permission Manager. Permission manager is een authenticatie interface die gebruik maakt van spatie/laravel-permission. Tijdens de installatie wordt de authenticatie toegevoegd aan de navigatie met een dropdown menu. Het installeren van deze add-on was eenvoudig, en het toepassen van permissies in de Controller files zoals de CRUD controller werkt hetzelfde als in Laravel met Auth.

Auth check op de artist_id field. Alleen users met een admin rol kunnen dit veld zien.

Permissies kunnen overal worden toegepast, ook in de blade.php files. In deze PoC zijn er gebruikers aangemaakt met verschillende rollen zoals Admin en Reader. Als je inlogt als Reader zijn de permissies zo ingesteld dat je de Authenticatie opties verborgen zijn in de navigatie. 

Permissies en rollen kunnen gemakkelijk worden beheerd in het CMS. Een user kan ook een rol krijg met specifieke permissies die buiten de rol vallen. Bijvoorbeeld een Reader met de permissies om ook de Authenticatie te kunnen zien.

Uiteraard moeten al deze rollen en permissies in de code worden aangegeven en kan je niet zomaar een nieuwe permissies toevoegen in het CMS ondanks dat hier wel een knop voor is.

Auth check in een blade.php file, met het gebruik van has any role. Alleen Super Admin's en Admin's krijgen het authenticatie menu.

De user rol pagina in het CMS

8. Grafieken

Grafieken vallen onder widgets. Widgets kunnen overal op de site worden toegepast. Net als de columns en fields staan de default widgets gedocumenteerd en is het ook mogelijk om custom widgets te maken. 

De chart widget maakt gebruik van consoletvs/chart. Met behulp van de command php artisan backpack:chart [name of chart] wordt er een chart controller gegenereerd en toegevoegd aan de routes. Met consoles tvs kan er gebruik worden gemaakt van een aantal verschillende chart libraries zoals chartjs, Echarts, Fusioncharts, Highcharts, C3 en Frappe charts. In deze versie wordt alleen gebruik gemaakt van Chartjs, in het de volgende versie worden ook andere chart libraries getest.

9. Image upload & Stackoverflow

Het moeilijkste element tijdens het implementeren was de image upload bij het aanpassen van een album/artiest foto. Hierbij was er een probleem met het uploaden van een afbeelding die (lokaal) in het systeem wordt opgeslagen en de URL afbeelding die uit de Spotify API komt. Voor de afbeelding upload is er gebruik gemaakt van de image upload documentatie waarbij er een public functie setImageAttribute($value) wordt gebruikt. In dit deze functie wordt de afbeelding gecheckt,  opgeslagen in het CMS en wordt het pad gelinkt aan de data. Doordat de spotify images een link zijn werden deze niet opgeslagen omdat er geen pad is.

Na veel trial en error is het probleem op Stackoverflow geplaatst. Ondanks het probleem de volgende dag al was gevonden waren er dezelfde dag een reacties met een bevestiging dat de gevonden oplossing goed was. 

De oplossing was om een check toe te voegen waarop gecheckt wordt om wat voor type image het gaat en anders wordt de spotify link toegevoegd in het in de database.

Stackoverflow reactie

Conclusie

Het opzetten en aanmaken van de CRUD pagina’s ging gemakkelijk. Voor bijna alle elementen die gebruikt zijn, was er voldoende documentatie beschikbaar. In het geval van specifieke vragen was een Google search genoeg om een antwoord op GitHub of Stack Overflow te vinden.

Momenteel beschikt dit PoC niet over de meest ingewikkelde elementen die een CMS nodig heeft, maar het PoC geeft een goede indruk waar Backpack tot toe in staat is. Backpack zit over het algemeen niet in de weg voor het maken van maatwerk elementen, iets wat bij Orchid vaker wel het geval was. Het maken custom buttons, columns, fields, widgets en zelfs custom styling staat goed gedocumenteerd op de Backpack website. 

Doordat Backpack niet te veel afwijkt van de Laravel structuur, goede documentatie heeft en een actieve community is het instap niveau lager vergeleken met Orchid. 

Om te bepalen of het Backpack CMS daadwerkelijk gebruiksvriendelijker is dan het Larawall CMS wordt er een user test uitgevoerd. Na de user test worden de verbetering verwerkt in het PoC-V2.