Singleton list types (single item list)

[MadeByMike]

A number of people in the community have expressed a desire to be able to configure a global 'options' page. This would work like a Keystone list however there is only a single item.

Currently settings like this are achieved with custom pages. What is wanted is the ability to use the fields API to generate these pages, along with access control and GraphQL endpoints.

I'm suggesting the following API that closely matches the createList API:

Keystone.createSingle('Settings', {
 schemaDoc,
 hooks,
 access,
 adapterConfig,
 path,
 plugins,
 fields,
 itemQueryName
})

All of the above would work the same as for lists.

The following list config would not be required on options pages:

labelField, labelResolver, listQueryName, singular, plural

I thought potentially you might want a different itemQueryName than what appears on the settings page? However since you would not be required to change the value of a setttings page name due to an ambiguous plural, I don't think we need a 'singular` option? If we do it should just be label?

I only see the need for one query which would match the itemQueryName. i.e:

settings {
  fieldName
}

For mutations we should only need update. No id should be required. e.g:

updateSettings(data: { siteName: "My Site" }) {}

We keep the data key for consistency.

[timleslie]

I would prefer not to add to the keystone API for this unless we determine that it's not possible to do using pure config and the existing API. From the POV of setting up the list with graphQL, I think everything described here can be achieved with hooks and access control. The admin UI stuff might require some additional config, but we should probably build out the graphQL side of things first and make sure we understand the use case before building in highly specific UI.

[MadeByMike]

I get there is not much difference between options and lists in the back-end, however there are big differences between how they are represented in the AdminUI and the required graphQL API. I think I am still pro this being a 'special case'.

At the end of the day there are 2 goals for me here:

1. First is to make it easy to set-up options pages with the correct GraphQL end-points, hooks, access control etc... so that it effectively looks and smells like a single item. Currently a new user could sink more than a day on setting this up, as it touches multiple advanced concepts.
2. The other important thing is that the end result looks professional enough to hand over to non-technical users. I.e. Proper treatment of 'Settings' in the admin UI.

Even after our discussion I still feel .createSingle or .createOptions is worth the cost. You can take a look at any professional CMS and you will find this feature.

[gautamsi]

I would not want to create a single item list where there are 100s of settings items (look at vscode settings page, it has so many items). I would definitely be interested in Options/Settings page though.

for this I would propose this:

• have a field of type dynamic, meaning I can select the field type before entering the information, possibly a select field would have type information.
• admin ui should render these two fields as combo field for such changes. (not sure if state machine would help in this)
• we can have a meta list (or a hidden list) which would hold the settings values as item in the list.
• possibly Keystone may take advantage of this to store and reload config item and we wont have to change the deployment with environment variable.
• have a configuration designer which would show the raw list like the list in admin ui today, but the option page would render them like page of settings grouped under categories (field value)
  - something similar was in KS4, where you could create headings for the items shown in the list edit page.

[molomby]

I would not want to create a single item list where there are 100s of settings items (look at vscode settings page, it has so many items).

This is an interface concern though, yes? Whether the options are organised in the Admin UI across different tabs, sections, pages, headings (like in KS5) or whatever; doesn't mean it's not a singleton list behind the scenes.

have a field of type dynamic, meaning I can select the field type before entering the information, possibly a select field would have type information.

This and the state machine thing sound pretty tangental to the topic of this discussion. Surely both these types of functionality would be useful in normal lists too?

we can have a meta list (or a hidden list) which would hold the settings values as item in the list.

Not sure why you'd restrict it to only one, what you mean by hidden or in what sense the list would be "meta"?

I'm guessing a little here but I think the "settings" problem you're trying to solve (that is, a set of fields that configure a Keystone instance), is more specific that the more general "singleton lists" concept we're talking about. A settings list is something you could build using a singleton list, but there are plenty of other things too.

What if I want to store a timestamp of the last time some worker process ran? Or build some kind of locking system, used by multiple processes? These both require a single value to be stored in some central location like the DB. They're not "settings" though.

possibly Keystone may take advantage of this to store and reload config item and we wont have to change the deployment with environment variable.

I imagine singleton lists will be used as a substitute for environment variables in some cases but I'd suggest caution with this approach. In most cases I subscribe to the 12 factor app paradigm which insists config be store in the environment.

[molomby]

Oh, is this the concept you mean by meta lists? I think I follow now

[gautamsi]

This and the state machine thing sound pretty tangental to the topic of this discussion. Surely both these types of functionality would be useful in normal lists too?

this will help normal list too. one other effort is to bring back dependsOn feature

from meta list I meant internally managed list (aux list or meta list) which are not visible in UI.

I imagine singleton lists will be used as a substitute for environment variables in some cases but I'd suggest caution with this approach. In most cases I subscribe to the 12 factor app paradigm which insists config be store in the environment.

12 factor is good and we should have config in env variable, but things which change frequently and have to be saved is not good for env. One example is short lived access token. What I meant was to have some in memory caching which can be reloaded (or set by afterChange hook) periodically. I can save that in db when the token change but do not have to read them every time form db, in memory should be good. settings may be accessible at runtime (keystone.settings.*) after initially read from db and no need to read from db every single time.

[MadeByMike]

@gautamsi Could all the features you mention be served by the existing field types? I'd much rather leverage the fields so that an options page IS just like a list under the hood. This means we get a lot of the work done for free.

[gautamsi]

"dynamic type" field is not yet now. if that comes, all of this becomes reality.
#1528 is RFC and not yet a reality, original idea for that in #312. dependsOn was discussed few times, keystonejs/keystone-5#322 (comment) and #1355

[jesstelford]

@MadeByMike A couple things worth noting in your original proposal:

The following list config would not be required on options pages: labelField, labelResolver

These two might want to still exist; they're what generates the special _label_ field. Removing that field would require extra code throughout the Admin UI to handle when it doesn't exist.

No id should be required [for update]

This is correct, however an id field should be returned as part of the result of a mutation; most GraphQL client libraries use this as a cache ID and without it cannot cache values / cache them incorrectly.

[molomby]

But the ID should be hard-coded to a static value I guess? Like 'singleton' or something

[MadeByMike]

@jesstelford

1. The labelField and labelResolver are only used for items in a list view right? Would any route in the AdminUI hit this anywhere for a single item? If so we could leave them or just let them take the defaults.
2. Yep, I expect it would return an id along any other params the item has.

[MadeByMike]

We need to be able to create options on a list as well. It seems very likely that there will be per list options in many application. One example that surfaced this was my attempt to create role based access control via the new list plugin feature:

This works for individual items and maybe it still should but it also make sense to apply these settings to a list. Perhaps the API should be consistent:

keystone.addOptions()
list.addOptions()

My demo: https://github.com/MadeByMike/keystone-access-control-demo

[wesbos]

Options page would be awesome!

[internetErik]

I know this is specifically for a use-case displaying an options panel in the CMS, but I would also find this useful for content entry for individual pages. I can achieve this by making the fields no create/delete when after they are first created, but the user interface is still awkward for clients (there are extra clicks to go into the list view, etc).

There is the adminOptions object that is passed in at list creation, this handles some aspects of what data is brought into the listing view in the admin interface. For me, it would be good enough to add a singleton configuration there:

keystone.createList('Options', {
  adminConfig : { singleton: true }
});

This could be handled in a few ways. Perhaps the simplest (but janky) is that, if(singleton === true), the UI would redirect itself to the first item in the list automatically, and there would be no button for creating a new item.

[gautamsi]

would it be interesting to have a controlling list for item limiter per user or per list?

Singleton List

I am going to create a PR for a singleton list plugin which can have hooks to prevent more than one item in the list.
questions:

1. should we allow deleting the only Item? I will add it as configurable.
2. should there be admin-ui option to mark this as settings list and show a ⚙️ in nav bar bottom to go to this list? or just like a normal list.

some other solution comes to my mind when considering singleton list.

Limiting number of items in list by dev time numbers

list plugin only solution which will enforce max items in a list and also optionally min items (it will not let you delete the item which will make overall item count to less than min allowed)?

Limiting list items based on a ref list

This came to my mind while thinking about above that a max item plugin can also be used with combination of a admin managed list (all access to admin/su only) where the information for list items are stored. for example:
admin list

item 1: 
     listname: taskList
     maxItems: 20
item 2: 
    listName: complainList
    maxItem: 5

the hook is then applied to taskList and complainList which would limit the number of items dynamically. really useful if combined with user authentication that can affect how much this user should be allowed to.

kind of a solution to manage these limitation without redeploying the solution. This may also be useful in adding a dynamic setting value which are usually set at build/deploy time like max item returned in a graphql query.

[MurzNN]

If we talking about singletons, they are always must have only one item, and must be accessed directly by singleton id, instead of something like id = 1. So feature with "maxItems" is useful for lists, but, as I think, not related directly to singletones.

For Singleton items I think will be much better to use some separate key-value storage, instead of separate tables (or mongo collections) for store only one item. So create some system list "Singletones" with only two fields:

• key (string, unique, primary) - to store the unique key of singleton item.
• value (JSON) - to store any complex data as JSON object, together with JSON field from roadmap.

This will dramatically speed-up loading and saving items and decrease complexity of database, because for singletones we don't need field indexing, filtering, ordering and all other features, only direct load-save the whole block of data.

And reuse only this one table to store all singletones, defined in Keystone, with future ability to use redis or other more robust key-value storage as backend, instead of full-featured database.