cooptilleuls/hm-admin

hm-admin is an angular2 component which help you to build backoffice automatically for an hypermedia API

Hm-admin

Description

The main goal of this project is to provide a self-generated backoffice which take advantage of the context describe in Hypermedia API. This backoffice should be easy to override via simple configuration variables but must have a good abstraction to allow a deep override if the integrator need it.

The backoffice should respect some rules:

• Keep it simple: this project will not cover all the weirdo cases that your client will invent. It's a basis. Huge enough to allow a lot of people to use it with small configuration, but a small basis to contains only required features. (In a second time, the app may be able to allow plugins to increase the features but first things first).
• Keep it clean: this project, by default, respect some auto-discipline (coding guidelines, high code coverage ratio, ...). As this project becomes your project, it's not mandatory to follow them but if you want, you can find them right here.
• Keep it User-friendly: this project follows the Material design recommandations to provide a full responsive and nice experience for the final user. It's not a matter about feeding the troll on the Apple/Android war. Those recommendations made their proofs so we use them.

As the full stack of typescript + compilation + tests + ... is quite pain in the ass to install, this project is based on angular-cli.

Let's start

Requirements

• Git
• NPM (we don't use leftpad so everything should be fine ;))
• An Hypermedia API (Have you ever heard of API Platform?)

Installation

First, clone the project

git clone [email protected]:coopTilleuls/hm-admin.git name-of-your-project 
cd name-of-your-project

Note from Captain Obvious: Don't forget to replace name-of-your-project by your project's name.

Then you can install dependencies and start your project

npm install -g angular-cli
ng serve

And that's it...

Configuration

Nice try but your app throw an error cause it can't reach your API. Ok. Google himself doesn't know the path of your API. Or maybe they know? ... hmm. Whatever. There's a minimum configuration that is required and it's your API's path, so let's fill it in the src/app/exemples/admin/configuration.ts file. There you will find all the stuffs you can configure (items in menu, displayed field in list, ...)

Contribution

This project is pretty huge and any help is welcome so feel free to contribute. There's a lot of things to do, each level of contribution may help (documentation, hotfix, compatibility, big features, ...). Thank you.

FAQ

I want to test this awesome tool but I don't have any Hypermedia API. Do you have some advice for me?

Yes, of course. Have you ever heard of API Platform? This solution helps you to build complex API, compatible with schema.org in a few minutes without being a monster in PHP, Java or any languages. Just some configuration steps.

hm-admin's Issues

Order filter in the list view

As a user
When I navigate to list view
And I click on a column header
Then the content should be ordered by this row

List of items in sidenav

As a user
When I click on the hamburger menu of the headbar
Then I should see a list of available entities in the sidenav

HTTP call done twice

The APIService::getCollectionByUrl() trigger the http call twice (to be clear, I’m not talking about the OPTIONS http method here). This is due to the query.subscribe used to handle an error.

https://github.com/coopTilleuls/hm-admin/blob/master/src/app/hm-admin/services/api/api.service.ts#L36

My opinion is we should not interfere with the Rxjs observable error workflow and let the error live is nasty little life until someone who knows how to handle it catch it up.

Still in my opinion and arguably, the error should almost never be catched by the APIService. The error should bubble up to the final subscriber.

Anyhow, I bet that the error workflow is broken here since the exception is thrown asynchronuously and therefore is hardly catchable.

In case that my point was not clear: My fix proposition is to remove this subscription purely and simply ;)

E2E Tests

As a dev
I want the application to be E2E testable

Install and configure Protractor + cucumber + write docs which bring together some resources about those two (just link, no need to sum up)

Update Typings according to their updates.

Prerequisites

• Are you running the latest version of your current branch?
• Did you check your issue is not already reported?
• Have you tried to poke someone on Gitter?

Description

Typings install is done with global and not ambient

Steps to Reproduce

Install the project

Expected behavior: typings of the project should be isntalled

Actual behavior: Nothing installed

Context

any OS

hotfix processes: update the contributing guide

When twgit hotfix start is used, twgit fire a new branch, based on the last commit of stable branch. Creating, for instance, a branch named hotfix/0.2.3

Then, when twgit hotfix finish is used, twgit merge the hotfix branch into stable, tag it, etc.

Problem is: When multiple hotfix PR are created in parallel, the async party begins, and a hotfix 0.2.5 could be mergeable before 0.2.3.

So, with hm-admin here is the hotfix process:

twgit feature start fix-blablabla
gaa && gc...
g push myfork
...
review
merge
...
twgit hotfix start
twgit feature merge-into-hotfix fix-blablabla
twgit hotfix finish

---

ps ironic note: I appreciate github warning me with this message while I’m filling this issue:

Please review the guidelines for contributing to this repository.

So now, it’s not just async party time, it’s circular reference party time too! 🎉 🎈 🎂

Move configuration into a dist file

Configuration should be in a dist file and a NPM task should help user to make a smart copy of the dist file on npm post-install

Pagination on the list

As a user
When I navigate to the list view of an entity
And I click on page 2 button
Then the list of content should refresh to display the second page of content

List view

As a User,
When I navigate to list view of an entity
Then I should see all content of the API for this entity in a table

Call API to get entrypoints core documentation

See doc

Call API to get entrypoints documentation

Call API to get entities documentation

See doc

Range is not extracted from schema (hydra)

Property’s “Range” attribute is not populate from schema and definition.

Try to add docker container

Provide a way to know if hm-admin is ready

Prerequisites

• Are you running the latest version of your current branch?
• Did you check your issue is not already reported?
• Have you tried to poke someone on Gitter?

Description

Since CoreDefinitionService::loadDefinitions() and SchemaService::loadSchema() don’t return observables (they return undefined), there is no way to know if hmadmin is ready or not.

Hence, I can’t add a pre-loader to my components waiting for hm-admin to do its initialization black magic.

I would love to have, as @Gregcop1 suggest, an “appReady” observable/promise

Add an PR template for Github

We have to add a PR template for Github, in order to get faster with the description of the PR.

Search filter in the list view

Take advantage of the "hydra:search" node in the response of get collection to know available filters

As a user
When I navigate to list view
And I fill the search input
Then the list should refresh with filtered content