carmel-fe initial design

[adriatic]

All UI elements needs to be KendoUI of course - as otherwise having a cool feature like theme manager would make no sense.

---

This document starts with the basic shell:

which (shell) gives us "Catalog-compliant" navigation infrastructure. The green numbers 1 - 5 indicate the 5 clicks (in that order) that defined the "deepest" path to the context of basic use for scatter charts.

The rest of this article discusses the content of the green rectangle - the area in which all carmel-fe actions take place. Let's use the "handle" carmel editor reference that area, which consists of editor toolbar and editing surface.

The implicit assumption is that the context for the carmel editor is completely defined once the component (red markers 1, 2, 3 and 4) and sample (red marker 5) are selected. See testing carmel-api with postman section to find out more about fetching the editor context. In that situation the context for autocomplete component is defined as:

  {
    "name": "Autocomplete",
    "created": "2017-04-01T15:54:02.8626205Z",
    "componentTags": [
      {
        "id": 1,
        "cTag": "autocomplete"
      }
    ],
    "samples": [
      {
        "id": 248,
        "name": "with.bind",
        "created": "2017-04-01T15:54:02.8631511Z",
        "gist": "2fa190db778824c2b406b10c673ae9ae",
        "sampleTags": []
      },
      {
        "id": 249,
        "name": "highlighting",
        "created": "2017-04-01T15:54:02.8636514Z",
        "gist": "078dec4fe353ff9214ef6d5ee0e091a7",
        "sampleTags": []
      },
      {
        "id": 250,
        "name": "value-binding",
        "created": "2017-04-01T15:54:02.8636514Z",
        "gist": "ba981cf9b774273a75bb6a4dedf21190",
        "sampleTags": []
      },
      {
        "id": 251,
        "name": "grouping",
        "created": "2017-04-01T15:54:02.8636514Z",
        "gist": "5da30e9c363cf37fe3e313476a65edb4",
        "sampleTags": []
      },
      {
        "id": 252,
        "name": "virtualization",
        "created": "2017-04-01T15:54:02.8636514Z",
        "gist": "1abf5f5fbb4d3e1306385506bc676aff",
        "sampleTags": []
      },
      {
        "id": 253,
        "name": "server-filtering",
        "created": "2017-04-01T15:54:02.8636514Z",
        "gist": "65f25b1fb2e07ec4e2749d21136650e7",
        "sampleTags": []
      },
      {
        "id": 254,
        "name": "events",
        "created": "2017-04-01T15:54:02.8636514Z",
        "gist": "625fc6a733b599fa9374d732ae5e696d",
        "sampleTags": []
      },
      {
        "id": 255,
        "name": "customizing-templates",
        "created": "2017-04-01T15:54:02.8636514Z",
        "gist": "f4755c3c68dab68260647851ff9e52a0",
        "sampleTags": []
      },
      {
        "id": 256,
        "name": "api",
        "created": "2017-04-01T15:54:02.8636514Z",
        "gist": "55999353554add4f866b26481f0ad555",
        "sampleTags": []
      },
      {
        "id": 257,
        "name": "basic-use",
        "created": "2017-04-01T15:54:02.8636514Z",
        "gist": "0ddb2e1d4ff26b988382c9150d4fc475",
        "sampleTags": []
      }
    ]
  },

[adriatic]

1. Simplest carmel editor implementation

This design expands on the idea introduced on Image 2 in article carmel user interface design and is based on the following assumptions:

1. GitHub authentication is required to gain access to carmel editor tagging function. Specifically, non-authenticated users will see the whole carmel editor disabled. This will entice people to use this functionality by loging in. Note that we will not require different credentials from any user - but we will keep track of more "advanced" user and assign them different access rights than default, which is given to any authenticated user.

2. While we will not start with fully blown editor from the very start, we need to discuss whether offering support for tagging and adding more samples for any existing component is sufficient to get people to use this tool. See analysis of carmel editor functionality for more information on this topic.

[adriatic]

1.1 editor toolbar

Toolbar elements (buttons) are bound to the auth0 user object which is provisioned by carmel administrator. At the moment we have two provisioned users:

• bridge editor
• bridge-user

Note: this data is visible only when authenticated to Auth0.

I suggest using this version of the toolbar, disregarding the content shown below (send should be save, etc):

having the image of the user is a nice detail for example

Notes:

• It is likely that the same toolbar could be used for all supported types of editing (tags, adding more samples to an existing component and adding new components), where we will initially start with just adding / editing tags. The actual design of the toolbar is left to @Thanood.

[adriatic]

1.2 editing surface

Until someone comes up with a better solution, I propose this tag editor which will behave as shown below:

[adriatic]

1.3 Two level database updates

As discussed between @JeroenVinke and @adriatic earlier today in gitter ☝️ April 1, 2017 12:36 PM, carmel editor has to implement the support for "delayed database updates", where user editing results with per/user database record and a "message" to the carmel administrator that there are edits that need to be merged in the database. Mimicking GitHub Pull Requests in a minimal fashion is probably the best way to do this quickly.

This approach should be used the same way for the Tag editor, and for the more complex Component / Sample editor to be implemented after the Tag editor.

[Thanood]

Can we already say how the user model will look like?

If we create different toolbars (or rather different buttons in the same toolbar) for brigde user and bridge editor we need to store user and claims/roles somewhere. This will probably be a User class, maybe provided by a UserService or dependency injection..

Do we already have a concept of that?

[Thanood]

@adriatic Please have a look at my sample interface definition which should resemble your definition in this post.

Let's see if I got your idea correctly. 😃
These interfaces would be used as the model of carmel-editor component.

[adriatic]

On security user model

Auth0 takes care of all that by persisting and providing the management ui for all security related data.

This is why there is no such data in carmel-api SQL Server database.

[Thanood]

The editor will need to know which role is active, right? Sure, Auth0 will provide that information. My question was if we already have a model for that. It will supposedly be the one which Auth0 provides. Correct?

[adriatic]

Yes of course. While I am happy to be always "online" for Auth0 issues, I will also suggest what information to read in order to gain additional knowledge (this is always a good thing).

In addition to providing "interactive" dashboard for manual provisioning of "everything" related to users and their rights / limitation, all this information is also available as API (so the application can do all that working itself, without having to have a human do it). As this could be more work than we can afford at this point, we should use the Dashboard based provisioning.

[adriatic]

on carmel editor model

I believe that there are a few attributes missing or incorrect:

• The tags[] object was initially planned to have more complex structure than just being an array of strings. I shrunk it for expediency reasons, leaving that for later version of carmel. However in this initial implementation, every occurrence of a tag should be an array of strings - including IComponentTag, which is the only preloaded with data (name of the component). It should certainly be possible to add more than one tag to the component.

• we should maintain the user name attribute as a part of the persisted data, so we could later identify who did what (reward the person with most contribution 😄). Note that this information comes from the Auth0 user object (this is a completely standard information from Oauth).

@JeroenVinke - is there still something missing?

[adriatic]

I hope to get the basic aurelia navigation skeleton app (viewed as a SPA) authenticate itself to a basic web API server (work I am doing for Aurelia-Auth0 organization done for tomorrow. This would allow us to discuss the carmel issues in a more concrete context.

[JeroenVinke]

@JeroenVinke - is there still something missing?

Yeah, definitions for proposals, but those are not defined yet. We can add those as we go this week

[adriatic]

1.4 Authentication UI

I suggest to take the most standard approach and add the Login / Logout links (right aligned) to the carmel nav-bar

The user could decide to first click on the Login link (button) and then continue doing stuff, or to be automatically redirected to the auth0-lock widget:

This approach allows access to some menu bar items that everyone can see (About, Help)

We will of course customize this widget (offering GitHub based authentication by default, and id/password UI for administrators)

[adriatic]

@JeroenVinke
Definitions for proposals ??

[JeroenVinke]

We don't want changes to be visible on the catalog right away, we want the changes to be "proposals" and those proposals need to be merged before we show them on the catalog

[adriatic]

True - and at the same time, you might be mixing catalog UI with carmel UI; in this discussion, we are describing carmel app only (that does not mean that at some time we will not switch focus on catalog, of course).

Unless we merge catalog and carmel into one app (something I would not favor), catalog ui should be nearly trivial, allowing "composite" search (often referred to as advanced search).

[JeroenVinke]

True - and at the same time, you might be mixing catalog UI with carmel UI; in this discussion, we are describing carmel app only (that does not mean that at some time we will not switch focus on catalog, of course).

I don't know why you think i'm mixing them up. Carmel (UI + backend) is the entity that should prevent changes from being visible on the catalog right away, without having someone merge the changes in Carmel. So a proposal system is something we do need to think about in the carmel UI

Unless we merge catalog and carmel into one app (something I would not favor), catalog ui should be nearly trivial, allowing "composite" search (often referred to as advanced search).

I never said anything about making changes to the catalog itself, I only talked about a system in Carmel that ensures that the data sent from carmel to the catalog has always been verified by a 3rd party.

[adriatic]

Are you a bit touchy today 😏 ? Note that I wrote the word might just to prevent such response (I do think ahead what reactions could I cause with my writing).

At the same time, you are correct that there is more UI needed to address this "two step workflow", which I will document (as my proposal, only) within one hour, when I return to my office

[adriatic]

Why thumbs down emoji?

[adriatic]

1.5 Ideas for two - step editing workflow

The user who logs in with the GitHub account does not see any manifestations of this dual step approach - other than the message that appear once he/she clicks on the Save button on the toolbar, which would tell the user that his changes will appear in carmel and catalog, once verified by carmel admin.

When the carmel admin logs in he will have an additional button on the tolbar that would open the page for accepting user created changes since last such action. This button should also show the number of pending changes to be approved - to indicate the "urgency" of this approval process.

It would be nice if the admin actions (approve / reject / approve with modifications) would be make available to the user who authored them, together with explanation why the admin decided to act as he did (send the email, or post to the specifically designed GitHub issue for this purpose)

Whoever believes that I am paying too much attention to details in the context of adding a simple tag - please be reminded that this whole exercise is really a practice for the aurelia / amazon compendium, where keeping contributors involved and informed is of a critical importance 😄 .

[Thanood]

@adriatic When you say every collection of tags right now should be an array of strings, do you mean you'd prefer to leave out the IDs for now?

export interface IComponentTag {
  cTag: string;
}

export interface ISampleTag {
  tag: string;
}

export interface ISampleDefinition {
  id: number;
  name: string;
  created: Date;
  gist: string;
  sampleTags: ISampleTag[];
}

export interface ICarmelSample {
  name: string;
  created: Date;
  componentTags: IComponentTag[];
  samples: ISampleDefinition[];
}

[adriatic]

@Thanood not sure what led you to believe that my today's description above has anything to do with using or not using IDs.

Let me first restate what I wanted to indicate, using the screenshot below, which represents the begining of the definition of the autocomplete component:

The entity cTag should be an array of strings, initialized in the database to its first component being being defined as the name of the component. This seems like a logical preset value to be already defined in the database, so the carmel user can search for it right away. This paragraph warrants two more comments:

• the cTag should be renamed to cTags to indicate that it is an array.
• carmel-fe UI should provide a simple search interface to simplify the navigation to the place where edits are going to be made. Such search would use these predefined (and all other already defined tags) as a shortcut to the more laborious navigation shown on the image in the above section.

I also want to address the presence and absence if integer IDs - please check this section for more information on this.

[adriatic]

reopened because it was closed by a bad click

[Thanood]

Is there any way to make the dropdown arrows point down? 😃
The toolbar is a direct copy of this sample: http://aurelia-ui-toolkits.github.io/demo-kendo/#/samples/toolbar-resize which I plan to adjust to our needs.

[adriatic]

My guess is that this is either "prebuilt" into the k-type="splitButton" entity - or defined somewhere in the telerik's (big) css file that lives in carmel. @JeroenVinke could know more.

[Thanood]

There is one thing I don't get concerning tags and cTag:

export interface IComponentTag {
  id: number;
  cTag: string;
}

export interface ICarmelSample {
  name: string;
  created: Date;
  componentTags: IComponentTag[];
  samples: ISampleDefinition[];
}

The entity ICarmelSample has an array of componentTags. Each one will have an id and a cTag. Which will eventually lead to a sample like this:

{
  name: 'my-component-sample',
  created: '20170403T00:00:00',
  componentTags: [
    { id: 1, cTag: 'my-component' },
    { id: 2, cTag: 'kendo-free' }
  ]
}

(please note that the second component tag is completely made up and probably doesn't make any real sense)

I understood that componentTags is the array holding one or more items of type ComponentTag which all have a single tag string (and thus the singular use of cTag). Please clarify if this is incorrect.

If so, please point me in the right direction to understand a structure like this which will be the result if using an array of cTags in an array of componentTags:

{
  name: 'my-component-sample',
  created: '20170403T00:00:00',
  componentTags: [
    { id: 1, cTags: ['my-component', 'kendo-free'] },
    { id: 2, cTag: ['navigation', 'tool-bar'] }
  ]
}

[Thanood]

The structure of IComponentTag above resembles the api structure in:
https://github.com/adriatic/carmelDbSeed/blob/master/node/code#L13
and
https://github.com/adriatic/carmelDbSeed/blob/master/dotnet/src/CarmelDbSeed/Models/ComponentTag.cs

[adriatic]

Good questions coming from the lack of clarity created by the switch where a tag was an object with elements like string, datetime, reference to an article outside of the carmel context etc. As this adds the difficulties related to serialization and deserialization, I changed the design to a lot simpler approach where a tag is always an array of strings.

In the case of the component (where I knew that the related tag (array of strings) can be initialized by setting this array's "first" (zero-th) element to the name of the components) so, the code should be like this

  {
    "name": "Autocomplete",
    "created": "2017-04-01T15:54:02.8626205Z",
    "cTag": ["autocomplete"],
...

Only by writing this I realized that I did not properly correct switch from the initial "complex tags" to "simple tags" - meaning that I have to really appologize to expose you to this "garbage".

The structure at https://github.com/adriatic/carmelDbSeed/blob/master/node/code#L13 is the old version of the code, that I hid in https://github.com/adriatic "organization" to not create confusion in aurelia-ui-tollkits

Thanks for persisting without asking me "are you aware how stupid this is, really?" 😏

Now, this requires immediate fix in the entity classes in the carmel-API and recreating of the database. Since I am clearly guilty of being careless, I will do this now, so you can find the correct pieces in carmel-API tomorrow.

Please let me know if we see this the same way now.

[Thanood]

Thanks, @adriatic that clears up a lot. 😃
Btw. I found your carmelDbSeed project by reading this issue: aurelia-ui-toolkits/carmel-api#3

I will have another look at carmel-api tomorrow.

[adriatic]

Thanks for this ack 😄

The issue aurelia-ui-toolkits/carmel-api#3 is created a while ago, and I rechecked it a few days back, to ensure that is has no references to the previous organization (http://github.com/adriatic) where I worked on learning how to and to put together the initial version of what is today carmel-api repo.

By saying

Btw. I found your carmelDbSeed project by reading this issue: aurelia-ui-toolkits/carmel-api#3

are you indicating that aurelia-ui-toolkits/carmel-api#3 has some incorrect references?

[Thanood]

This comment indeed has incorrect references: aurelia-ui-toolkits/carmel-api#3 (comment)

The references forward to your personal repo where I found the old code.

[adriatic]

Weird

The article you point up is this, where I show all links - and all seem to be correct to me. Not that this is really important, I just prefer to understand what we are discussing, completely:

[Thanood]

Step 2.2 - the node link: https://github.com/aurelia-ui-toolkits/carmelDbSeed/tree/master/node forwards to https://github.com/adriatic/carmelDbSeed/tree/master/node

Step 2.3 - the "code" link: https://github.com/aurelia-ui-toolkits/carmelDbSeed/blob/master/node/code of course has the same forward.

At least it does this for me. 😃

[adriatic]

At least it does this for me

... and for me as well (any other possibility would really concern me a lot 😄). Fixed.

[Thanood]

I've successfully implemented the proposed tag editor (52e54e0) but I've seen some drawbacks:

• (minor) no npm or jspm repo: need to include the library in index.html, no bundling or typings
• (minor) no good support for two-way data-binding: no removeAll or replace
• it's a jQuery plugin but there are only a few non-jQuery editors
• features such as drag&drop or auto-complete need additional jQuery UI plugins (I hate that)

I consider only the last one a major drawback.
Maybe we can find an alternative or migrate on of these angular/react tag-editors.

[adriatic]

I agree on all drawbacks and we should address them all. My initial idea behind using that jQuery based version was to save the time until we can get some alpha version of carmel out, so we can really assess what level of enthusiasm it would generate. Based on that we can embark on a more serious solution, while still retaining all of the "captured" tags in the database..

I will update my local copy of carmel, so I can give more comments in the context of this discussion item