How does `VersionSpecificPackageIds` work?

[abjerner]

The Listing page doesn't provide a lot of detail for what this options does, and how it affects the package page in the Marketplace.

At Limbo we have the Structured Data package, which targets Umbraco 9. The name was based on what we we have called in for years before releasing at as a package, but to outsiders the name may not make that much sense - so we released it as Limbo Tables for Umbraco 10+.

For Limbo Tables the VersionSpecificPackageIds option looks as below (see umbraco-marketplace-limbo.umbraco.tables.json):

{
  "VersionSpecificPackageIds": [
    {
      "UmbracoMajorVersion": 9,
      "PackageId": "Limbo.Umbraco.StructuredData"
    },
    {
      "UmbracoMajorVersion": 10,
      "PackageId": "Limbo.Umbraco.Tables"
    },
    {
      "UmbracoMajorVersion": 11,
      "PackageId": "Limbo.Umbraco.Tables"
    }
  ]
}

The only difference I have found from adding this is that the package package now also shows v9 - which I think is a bit misleading, because Limbo Tables doesn't - but Limbo Structured Data does.

Since it's technically two different packages that has to be installed with two different package IDs, I would assume the Marketplace would add links between the two packages instead of claiming that one package also supports the versions of the other package.

[AndyButland]

The idea here was to support cases where essentially the same package has been released on two different NuGet package Ids. Umbraco Forms was the close to home example - it was UmbracoForms up to Umbraco 8, then Umbraco.Forms after that.

Using VersionSpecificPackageIds we provide just the details for the Umbraco 8 package (the JSON file is here):

{
   ...
   "VersionSpecificPackageIds":[
      {
         "UmbracoMajorVersion":8,
         "PackageId":"UmbracoForms"
      }
   ]
}

This does two things:

1. As you have seen, extends the visible range of Umbraco versions the package supports.
2. If you also select what Umbraco version you are running - either via the "Filter" panel, or via the querystring passed when the marketplace is IFRAMed into the back-office, the install details will also show what package ID and version you should install.

This seems a better experience for us as the package developer and for people searching for the package. There's only one listing to maintain and and it doesn't appear there's a duplicate in the marketplace.

For your case, it's up to you whether to follow this too and list the one package. Or if you prefer, you can list both and use the related packages to link between them.

[abjerner]

@AndyButland this then works a bit different from what I thought, but I can work with that.

Anyways - if I add another package as a related package, it looks like this. The title might be a bit misleading.

https://marketplace.umbraco.com/package/limbo.umbraco.structureddata

Depending on whether you go small or big, could the title be updated to have a more general purpose? Or be controlled via the JSON file?

Or possibly even something like this in the JSON file:

{
  "Related": [
    {
      "Title": "Add-ons for this package",
      "Items": [
        {
          "PackageId": "Limbo.Umbraco.Tables",
          "Description": "Table editor for Umbraco 10+."
        }
      ]
    },
    {
      "Title": "Other versions of this package",
      "Items": [
        {
          "PackageId": "Limbo.Umbraco.Tables",
          "Description": "Table editor for Umbraco 10+."
        }
      ]
    }
  ]
}

For some packages, I'd like a better way to show other versions (eg. as Limbo Tables supports U10+, but Limbo Structured Data supports U9) and for other packages I'd like to show add-ons for the package (eg. Skybrud Redirects has a Skybrud Redirects Import add-on). The above snippet allows for adding multiple groups of related packages, each with their own group title.

I don't necessarily need multiple groups for the same package, so being able to control the title of the related section might be sufficient. But multiple groups might be a good idea going forward depending on how much customization of the package page that HQ would like.

[AndyButland]

That's a pretty good suggestion for a structure, but I think for now at least we'll need to take the slightly simpler approach. There would be some effort to introduce a custom number of groups, but also we need to consider that the existing structure is used by quite a few packages now, so we'd need to keep supporting that.

There's a few improvements we can fairly make here though without impacting that.

• Change the existing heading to something more generic. I've done that such that now is just says "Related packages". That way we don't pre-judge why a package might be related in the wording we use for the heading.
• There's a front-end UI piece missing in the current implementation of related packages, which you can see in the screenshot above. We should be displaying here both the usual package description and the custom package description provided in the JSON file. In other words there should be two descriptions:
  • The usual package description should display where the custom one does now, so this part of the package card looks the same wherever it is displayed.
  • The custom "why this package is related" description provided in the JSON file for related packages should appear as well, probably below the image and perhaps in an italic font to separate it.
  • I'll ask @nathanwoulfe if he can look at this please when he's back in the new year.
  • With that rendering you have somewhere to explain why a particular package is related.

I think for the "add-ons for the package" you could look at the feature for "sub-packages" that we've implemented. See details of the IsSubPackageOf flag documented on this page.

[nathanwoulfe]

Sorted - previously had a conditional display for the related description, to the related or default description. Updated to show both.

[AndyButland]

Excellent, thanks. I'll close this then, but we'll likely deploy the latest that contains this fix next week.

[abjerner]

Awesome. I can see the title already has been changed 👍