Expanding the concept of the "aurelia plugins catalog" application

[adriatic]

Introduction

This is a long standing issue, which got a significant boost today, by an almost casual remark by Rob:

At some point in the future, I would like to explore how we can potentially integrate the catalog you built into our official docs.

Several months ago (before Monterey's time) this would be less inspiring to me at least, as in all previous discussions we had, the subject was the use of aurelia docs api so far used in aurelia HUB as the building block of Aurelia-UI-Toolkits bridge catalog applications (kendoUI, materialize and Syncfusion).

It is the planned support for the package importer module for aurelia-cli tool that allows us to create a more ambitious plan: a catalog of all aurelia plugins which will allow the aurelia community a uniform, guided access to all existing plugins.

---

Properties of Aurelia-UI-Toolkits bridge catalog applications

This is a brief summary of the catalog application architecture, needed to initiate the discussion and the design if the next generation of the catalog app mentioned in the Introduction section above

The catalog is a very lightweight container, hosting just the basic application's skeleton, where all of the frequently changing components are external. This allows catalog maintenance without the rebuilding the app in most of the cases. The screen shot below indicates the catalog sections that reside outside the catalog app.

Equally important, all of the catalog's main content (list of all Aurelia components, with examples how to use them) is also not a part of the application itself. All this information is organized in the form of GitHub Gists - click here to run see the gist that renders the catalogs basic listview component:

[adriatic]

Tasks for the team

• [ ] Enumerate other catalog properties (if any) that are relevant to get everyone excited about the creation of the Aurelia super catalog application.

• [x] Question for @Thanood: is materialize catalog at the same level of not being an monolithic app as kendoui catalog?

• [ ] create the sketch of the super catalog design here, making sure that the amount of effort to do that is important than the usefulness of this new app.

[Thanood]

is materialize catalog at the same level of not being an monolithic app as kendoui catalog?

If by monolithic you mean the samples are still in the app itself as opposed to gists, then Materialize catalog is still monolithic, unfortunately. I will have to read about how to do it again. I've not taken a look yet but that should be in one of our books.

The reason is: at the time of the first concept of sample externalization, it didn't seem possible to change the theme of the gist samples. That appears to have changed as I could easily see in the KendoUI catalog. 😃

Being able to change colors is a major feature in Materialize catalog for two reasons:

1. users can immediately see that colors change for all components when they select a color theme
2. bridge developers can easily see when it does not work 😃

I'm going to read about the gist samples again and I'm going to explore if/how colors can be applied to the samples.

At some point in the future, I would like to explore how we can potentially integrate the catalog you built into our official docs.

Is there any specific information yet on how this integration would be done? Will the super catalog be a part of the hub? (just noticed this is basically the same question @JeroenVinke had in Gitter)

[JeroenVinke]

One thing that is not immediately visible when using the kendo catalog, but is a critical part, is that it uses a kind of proxy service that I am running on a server. This service allows us to fetch gists without being subjected to the lower github api limit for unauthenticated requests, as the service proxies the request with Github authentication enabled.

We fetch all files of a gist from the proxy server, and then the files are used to run the example in the top part, and show the files in the bottom part

[adriatic]

Good point (I am aware of it) - it belongs to the same category as the (future) service for feeding the autocomplete control used searching for plugins; see red marker 4 on the image below

This service is being discussed here

[adriatic]

Comments to @Thanood's section above

If by monolithic you mean the samples are still in the app itself as opposed to gists, then Materialize catalog is still monolithic, unfortunately. I will have to read about how to do it again. I've not taken a look yet but that should be in one of our books.

Yes, by "not-monolithic" I referred to the catalog's distributed character where most of often changing parts (samples and documentation) live outside the catalog. It is one of the most appealing properties of the catalog with the respect to maintainability. Check Creating gists for the catalog app for details of this "trick".

The reason is: at the time of the first concept of sample externalization, it didn't seem possible to change the theme of the gist samples. That appears to have changed as I could easily see in the KendoUI catalog.

I am not aware of any additional work being done to support the theme changes after the samples were externalized - my understanding is that the theme is dynamically set for the the whole catalog app and all parts of the UI (including the samples loaded from gists) are automatically using the current theme. @JeroenVinke will correct me here if necessary.

Is there any specific information yet on how this integration would be done? Will the super catalog be a part of the hub?

The answer to the second question is YES, as the super catalog has narrower context than the HUB. The details of the integrations are ours to provide (see the third "check-box" in this section), because were are in a better position to do that than the core team would be

[JeroenVinke]

We use <compose view-model="jeroenvinke.nl/gist/<gist id>/app"> to run gists in the catalog. So the app.html, app.js (and any resources in app.html etc) but not index.html of the gist, are pulled in just like "normal" files. Since the css of gists are loaded in index.html, and we do not load this index.html in the catalog, the compose tag renders without any style. Because of the compose tag, they also run in the context of the app (it is not an iframe or anything), so the css of the catalog is applied to the gists. And this css is switched via the theme switcher

[Thanood]

Thank you for clarifying this, @JeroenVinke. I've had a look at the samples code and will try to follow this implementation. Looks like a lot of work, though. :smiley:

[Thanood]

@adriatic @JeroenVinke Gist.run doesn't work in IE (I don't know Edge). Does the catalog work in IE and Edge?

I tried IE but I've got this error (unrelated to gist.run):

The upper part translates to something like "object doesn't support the property or method 'include'". Maybe a missing polyfill?

[JeroenVinke]

I don't think our catalog has ever worked in IE 😄

Since we are not using gist.run (we use <compose> but instead of referencing a local view/view-model pair, we are referecing a URL) I don't think that is the problem.

[Thanood]

Status update:

• first sample (button) is converted
• code preview tabs are still missing
• old routes are preserved for now
• warnings all over the place in case I forgot a sample
• side nav menu is broken - doesn't highlight the current sample (route)
• Jeroen's server received some more load today. 😉

I thought of converting the catalog to CLI or webpack. Loading times on browser refresh are starting to hurt.

Tracking progress here: https://github.com/aurelia-ui-toolkits/aurelia-materialize-bridge/issues/324

[adriatic]

@Thanood - let me add a few comments explaining my insistence on having all catalog apps built like KendoUI bridge catalog:

• it is a good innovation that we should be proudly showing off.
• two out of our three bridge catalogs are already architected that way.
• it is a ton easier to maintain - although a bit slower (probably Jeroen's server contributes to that, so we might consider finding a server hosted at some US site that will get us free hosting, or even better, get some server resources from bluespire (Rob;s company).

[Thanood]

Agreed but I didn't mean to blame the gist samples for browser refresh time. Actually they're pretty fast (faster than the 1.5s timeout used to display the spinner). Unbundled SystemJS is slowing down page load times significantly. Fetching the samples from an external source has the additional benefit that the catalog doesn't rely on in-browser transpilation.

I did a catalog app with the CLI just to test for my tree-view. It was pretty easy to do and it is really fast. See here if you want - of course you don't have the comparison to unbundled SystemJS load time. That catalog is pretty small in comparison to Materialize. And of course the code previews show the app-bundle.

So I thought why not do that for Materialize bridge or even try webpack? 😃 There's an additional "sanity check" coming for free with webpack as it's the most problematic bundler to use atm with Materialize bridge.

[Thanood]

So I thought why not do that for Materialize bridge or even try webpack?

I was not aware of the fact that the <compose> approach needs in-browser transpilation. But it makes sense. :smiley: So no cli/webpack for the catalog. At least until we find a way to include babel-runtime which should be possible but IMO not worth the effort atm.

Btw.: requirejs loads this: http://jeroens-server.nl/gist-id/app when using that: <compose view-model="http://jeroens-server.nl/gist-id/app">

So the exact URL is fetched not the JS file and the html file as a result of being a component.

[Thanood]

Status update: done 😏

Well, apart from breadcrumbs, that is. You cannot have a child-router in a <compose>, so there's nothing to see.

Also, not released yet. I need to clean up a bit. It's alive! http://aurelia-ui-toolkits.github.io/demo-materialize/#/samples/color-basic-use 😃