Need ability to retrieve a list of subpages whose "leaf name" starts with a specific string

NEW
Unassigned

Status

enhancement
5 years ago
3 years ago

People

(Reporter: sheppy, Unassigned)

Tracking

Details

(Whiteboard: [specification][type:change][LOE:?])

Reporter

Description

5 years ago
What feature should be changed? Please provide the URL of the feature if possible.
==================================================================================
We need to be able to get a list of pages which are subpages of a specific page limited to those pages whose last path component starts with a specific string.

What problems would this solve?
===============================
For example, all API reference pages are immediate children of the page /<locale>/docs/Web/API.

That means that, you might have:

/en-US/docs/Web/API/Window
/en-US/docs/Web/API/Window.document
/en-US/docs/Web/API/Window.size
(etc)
/en-US/docs/Web/API/RTCPeerConnection
/en-US/docs/Web/API/RTCPeerConnection.methodName
(etc)

We need to be able to retrieve a list of all of the members of the Window interface, for example. That means we need to be able to get a list of all subpages of /en-US/docs/Web/API where the text after the final slash starts with "Window.", or:

\/en-US\/docs\/Web\/API\/Window\.(.+)

While a regexp search would work for this, it might be overkill given the specific use case we have in mind. Whatever's easier to implement.

Who would use this?
===================
This is pretty urgently needed in order to properly build flexible, automated landing pages, which is a priority project for Ali and I right now.

This is a search-related function we'd need to be able to access using KumaScript code as well.

What would users see?
=====================
Nothing; this is simply a KumaScript feature.

What would users do? What would happen as a result?
===================================================
The goal of this effort is to be able to use a single macro on the Window page that automatically grabs a list of all members of the Window object, sorts them by category (method, property, event, etc) and builds a beautiful list of properly annotated links.

We currently have to do this by hand, and things get missed -- plus this opens things up too easily to every page looking different.

Is there anything else we should know?
======================================
This is related to, but not the same as, bug 1014897.
Reporter

Comment 1

5 years ago
Note that "leaf name" ≠ "title". :)
Jannis, do you have an estimate on how long this would take?
Severity: normal → enhancement
Flags: needinfo?(jezdez)
Whiteboard: [specification][type:change] → [specification][type:change][LOE:?]
Reporter

Comment 3

5 years ago
Back at the MDN hack days in Paris, I had a long chat with Jannis about this, and I *think* what he proposed was adding support for letting macros send search queries to ElasticSearch, so they could do more advanced queries. That would be a wonderful solution, in my opinion, if it's doable, since it would let us build a lot of amazing stuff easily and in a performant manner.
I hesitate to add/alter our search index for such a specific use-case. :sheppy - can you provide an example of the KumaScript template you'd like to be able to write? We may be able to do this with existing metadata about pages that's already sent thru to KumaScript.
Flags: needinfo?(jezdez)
Reporter

Comment 5

5 years ago
(In reply to Luke Crouch [:groovecoder] from comment #4)
> I hesitate to add/alter our search index for such a specific use-case.
> :sheppy - can you provide an example of the KumaScript template you'd like
> to be able to write? We may be able to do this with existing metadata about
> pages that's already sent thru to KumaScript.

Yeah:
We want to be able to automatically build the landing page for an API interface, with the lists of properties, events, and methods automatically built and updated as new pages are added for new ones.

Most landing pages are built using subpage lists.

The problem here is that the API reference does not put members of an interface into subpages. Each interface is a child of docs/Web/API, and so is each member of that interface:

docs/Web/API/Window
docs/Web/API/Window.closed
docs/Web/API/Window.focus
(etc)

This means that in order to generate these lists automatically, we need to be able to find the pages whose slugs are docs/Web/API/Window.* -- which we can't currently do. There's no metadata that lets us find these among all the other stuff under docs/Web/API.

This also applies to the JavaScript reference and to parts of the CSS reference, among others.

There are other macros that would need this capability, such as ones to build quicklink lists and such.
Reporter

Comment 6

5 years ago
So basically, what I want is a macro like this:

{{APIInterfaceMenu("InterfaceName")}}

This would insert a properly-formatted set of links to the properties, methods, and events in the specified interface, with the appropriate headings and other text as needed based on our design (such as the summary of what each does, pulled from the SEO summary).
Reporter

Comment 7

5 years ago
An alternate solution would be to treat "." in slugs exactly the same way we treat "/" -- it establishes a child relationship between pages. That would let us use the existing subpage retrieval mechanism.
You need to log in before you can comment on or make changes to this bug.