moving carmel forward

[adriatic]

This article connects to the carmel-fe initial design, trying to re-state the current situation and allow us to continue carmel app development.

[adriatic]

Here is the most current status of this application:

My initial feedback is (making me very happy) that this is nearly sufficient for what we want to do for the alpha release of this tool that is at the moment completely focused on KendoUI catalog application.

In order to get to this point completely, I am proposing the following changes:

1. Remove parts of the UI

2. Fix the nav-bar

We should make the About menu item be default item, and use that panel to provide all explanations needed to run this app.

Next we should subject the Components menu item to authentication. While we may provide the Login menu item (right justified on the nav-bar), the click on the Components will result with the prompt to authenticate (using Auth0 Lock widget.

Last in this series of actions, we will customize the lock to offer two modes of authentication:

• GitHub that will be used by any carmel user as the minimum requirement to be allowed to define tags.
• [userID, password] pair used for the carmel admins.

3. Fill in the gigantic hole created by the decision to make carmel look like a catalog, when the only real functionality is to to support tagging, UI for which requires just a few lines worth of carmel editor's surface.

As I believe that tags can best be created in the context they are being applied to, we should make carmel mimic the catalog's behavior - at least until we upgrade carmel in the next release, to take over all catalog's tasks. By mimic, I mean this rendering when navigating to a specific sample for a specific component (Box Plot Charts in this case)

where the red lines indicate the removal of unneeded parts of the UI and the rest of this rendering shows as a screenshot from the catalog - it should look like this:

Note that I plan to add all these screenshots to the carmel-api database, so that you do not need to work on making any extra work on the front end side (other than defining the API (item 6 below).

[adriatic]

Issue left to discuss

1. How many tags do we allow
2. Should tag creators be allowed to edit tags - or should this be limited to admins
3. How to initiate tag creation / editing session
4. I believe that tags should be autosaved (on timer and or switch-away from the current page)
5. A more complicated decision is whether to allow GitHub authenticated users to have a free rein on Tags creation / editing - or to require "double step", similar to GitHub PRs where the admins merge user's edits to carmel.
6. Define the API for carmel-api to expose in order to make carmel-fe completely happy.
7. ... add more here

Since the process of adding new samples is a lot more obvious case where this PR like approach is mandated, perhaps we should bite the bullet (item 5. above) rather sooner than later.

Since you own aurelia-fe, please keep using the master repo - and in the case you may ask me to do something there, I will create a PR. The same rule with inverted roles applies to carmel-api

[Thanood]

1. Very good question.. My rather generic answer would be: "as many as makes sense for a search engine" - which is not an easy question as too many can easily lead to result relevancy being meaningless and too few can lead to samples being hard to find. So, maybe even to limit ourselves to the most relevant tags, let's start with five (preferably, that number will be configurable).

2. Editing a tag would (from the sample's point of view) be the same as deleting a tag and adding a new one with the desired name. So I say tag creators may edit tags. Overtime we could add an admin feature to ban certain "spam" tags of this gets misused.

3. IMO closely related to 4, so I'll give my comment there.

4. The data sent per edit session is likely to be very small, so we could easily save when the tags update (that is, when the user finishes entering a tag with enter or deletes a tag). In this case the edit session starts immediately when the sample is displayed and ends when tags are changed (and then starts again). There's a drawback when using a timer or navigation: the user may close the window between timer "ticks" or before leaving the current page.

5. see 2 - I think the same applies here, replacing "tag creators" with "GitHub authenticated users".

6. Screenshots: Is there an api needed? We could store the images like <gist-id>.png and load that image. Of course, that would not be nicely readable to a human being.

[Thanood]

I've only now noticed that editing a tag is not really the same like removing and adding a new tag since it changes the tags of other samples (tags are references).

[adriatic]

In the order in which your comments are written:

1. I like the "configurable" sizes - not sure though how will this play with the "database programming". Leaving this open for now, as this is well defined issue.

2. I agree with more freedom approach (we can always clamp it down if needed)

3. the edit session starts immediately when the sample is displayed and ends when tags are changed (and then starts again) - perfect 😄

4. Addressed in 3 above

5. Agreed.

6. Since the screenshots are a temporary fix, I propose not to mess with gists, but rather to add the image as the atttribute to the model of each sample. That way it will be fetched in the same "breath" as the rest of data used to render the UI. We should add the "get this image and stuff it in the database record for the current sample" as the tahoe admin feature.

I've only now noticed that editing a tag is not really the same like removing and adding a new tag since it changes the tags of other samples (tags are references).

This confuses me as until this very second, I thought tags as strings associated with each component and each sample, allowing the catalog users to ask: "what all samples use remote data". To answer this question, carmel will look through all sample tags and fetch those that have "remote data" tag.

[Thanood]

Regarding 6: My point is that the gist ID is available in the current version (from a json file) and also in carmel-api.. And so would be the image file name.

I thought tags as strings associated with each component and each sample

My bad, I guess I still had the "old" data structure in mind.

[adriatic]

Let me ensure that we are indeed describing the implementation of the "each sample's screenshot appears as a part of the carmel UI" the same way:

I am proposing to extend the set of sample's attributes with Image and use the approach similar to Storing and Retrieving Images from SQL Server using Microsoft .NET to store and fetch them.

Important I would prefer to have you decide the actual implementation of this as I have a lot more respect for your db skills than mine 😄 .

[Thanood]

Since the screenshots are a temporary fix...

... why would you implement something that sophisticated and store the images in a database? 😃 Sure, it might be interesting but, as you said, it's temporary.

Let me explain my idea: The sample's attributes don't need to be changed (and changed back again after the temporary solution is irrelevant). Every sample (already) has a gist id. This id is unique.

So a simple solution would be to store the images in images/samples/${sample.gist}.png - we have unique filenames and an easy storage which can easily be removed after we don't need screenshots anymore.

[adriatic]

So a simple solution would be to store the images in images/samples/${sample.gist}.png - we have unique filenames and an easy storage which can easily be removed after we don't need screenshots anymore.

I agree completely - as it gets us faster to the alpha version. I dreamed up the picture in the database idea as I believe that this will come handy later, in a different context.

[adriatic]

As there were no comments to my comments, we can either agree that we are in the complete agreement - or that you did not get the chance to visit this thread. I am rather erring on the safe side, so I will wait for your confirmation that we can move ahead with final details of the implementation as stated above.

[Thanood]

Yes, we are in complete agreement. Shall we look for a tag-editor replacement (with auto-complete) or do we do that later?

[Thanood]

Live sample:

[adriatic]

I prefer the tag editors you discovered yesterday - and I like the autocomplete feature with the caveat that I do not have a good idea on what to be in the autocomplete list. All existing tags? List of items explained in Wikipedia?

I have the feeling that this might be the key tag editor feature and would like not to start it silly 😄

[Thanood]

I'd say all existing tags or all existing tags used in that component (not sample). It should be easy getting that information by some database joins.

[adriatic]

This could be a good start - I would expect that carmel users will help in this selection

[Thanood]

I've exchanged the jQuery tag editor with taggy. I've kept it very simple currently, no custom styles, no delete button but autocomplete.