Hi Tony! Thanks for this review, and continued details that we went through during the PCP API call today. Some specific comments about the DevPTT comments inline.
> On Apr 12, 2017, at 4:45 AM, Tony Atkins <[email protected]> wrote: > > Hi, Steve: > > Thanks for sharing this with the group, I watched the video a couple of times > and read through the code. You and I discussed this a little privately, and > I hope that we will have wider discussions in upcoming architecture and PCP > API meetings. In the meantime, I wanted to share my thoughts about where you > and I will need to coordinate your work with larger efforts, and on a few > patterns I think might make further work easier. > > First, the work to date is an impressive start. As more of us work on > presenting UIs that ultimately result entering in schema-validated JSON data, > I suspect we'll end up reusing some of your work more widely. Well done. > Yeah... I'm excited for Real People to start configuring and extending the GPII. > Second, just to confirm, my vision is that eventually this interface will be > working not with existing combined JSON files, but from the "live registry" > (more on that in a separate note). As part of this, I'd imagine us fleshing > out what each of these settings mean in concrete terms, i.e. as a series of > core JSON schemas that can be reused in building schemas for individual > settings. Well-written schemas can also be reused or extended for different > use cases (UI work like yours, API payload validation, et cetera). > Yeah... honestly, I would like it to be either. I hope that I can sufficiently factor the reading into a datasource, or datasource-like configuration such that it could be a live server, or for local development and debugging you could just hand it the huge JSON file... or even a JSON file that is part of the acceptance tests if you needed to view/tweak that. But yeah, the main use case is eventually reading from the live deployed servers, and having this as part of our deployed set of cloud tools. I think there are some exceptions to that, such as presenting some bits in the UI concering where the data came from. If it's from a live registry, I imagine there might be some info there with change logs, who you are auth'd as etc. If it's just from a file... it might just show the file name. But for the actual reading of the settings and populating the editing tables... I hope that those parts look and act the same regardless of where it came from. But as you point out, I should make sure this operates as expected sooner than later... so I don't get addicted and specialized to reading files from the local file system. > This leads to my largest suggestion regarding your early work: Right now, I > see hard-coded schemas inline in one massive file > <https://github.com/sgithens/gpii-devpmt/blob/ec8d8bb3a454c3820b839c4ebd7696095f4a3c07/src/js/commonTerms.json5#L5>. > I would suggest replacing the inline schemas with a schema key that refers > to an external file, for example, a relative URI or schema id. Your > validator should be made aware of the full range of schemas on creation, and > should be able to resolve which schema you mean from the ID or URI. You can > see examples of this in my client-side validation work in the > gpii-json-schema package <https://github.com/GPII/gpii-json-schema>. > That totally makes sense, if using json schema can factor out just the common ones that can be included, with only some of the wonky ones requiring their own definitions. I would however like to avoid, as much as possible, a proliferation of massive amounts of tiny files. So if I can create like 5 of them that represent most of them, and just link to them, that would be great. I feel like some of them will still need to be filled out in there. I hope that there is a way of programmitically driving the validator as well, so if you are just editing something and don't want to create a million files, or have things bunched together for an acceptance test, you could just trawl the json, or couch instance or whatever, and when you hit a node that needs validating call it. That one massive file, will only be for generic_prefs/common_terms, with the application specific ones coming from their settings info in their solutions registry entries. But from the PCP call, I am thoroughly bracing myself for this to change at any time. > Once you have something other than inline schemas, we can begin the key work > of building and reusing common definitions. For example, as shown in your > video, there are many settings that accept "a valid color". Once we can link > to and reuse common schemas, we would just have one schema that describes a > particular way of representing each "color", and then we'd reuse that. > Right on. > I also see that your use is fairly limited at the moment, relying heavily on > the variable type, with the occasional enumerated list. We have a lot more > tools at our disposal within the standard to bring "what's allowed in the UI" > closer to "what's likely to actually work". For example, there is the option > to suggest a default, to provide information about the range of values for > integers, the supported level of precision for integers, and many other > options. These are good topics for detailed reviews (see below). > Yeah, my effort at the moment as been to quickly get them editable, with just enough types so that they are written back in to the prefset with the correct JSON type (string, number, object, boolean) so that they will actually work in the GPII. Now that I have gotten a fair amount of the UI filled in, we can look towards making the little sidebar awesomer. > In the video, you also mentioned the need for more human facing instructions. > I have in the past used description metadata > <https://spacetelescope.github.io/understanding-json-schema/reference/generic.html#metadata> > for this purpose, even using a field's description to populate a label for > the field. Even if you don't want to go that far, descriptions are useful > for anyone reviewing your work, future developers, et cetera. I have also > used them like JSDocs or plain comments, to give myself and others an idea of > the intent behind the raw definition. > Oh wow, yeah, that's an awesome field. I will definately use that. > If your UI work with JSON schemas is anything like mine, I'm assuming you'll > also eventually want to present human-readable error messages. At least in > AJV, there is the option to define custom error messages within the schema > itself, which gpii-json-schema extends somewhat. This approach is likely > short-lived, as custom errors are not likely to become part of the core JSON > Schema standard. Speaking of which, as I pointed out to you in our chat last > week, there is an emerging JSON UI Schema spec > <https://github.com/json-schema-org/json-schema-spec/issues/67>. Whatever > approach we use for instructions and errors should probably change as that > matures, so that our work is easier to reuse down the road. > Right on, it would be super cool to use that and contribute to the spec. > Anyway, again, great effort, I look forward to seeing what you can do with > this tool, and what we all can do together working with schemas. On that > note, I mentioned this to you, but will mention it to anyone else working > with schemas. I am happy to review and comment on work that uses > gpii-json-schema, or even just plain schemas, to pair on problems, et cetera. > Thanks! And cheers to you! In addition to the core GPII/infusion libraries, I was largely capable of producing it in a reasonable amount of time because of all the libararies you pushed out last week. gpii-express, gpii-handlebars, gpii-binder, gpii-the-webdriver-module-testing-one, etc etc. It's really cool stuff. Cheers to the max, Steve > Cheers, > > > Tony > > On Wed, Apr 12, 2017 at 6:08 AM, Steven Githens <[email protected] > <mailto:[email protected]>> wrote: > Hi Arch, > > I wanted to give a quick update on the DevPTT tool I've been working on > recently. Based on work by Bern and the rest of the UX team, this tool is > geared towards admin/dev/staff type power users to build and edit > preference/snap sets. It will allow the creation of preference sets, along > with their metadata and specifying values for All common terms/generic > preferences and application specific terms. > > Visual Overview: > https://dl.dropboxusercontent.com/u/77127737/DevPTT_M3Update-20170411.mov > <https://dl.dropboxusercontent.com/u/77127737/DevPTT_M3Update-20170411.mov> > > A milestone 3 tag is here. I hope to upload a double clickable demo that > runs in an electron shell, but am having some build issues with > electron-packager tonight, hopefully available before Monday. > > https://github.com/sgithens/gpii-devpmt/tree/Milestone3 > <https://github.com/sgithens/gpii-devpmt/tree/Milestone3> > > My scratch list for the next few weeks includes: > - Making sure it's capable of creating all the April APCP snapsets (it's > actually pretty close for this purpose) > - Implementing the button to add contexts > - Adding the UI for creating a new preference set > - Filling in more metadata in the solutions registry, pulling some of it in > from Atkins modules, and collaborating on gpii-json-schema validation/editing > widget. ( This is why most of the products/applications in the list only have > "Enable" right now, and not a list of specific settings. ) > - gray out the save changes button until changes have been made, and show the > queued changes that haven't been saved yet. > - rework the bits that read the files in and out to use configurable > datasources ( so they can be from disk or a live gpii server ). > - Re-order the list of products and add basic filtering box to hide/show only > products you currently have enabled. > - Add a collapsable left hand sidebar with TOC for all the settings/products > on the page. > - Fix some flackyness with the right hand editor widget not always staying at > the top of the page. > - Submit for a PR code review > > Cheers, > Steve > > _______________________________________________ > Architecture mailing list > [email protected] <mailto:[email protected]> > http://lists.gpii.net/mailman/listinfo/architecture > <http://lists.gpii.net/mailman/listinfo/architecture> > >
_______________________________________________ Architecture mailing list [email protected] http://lists.gpii.net/mailman/listinfo/architecture
