Events metadata, pages, and directory

[tnabtaf]

Track progress on updating hub to automatically generate the Events directory, and how to structure Events pages.

[tnabtaf]

Goals:

• Automatically update the events page (/src/events/index.md) based on metadata in individual event pages.

  • Events will be automatically added to the events list as their page is created. That is, new events will not be added by directly editing the events page as is done now.
  • Events will be automatically moved from the upcoming events list to the past events list as they pass
  • After a period of time, or a certain number of past events, or at the start of a new year, past events will be moved to an archive events page.
  • At the top of the upcoming list, images for the next n upcoming events with a featured image will be shown.
  • At the top of the past event list, images for all past events with a featured image will be shown.

• Individual event pages will contain

  • metadata about the event that is used to generate events lists (required)
  • additional text about the event (optional)

[tnabtaf]

Initial Event Metadata

@nekrut's initial update contains these metadata tags in the event page YAML front matter:

• title: PAG 2017
• date: '2017-04-01'
• tease: Galaxy is for Plants and Animals too...
• continent: NA
• location: San Diego, CA
• image: PAG2017.png
• host: PAG
• event_url: http://www.intlpag.org/

For this event the page also contains a fair amount of information about the event.

[tnabtaf]

Suggested revised event metadata and explanation of existing metadata

I have a couple of suggestions for how to use these tags and what further tags may be needed.

title

• Required
• Meaning
  • Name of the event or presentation
• Use
  • Becomes the event page title
  • Shown in the event list as the name of the event.
• Format:
  • free text all on one line.

url (changed name)

• Optional
• Meaning
  • Where the title text should link to when it is displayed.
• Use
  • If present then title links to this location.
• Format:
  • URL
  • Can be an internal or external URL.
  • If it's an internal URL the page should have some text in it, in addition to the metadata.

tease

• Optional
• Meaning
  • Short bit of additional text about the event.
  • Meant to complement, rather than replace title (?)
• Use
  • display with the event title, when space allows.
• Format:
  • free text all on one line.

Dates

Dates are hard. I think there may be three types of dates we care about.

Let's start with the two I think we definitely want

start_date (new)

• Required
• Meaning
  • Date the event starts
• Use
  • Determines where in the upcoming events list the item shows up.
  • Displayed as start date for the event.
• Format:
  • 'YYYY-MM-DD' (including single quotes)

end_date (new)

• Optional
  • If not provided then start_date is also the end date.
• Meaning
  • Date the event ends
• Use
  • Determines where in the past events list the item shows up.
  • Displayed as end date for the event.
• Format:
  • 'YYYY-MM-DD' (including single quotes)

date or sort_date / post_date?

The Events page is not the only place we will want to list upcoming events. We may want to show a short list of upcoming events, or upcoming and particularly important events on the home page. We may want to aggregate news items and events into a single RSS feed.

The order we display items in these places could be based on start_date for events, but that may not be what we want. We might want to highlight recently added events, or just the significant upcoming events.

I'm propose that the date tag on event pages mean the date this event was added, or the date of the most recent significant change to the event page. I also argue that we should use the same tag on all pages like this, including news items, blog entries, deployment log entries (which may just become blog entries) and so on.

Finally, I argue that we should change the name of this tag to sort_date or post_date to accurately reflect what it is used for. Using date on events pages is downright confusing, but it would also be confusing on blog pages that themselves link to external resources that may have been created months before.

• Optional (maybe)
  • If not provided then this event won't get included in places that use this tag.
• Meaning
  • Date this event page was created, or date of the last significant update.
• Use
  • Determines where in recent activity type lists this event shows up.
• Format:
  • 'YYYY-MM-DD' (including single quotes)

Where is it?

Part of a larger event?

A frequent situation is there is a workshop in a larger event. In these cases I have been (effectively) using title as the event name, and then including the name of the larger event in the location, along with the location. I argue that we should keep doing this. Here's a way to make it happen.

part_of_event

• Optional
• Meaning
  • This is the name of the larger event that this event is a part of.
• Use
  • If provided then this text will be included in the location (or somewhere).
• Format:
  • Free text, all on one line

part_of_event_url

• Optional
• Meaning
  • URL of the larger event that this event is a part of.
• Use
  • If provided then the name of the larger event will be a link to this URL
• Format:
  • A URL

host (changed meaning)

• Optional
  • but can be "online" or "to be determined" or ...
• Meaning
  • Host institution, organization or convention center.
• Use
  • Displayed first wherever location is displayed
• Format
  • Free text, all on one line
• Examples
  • Cleveland Clinic
  • University of Iowa

host_url (new)

• Optional
• Meaning
  • URL of host
• Use
  • If provided then the host text will link to this URL
• Format:
  • A URL

location

• Required
  • but can be "online" or "to be determined" or ...
• Meaning
  • Where in the world is this event being held.
• Use
  • Displayed wherever location is displayed
• Format
  • A location in however much detail you want to provide.
  • There should be enough information that someday we could feed the location (and the host) to a mapping service and have a reasonable expectation of it guessing at least the right city.
  • I prefer longer region and national names to shorter ones. For example, California over CA, and United States over USA.
  • It's easier for people not from that country to read.
• Examples
  • Cleveland, Ohio, United States
  • Iowa City, Iowa, United States

location_url (new)

• Optional
• Meaning
  • URL to link location to
• Use
  • If provided then the text in the location, before the first comma, will link to this URL
• Format:
  • A URL

continent

• Required
• Meaning
  • What continent is this event happening on
• Use
  • Display a continent icon for the correct continent.
  • Makes it easy to quickly tell what's in your part of the world.
• Format:
  • A two letter code. One of the following
  • AF: Africa
  • AS: Asia
  • AU: Australia
  • EU: Europe
  • NA: North America
  • SA: South America
  • GL: Global (not sure on this one, could also be ON for Online, or WO for world)

image_url (changed name)

• Optional
• Meaning
  • image / logo for this event
• Use
  • Display this image anywhere that events are summarized and images are included.
  • This will include at least the upcoming and past events lists on the Events page.
• Format:
  • A URL
  • Prefer that these be internal URLs, as external URLs often eventually stop working.

How to handle image sizes?

We have a couple of options here:

1. Require that the images be prescaled to display size before uploaded.
2. Provide a hint to the renderer on how high and/or wide to display this image. (That would require at least one extra tag.)
3. Have the rendering code figure out what size the image should be rendered at.

I like option 3 myself.

gtn (new)

If the event is a training event, and it's presented by a Galaxy Training Network Member, then I would like to display a GTN icon somewhere in the listing.

• Optional
  • If not present then defaults to f
• Meaning
  • Is this a training event presented by a GTN member?
• Use
  • Display a GTN icon (that links to the GTN trainer directory page) somewhere in the entry
• Format:
  • y|n

What about contacts?

The current events list includes a column for contact information. @nekrut left this off in his initial implementation, which made me wonder about dropping it. If people are interested in an event, they can follow the link and find out who to contact.

This saves space, at the expense of highlighting community and team members.

If we did add contacts, we would need some way to add both text and URLs.

What about links?

Until last year I really aggressively tried to track down presentations and training materials once an event was over, then upload them to the wiki, and then link to them from the past events archive. My thought was that this is great stuff to have, and uploading it to the wiki means it will be included in the custom Google search of all Galaxy web sites.

However, this was a lot of work and took a lot of disk space, and so for the last year I've only added links when I happen to come across the material.

Not sure what to do here.

[dannon]

@tnabtaf This is a lot to take in, whew. First off, you're the one entering most of this stuff, so I'll definitely defer to your choices, but this seems like quite a lot of metadata to have to manage. The 'part of' fields in particular, I'd think you'd just roll into the narrative description, but maybe I'm not seeing how this would be used in feed rendering.

Regarding url vs external_url -- the reason it is explicitly 'external_url' right now is that 'internal' urls would be redundant. Each one of these event content items generates an individual event page on the hub automatically. The only reason for external_url to exist is for when you do not want links within the wiki in aggregate feeds to link to that internal page. I'm not sure we really ever want that, though, it seems like it'd feel inconsistent to have some events perform one way, some another. It seems reasonable to me that for every event in a feed, you'd click it, go to our little landing page (also autogenerated, this is the actual content item) for the event, and then you'd see the full details, including links to host, external website, etc., etc.

For dates, I'd really prefer a situation with just two dates, or a single date + duration in days. An additional 'post_date' seems like it adds complexity. How about highlighting particular events using the flexible content blocks on the events, etc., pages. Would that work for you?

I didn't want to call 'image' 'image_url', because I don't think we want people using URLs here. This should be a path to an image in the repository. Regarding formatting, I swapped to wrapping images in .img-fluid and the autosizing seems to work pretty well for the most part, so I like that idea.

Regarding links, I'd imagine this is all stuff you'd curate on the event page itself. So, /src/events/my-fancy-events/index.md. You can put anything you want on that page, it'll get indexed, etc.

I'm sure I missed stuff I meant to reply to. Did you check out the branch where I'd implemented the start of this?

[tnabtaf]

@dannon.

@tnabtaf This is a lot to take in

I became vaguely aware of that while typing. With that in mind, and to incorporate your feedback, here's a more compact, revised set.

title

• Same as above

external_url

• Optional
• Meaning
  • The page describing this event is outside the hub.
• Use
  • If present then title links to this location.
  • If not present, then title links to the hub event page.
• Format:
  • URL

tease

• Same as above

Dates

date (changed meaning)

• Required
• Meaning
  • Date the event starts
• Use
  • Determines where in the upcoming events list the item shows up.
  • Displayed as start date for the event.
• Format:
  • 'YYYY-MM-DD' (including single quotes, I don't know why)

days (new)

• Optional
  • If not provided then event is assumed to be one day long.
• Meaning
  • How many days does this event last?
• Use
  • Determines where in the past events list the item shows up.
  • Displayed end date for the event.
• Format:
  • an integer

Um, what?

How about highlighting particular events using the flexible content blocks on the events, etc., pages. Would that work for you?

I don't know what that means. :-/

Where is it?

host (drop this)

location

• Required
  • but can be "online" or "to be determined" or ...
• Meaning
  • Where in the world is this event being held.
• Use
  • Displayed wherever location is displayed
• Format
  • A location in however much detail you want to provide.
  • There should be enough information that someday we could feed the location (and the host) to a mapping service and have a reasonable expectation of it guessing at least the right city.
  • I prefer longer region and national names to shorter ones. For example, California over CA, and United States over USA.
  • It's easier for people not from that country to read.
• Examples
  • Iowa City, Iowa, United States
  • University of Iowa, Iowa City, Iowa, United States
  • Plant and Animal Genome XXV, San Diego, California, United States

location_url (new)

• Optional
• Meaning
  • URL to link location to.
  • This can be a conference URL, or a host UR, or a facility URL, or ...
• Use
  • If provided then the location text (all of it) will link to this URL.
• Format:
  • A URL

continent

Same as above.

image

• Optional
• Meaning
  • image / logo for this event
• Use
  • Display this image anywhere that events are summarized and images are included.
  • This will include at least the upcoming and past events lists on the Events page.
• Format:
  • an internal hub path.

gtn (new)

Same as above

What about contacts?

Drop them.

What about links?

Regarding links, I'd imagine this is all stuff you'd curate on the event page itself. So, /src/events/my-fancy-events/index.md. You can put anything you want on that page, it'll get indexed, etc.

+1

So, that's going from 15 tags to 10.

Whaddya think?

[tnabtaf]

@dannon /i'm going to start moving forward with these tags. I'll use the branch.

[dannon]

@tnabtaf Sorry, meant to reply, this smaller set looks good to me. What I meant by 'flexible content blocks' was that, on the branch, you'll see that the events/index.md does have regular 'content' space, which will (currently) show up above the autogenerated lists of events. You could use this space on the events landing page to highlight particular events with hand-crafted text.

[tnabtaf]

@dannon. Thanks for the merge. All the events for 2017 include at least the required tags as described above. I also renamed paths to have event directories start with 2017 and sometimes 2017-mm, and sometimes 2017-mm-dd. Not sure if it would be worthwhile always specifying the month.

Moving on to News items next.

[bebatut]

Hi,

I have a question. Would be possible to add a metadata to clearly identify the training events from the talks to conference (for example)? I was thinking to write a small script to extract the training events with the location and date, and then be able to obtain some statistics and maps automatically. What do you think about that?

Bérénice

[tnabtaf]

Hi @bebatut!

Hmm. I can imagine adding an ilk tag to indicate if it's training, hack, talk. and so on. I'd want to somehow incorporate the current gtn functionality into that tag. I don't know enough about JSON to suggest how to do that. If possible, I rather not have two tags that can contradict each other.

I'd also want to support events that have both training and presentations (for example).

And I really like the idea of a map. The `location' field spec (can I call it that?) says

There should be enough information that someday we could feed the location to a mapping service and have a reasonable expectation of it guessing at least the right city.

@dannon: Any thoughts on this?

[tnabtaf]

I'd like to revive an early discussion

What about links?

Until last year I really aggressively tried to track down presentations and training materials once an event was over, then upload them to the wiki, and then link to them from the past events archive. My thought was that this is great stuff to have, and uploading it to the wiki means it will be included in the custom Google search of all Galaxy web sites.

However, this was a lot of work and took a lot of disk space, and so for the last year I've only added links when I happen to come across the material.

Well, I just came across slides for a talk from this year, and I don't really want to ignore that information. So, here's a proposal

links

Want the ability to support multiple links. This proposal doesn't include a description of what each link is. I'm open to adding that.

• Optional
• Meaning
  • List of links to related information. Could be slides, video, poster, etc.
• Use
  • If present then rendered as [Link1](url1), Link2](url2)
• Format:
  • A JSON array of URLs
• Examples:
  • links: ['https://speakerdeck.com/jxtx/bio-genomics-2017']
  • links: ['https://www.xsede.org/documents/10157/1125659/Genomics_SymposiumTalk_2016.pdf/0da778e0-d60a-412c-b739-a3182020d4fa', 'https://www.youtube.com/watch?v=m1GXj7z3JYM']

[dannon]

I definitely don't think we should ignore links to slides, etc., but I think these sorts of things should be included in the content area. It still gets indexed, is easy to format, display, etc., and it'll be much easier to handle both large lists of links and the occasional single set of slides, since it'll all be up to the event author's discretion.

[tnabtaf]

The page that got me thinking about this again is this:

https://github.com/galaxyproject/galaxy-hub/blob/master/src/events/2017-02-biogenomics-talk/index.md

Except for the link to the slides, there would be nothing else on that page. Or, I'd need to create some text that basically reiterates the front matter. Which I can do...

[dannon]

Right. I think we want things on those pages, if only a short blurb. (edit: But maybe we don't? I may have been seeing those pages differently, we should talk!)

[dannon]

(and it wouldn't necessarily be a reiteration of the frontmatter -- that's all going to be formatted nicely and included on the event page already)

[dannon]

Done in #161.