EJS templates working with things other than an items array

[andrewpbray]

Description

The documentation on listing templates is clear that it can ingest a contents.yml file that consists of an array of items. That array is then accessible in the EJS template as items.

If contents.yml is not a flat array but has an array nested under a top-level key, is there any way to include that in the EJS template? In my reading of the docs, EJS itself has that capability, but it seems Quarto only makes an items object accessible and it must be an array.

An example of what I'd like to do for a contents.yml file:

days:
  - gift: partridge in a pear tree
  - gift: turtle dove

With an ejs that would allow access to "partridge in a pear tree" via something like days[0].gift

Thanks!

[cderv]

Are you looking for what we call template-params (https://quarto.org/docs/websites/website-listings-custom.html#template-parameters) ?

This would be

template-params:
  days:
    - gift: partridge in a pear tree
    - gift: turtle dove

That we pass to custom listings as templateParams

it should allow you to do whatever you need with ejs.

[cderv]

I think this is more complex because anything under contents will be processed by Quarto in some ways before being passed as items data to the template. Like for creating correct value for all listing fields (https://quarto.org/docs/websites/website-listings.html#listing-fields), for example we process the date, or making sure the author will be an (author: John => author: [John]) , or specific usage like path for inline listing information https://quarto.org/docs/websites/website-listings.html#yaml-listing-content). It happens in listingFromMeta at least and maybe other place

Whereas anything on template-params is just passed as is to the template.

quarto-cli/src/project/types/website/listing/website-listing-template.ts

Lines 159 to 162 in 50b4cf1

	} else {
	ejsParams["metadataAttrs"] = reshapedListing.utilities.metadataAttrs;
	ejsParams["templateParams"] = reshapedListing["template-params"];
	}

And we do reshape the items to be passed to the template

quarto-cli/src/project/types/website/listing/website-listing-template.ts

Lines 65 to 142 in 50b4cf1

	// Process the items into simple key value pairs, applying
	// any formatting
	const reshapedItems: Record<string, unknown | undefined>[] = items.map(
	(item) => {
	resolveItemForTemplate(item, listing);
	const record: Record<string, unknown | undefined> = { ...item };
	if (item.author) {
	if (Array.isArray(item.author)) {
	record.author = item.author.join(", ");
	} else {
	record.author = item.author;
	}
	}
	// Format date values
	// Read date formatting from an option, if present
	const dateFormat = listing[kDateFormat] as string ||
	format.metadata[kDateFormat] as string;
	const fieldLabelLangKeys: Record<string, string> = {
	"word-count": kListingPageWords,
	};
	const fieldTypes = listing[kFieldTypes];
	for (const field of Object.keys(fieldTypes)) {
	if (fieldTypes[field] === kFieldDate) {
	const dateRaw = item[field];
	if (dateRaw) {
	// For file modified specifically, include the time portion
	const includeTime = field === kFieldFileModified;
	const date = typeof dateRaw === "string"
	? parsePandocDate(dateRaw as string)
	: dateRaw as Date;
	if (date) {
	record[field] = dateFormat
	? formatDate(date, dateFormat)
	: includeTime
	? formatDate(
	date,
	"short",
	"medium",
	)
	: formatDate(date, "medium");
	}
	}
	} else if (fieldTypes[field] === "minutes" && item[field]) {
	const val = item[field] as number;
	record[field] = localizedString(format, kListingPageMinutesCompact, [
	Math.floor(val).toString(),
	]);
	} else if (
	fieldTypes[field] === "number" && item[field] !== undefined &&
	fieldLabelLangKeys[field] !== undefined
	) {
	const val = item[field] as number;
	record[field] = localizedString(format, fieldLabelLangKeys[field], [
	Math.floor(val).toLocaleString(),
	]);
	}
	}
	if (item.description !== undefined && !isPlaceHolder(item.description)) {
	const maxDescLength = listing[kMaxDescLength] as number ||
	-1;
	if (maxDescLength > 0) {
	record.description = truncateText(
	item.description,
	maxDescLength,
	"space",
	);
	}
	}
	return record;
	},
	);

Not also the metadataAttrs utility function that will be passed to custom EJS so that item can be process easily the same way as we do for internal templates. Using metadatAttrs is explained in https://quarto.org/docs/websites/website-listings-custom.html#sorting-filtering-and-pagination and apply on an item element, that need to have been processed by Quarto

So using contents items for Listing as described in our references and docs to be used in EJS template is way easier and correctly done by passing to contents.
template-params is really for custom key-values to be used in the custom template, and not known or process by Quarto.

Hope it helps clarify

[andrewpbray]

Gotcha; that makes sense. That's a lot of extra functionality that comes on line by using contents.

[cderv]

Oh I see. Probably _metadata.yml could work, but I believe we could also support a file for template-params, same way we support for contents. something like

  contents:
    - items.yml
  template-params:
    - listing-meta.yml

would that be what you want ?

Should we log this idea in its own issue ? Or do you think it is not that useful after all if you need to provide contents anyway ?

[andrewpbray]

I think probably sit on this for now / doesn't need it's own issue. That extra processing in contents is very useful, so I'll restructure things to format the external file as a flat array. That should solve the immediate issue. If I come across a strong use-case for the template-params from an external file, I'll open a separate issue.

Thanks for your help brainstorming!

[cderv]

Thanks for your help brainstorming!

My pleasure ! You always have interesting usecase !