From 813ea4facc5545f68a41364f937461a6cd680a41 Mon Sep 17 00:00:00 2001 From: Miro Yovchev <2827783+myovchev@users.noreply.github.com> Date: Fri, 28 Jul 2023 13:38:25 +0300 Subject: [PATCH] In-code docs and tiny fixes --- .../schema/ui/apos/logic/AposSubform.js | 15 ++++ modules/@apostrophecms/settings/index.js | 88 +++++++++++++++++++ .../ui/apos/components/AposSubformPreview.vue | 14 +-- 3 files changed, 110 insertions(+), 7 deletions(-) diff --git a/modules/@apostrophecms/schema/ui/apos/logic/AposSubform.js b/modules/@apostrophecms/schema/ui/apos/logic/AposSubform.js index 85f6bc07f9..70a3099e2c 100644 --- a/modules/@apostrophecms/schema/ui/apos/logic/AposSubform.js +++ b/modules/@apostrophecms/schema/ui/apos/logic/AposSubform.js @@ -1,3 +1,18 @@ +// Renders a single subform by configuration. Supports preview and edit modes. +// The component is not tied to a specific module and communicates with the +// parent component via events. See the `AposSettingsManager` component for +// an example of how to implement this component. +// +// ## Props +// `values` prop is the current value of the subform, which is an object. +// `subform` prop is the schema for the subform, which is an object. +// `errors` prop is an array or object as expected by the Editor Mixin. +// `busy` prop is a boolean indicating whether the subform (edit mode) is busy. +// `expanded` prop is a boolean indicating whether the subform is in preview (false) +// or edit (true) mode. +// `updateIndicator` prop is a boolean indicating whether the subform should +// display an updated indicator in preview mode. + import { klona } from 'klona'; import AposEditorMixin from 'Modules/@apostrophecms/modal/mixins/AposEditorMixin'; diff --git a/modules/@apostrophecms/settings/index.js b/modules/@apostrophecms/settings/index.js index cb617f7dc0..899d777130 100644 --- a/modules/@apostrophecms/settings/index.js +++ b/modules/@apostrophecms/settings/index.js @@ -1,3 +1,91 @@ +// Enable users to manage their personal settings (user record). +// +// ## Options +// +// `subforms` +// +// An object with subform configurations. The key is the subform name, the value +// is the subform configuration, described bellow. Subforms rendered on the client +// side have two modes - preview and edit. The initial mode is preview. The configuration +// provides the necessary information for both modes. +// +// ```js +// subforms: { +// // The subform name +// name: { +// // Required subform fields, shown in the order specified. The fields should +// // exist in the user schema. The information is used in edit mode only. +// // Currently supported system user fields are 'adminLocale' and 'password'. +// // Keep in mind 'adminLocale' is available only if the `apostrophecms/i18n` module +// // has the appropriate configuration. +// fields: [ 'firstName', 'lastName' ], +// // Optional subform label. Used in both preview and edit mode. +// label: 'Profile', +// // Optional subform help text. It is rendered instead +// // the subform preview value in preview mode only. +// help: 'Your full name', +// // The subform value rendered in preview mode, but only if `help` option is not provided. +// // A string or i18n key / template can be specified. +// // If not specified, the UI will attempt to generate a +// // preview value based on the subform schema and field values (space separated). +// preview: '{{ firstName }} {{ lastName }}', +// // In effect ONLY if `preview` and `help` options are not present. Provide a custom, +// // already registered (admin UI) component to render the subform preview value. +// // The subform config object and current field values will be passed as props. +// previewComponent: 'MyComponent', +// // Optional protection type. Currently allowed values are `password` +// // and `true` (alias of `password`). If specified, the subform will be +// // protected by the user current password. +// protection: true, +// // Optional flag to indicate that the subform should be reloaded after save. +// reload: true +// } +// } +// ``` +// +// `groups` +// +// An object with group configurations. The key is the group name, the value +// is the group configuration, described bellow. Groups are used to organize +// subforms in the settings modal (tabs). If no groups are configured, a single group +// named "ungrouped" will be created. The order of the groups is respected. +// +// ```js +// groups: { +// // The group name +// account: { +// // The group label. +// label: 'Account', +// // The subforms that belong to the group. The order is respected. +// subforms: [ 'name', 'password' ] +// } +// } +// ``` +// +// ## API +// +// Add a protected field to the system protected fields list. This will ensure +// that any subform containing that field will be ALWAYS protected by +// the user current password. It is recommended to use this method in the +// `apostrophe:modulesRegistered` event handler. +// `self.apos.settings.addProtectedField(fieldName, protectionType)` +// +// Add a forbidden field to the forbidden fields list. This will ensure that +// the field will not be allowed in any subform. It is recommended to use this +// method in the `apostrophe:modulesRegistered` event handler. +// `self.apos.settings.addForbiddenField(fieldName)` +// +// Add a field to the reload after save fields list. This will ensure that +// the subform containing the field will be reloaded after save. +// It is recommended to use this method in the `apostrophe:modulesRegistered` +// event handler. +// `self.apos.settings.addReloadAfterSaveField(fieldName)` +// +// ## UI +// +// An example of custom `preivewComponent` and core components explained +// can be found in the relevant PR: +// https://github.com/apostrophecms/apostrophe/pull/4236 const { klona } = require('klona'); module.exports = { diff --git a/modules/@apostrophecms/ui/ui/apos/components/AposSubformPreview.vue b/modules/@apostrophecms/ui/ui/apos/components/AposSubformPreview.vue index 97913de99d..398027aa8f 100644 --- a/modules/@apostrophecms/ui/ui/apos/components/AposSubformPreview.vue +++ b/modules/@apostrophecms/ui/ui/apos/components/AposSubformPreview.vue @@ -6,11 +6,12 @@
- + {{ previewValue }}
@@ -77,8 +78,7 @@ function inferFieldValues(schema, values, $t) { case 'select': { result[field.name] = field.choices .filter(choice => choice.value === value) - .map(choice => $t(choice.label)) - .join(', '); + .map(choice => $t(choice.label))[0] || ''; break; } @@ -86,7 +86,7 @@ function inferFieldValues(schema, values, $t) { const labels = []; for (const choice of field.choices) { if ((value || []).includes(choice.value)) { - labels.push(choice.label); + labels.push($t(choice.label)); } } result[field.name] = labels.join(', '); @@ -116,10 +116,10 @@ function inferFieldValues(schema, values, $t) { &__value { @include type-large; line-height: 1; + } - > span { - display: inline-block; - } + &__value-block { + display: inline-block; } &__value.is-help,