Additional UI elements in home area

[jmcc0nn3ll]

There are two UI elements I would like to prepare, and I would like you to point me in the right direction on how to get them dropped into place appropriately.

First, I would like to pull in a list of blog articles from Webtide and render that on a page, perhaps even the home page of jetty.org, in the center.

Looking at the source, I think it would just be another <article class="doc"> entry.

I assume I can load up JavaScript and do it, but is there a way to tie it into asciidoctor/antora? Ultimately, I know how to make it happen, but I would like to do it the 'right' way to integrate into the site properly. If it is just a matter of loading JavaScript on a given page, what is the recommended way to get that loaded appropriately, etc? I used slim in the past for something like this.

Same sort of deal as the first one; years ago, we had a 'Used By' type page that cycled through project names, images, and links. I want to resurrect that idea, likely as a separate page.

[mojavelinux]

I would like to pull in a list of blog articles from Webtide and render that on a page... I assume I can load up JavaScript and do it, but is there a way to tie it into asciidoctor/antora

If you want the list to be real time, then you definitely want to do it using JavaScript (fetched by the browser). If you tie the compilation into the Antora build, then the list will only be updated anytime Antora builds the site.

With that said, you can use an Antora and/or Asciidoctor extension to run arbitrary code and insert the result into a page or even create a new page dynamically. But again, that will only happen when Antora builds the site. So client-side JavaScript may be preferable.

what is the recommended way to get that loaded appropriately, etc? I used slim in the past for something like this.

Antora uses Handlebars as its HTML templating language. You can see where scripts get added to the page in the following partial template: https://github.com/webtide/jetty.website/blob/main/ui/src/partials/footer-scripts.hbs The template can check that it's processing a specific page and only load the script on that page.

What I've always found useful is to create a hard-coded result list, style it, and figure out where you want it to be displayed. Then, hook it up to live data. I tend to avoid libraries, a policy which affords me maximum control over the HTML that's produced. For example, https://css-tricks.com/how-to-fetch-and-parse-rss-feeds-in-javascript/

we had a 'Used By' type page that cycled through project names, images, and links. I want to resurrect that idea, likely as a separate page.

In this case, I would probably recommend maintaining the list in an AsciiDoc file in the home (i.e., ROOT) component. On page load, JavaScript could decorate that list and display it in some sort of carousel with the help of some CSS. What would help is to:

a) Have some sample content to work with b) Have a picture of how you want it to look

[jmcc0nn3ll]

Ooops, I meant to push a PR but ended up pushing a merge with my changes.

How do I test this locally before I push?

[mojavelinux]

When making changes to the UI project (the ui folder), you will want to use the UI preview. You can find instructions for how to do so on the following two pages:

• https://docs.antora.org/antora-ui-default/set-up-project/
• https://docs.antora.org/antora-ui-default/build-preview-ui/

You should not have to build the whole site to test changes to the UI. That's why the UI preview exists.

[mojavelinux]

You have not put the UI assets (css, js, etc) in the correct folder. All UI-related things should be under the ui folder. UI assets do not belong in the ROOT component.

The CSS should be in ui/src/css and the JS should be in ui/src/js with a numeric prefix for ordering (e.g., 07-blog.js) or in ui/src/js/vendor in which case it will be loaded separately.

You only need a blog.adoc page in the ROOT component if these entries are going to be displayed on a dedicated page. If they are being added to an existing page, no additional page is needed.

[jmcc0nn3ll]

Reverted.

I put the javascript in the ROOT component because it was only intended for one page in that component, and it was client-side intended to run dynamically. Same with its associated css.

However....we blog infrequently enough we could always just regenerate when we get a new blog written, or they just get updated when we do a release.

The other one though would be a bit of client-side, which would still go in the component, no?

[mojavelinux]

I understand that you only want to apply CSS and JS for a single component, but putting those assets in the component content root is just not how Antora works. Rather, you put all UI assets in the UI project, then you can selectively add those to certain pages based on property values in the UI model (such as page.component.name).

The only files that go into the content root are the content files themselves (AsciiDoc files, images, examples, and attachments).

[jmcc0nn3ll]

Small question. I pushed up the wtblog branch, but I have an issue in the lint when running gulp. The issue concerns how to make the http GET call to the blog feed.

I have tried these several ways, but I am missing something obvious. My latest attempt:

07-add-wtblog.js

  var XMLHttpRequest = require('xhr2')
  const xhttp = new XMLHttpRequest()

This require allows me to pass lint when building the UI project however in the browser it doesn't know what require is.

What am I missing about this process? It feels like the lint process requires an environment that the browser is not providing.

[mojavelinux]

There's no need to be using external libraries. Just reference window.XMLHttpRequest and it should resolve and make the linter happy. (Since it's a global, it has to be prefixed with window.).

[mojavelinux]

I noticed that you added a bundle of entries to .gitignore. Generally, I dislike/discourage a laundry list in .gitignore, preferring very precise entries. Also, folders should never be unscoped. They should always start with / so that they match exactly what you want and not anywhere in the project. (See https://github.com/webtide/jetty.website/blob/main/ui/.gitignore).

At the root of the project, you should not have node_modules, package.json, and package-lock.json. You should be using npx to run antora. So there's no need to have those specific exclusions (and node_modules is already excluded in the ui folder).

If there is a need for more .gitignore entries, it should be a separate PR.

[jmcc0nn3ll]

I got it working, I'll clean it up and put in a PR tomorrow for it, and make a separate one for .gitignore which we are a bit more liberal with on jetty. the node_modules was likely my trying to get antora and npx running correctly. I'll make a fresh clone tomorrow.