Improve documentation of generic fields (#4651)

superdesk · Nov 6, 2024 · 7024a6c · 7024a6c
1 parent a73fcec
commit 7024a6c
Show file tree

Hide file tree

Showing 20 changed files with 43 additions and 4 deletions.
diff --git a/scripts/apps/authoring-react/fields/attachments/index.tsx b/scripts/apps/authoring-react/fields/attachments/index.tsx
@@ -28,6 +28,16 @@ export const ATTACHMENTS_WIDGET_ID = 'attachments';
 export function getAttachmentsField(): IAttachmentsField {
     const field: IAttachmentsField = {
         id: ATTACHMENTS_FIELD_ID,
+
+        /**
+         * Not generic due to:
+         * - having a hardcoded fieldId in a side-widget
+         *
+         * Could be made generic by getting rid of side-widget
+         * or changing side-widget to support multiple fields.
+         */
+        generic: false,
+
         label: gettext('Attachments (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/date/index.tsx b/scripts/apps/authoring-react/fields/date/index.tsx
@@ -13,6 +13,7 @@ export function getDateField()
 : ICustomFieldType<IDateValueOperational, IDateValueStorage, IDateFieldConfig, IDateUserPreferences> {
     const field: ICustomFieldType<IDateValueOperational, IDateValueStorage, IDateFieldConfig, IDateUserPreferences> = {
         id: DATE_FIELD_ID,
+        generic: true,
         label: gettext('Date (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/dateline/index.tsx b/scripts/apps/authoring-react/fields/dateline/index.tsx
@@ -23,6 +23,7 @@ export function getDatelineField()
 : DatelineFieldType {
     const field: DatelineFieldType = {
         id: DATELINE_FIELD_ID,
+        generic: true,
         label: gettext('Dateline (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/dropdown/index.ts b/scripts/apps/authoring-react/fields/dropdown/index.ts
@@ -17,6 +17,7 @@ export const DROPDOWN_FIELD_ID = 'dropdown';
 export function getDropdownField(): ICustomFieldType<IDropdownValue, IDropdownValue, IDropdownConfig, never> {
     const field: ICustomFieldType<IDropdownValue, IDropdownValue, IDropdownConfig, never> = {
         id: 'dropdown',
+        generic: true,
         label: gettext('Dropdown (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/duration/index.tsx b/scripts/apps/authoring-react/fields/duration/index.tsx
@@ -16,6 +16,7 @@ export function geDurationField()
 : ICustomFieldType<IDurationValueOperational, IDurationValueStorage, IDurationFieldConfig, IDurationUserPreferences> {
     const field: ReturnType<typeof geDurationField> = {
         id: DURATION_FIELD_ID,
+        generic: true,
         label: gettext('Duration (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/editor3/index.tsx b/scripts/apps/authoring-react/fields/editor3/index.tsx
@@ -53,6 +53,7 @@ export function getEditor3Field()
 : ICustomFieldType<IEditor3ValueOperational, IEditor3ValueStorage, IEditor3Config, IUserPreferences> {
     const field: ICustomFieldType<IEditor3ValueOperational, IEditor3ValueStorage, IEditor3Config, IUserPreferences> = {
         id: EDITOR_3_FIELD_TYPE,
+        generic: true,
         label: gettext('Editor3 (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/embed/index.tsx b/scripts/apps/authoring-react/fields/embed/index.tsx
@@ -14,6 +14,7 @@ export function getEmbedField()
 : ICustomFieldType<IEmbedValueOperational, IEmbedValueStorage, IEmbedConfig, IEmbedUserPreferences> {
     const field: ReturnType<typeof getEmbedField> = {
         id: 'embed',
+        generic: true,
         label: gettext('Embed (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/linked-items/index.tsx b/scripts/apps/authoring-react/fields/linked-items/index.tsx
@@ -24,6 +24,7 @@ export const LINKED_ITEMS_FIELD_TYPE = 'linked-items';
 export function getLinkedItemsField(): ILinkedItemsField {
     const field: ILinkedItemsField = {
         id: LINKED_ITEMS_FIELD_TYPE,
+        generic: true,
         label: gettext('Linked items (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/media/index.tsx b/scripts/apps/authoring-react/fields/media/index.tsx
@@ -17,6 +17,7 @@ export function getMediaField()
 : ICustomFieldType<IMediaValueOperational, IMediaValueStorage, IMediaConfig, IMediaUserPreferences> {
     const field: ReturnType<typeof getMediaField> = {
         id: MEDIA_FIELD_ID,
+        generic: true,
         label: gettext('Media (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/package-items/index.tsx b/scripts/apps/authoring-react/fields/package-items/index.tsx
@@ -22,6 +22,17 @@ export const PACKAGE_ITEMS_FIELD_ID = 'package_items';
 export function getArticlesInPackageField(): IPackageItemsField {
     const field: IPackageItemsField = {
         id: PACKAGE_ITEMS_FIELD_ID,
+
+        /**
+         * 'linked_items' is a very similar field, but generic.
+         * It appears this field type was implemented to save time in comparison to
+         * creating configuration options for linked_items.
+         *
+         * It looks though there would only be 1 config needed,
+         * so I think we should do the config and drop this one in the future.
+         */
+        generic: false,
+
         label: gettext('Package items (authoring-react)'),
 
         editorComponent: Editor,

diff --git a/scripts/apps/authoring-react/fields/tag-input/index.tsx b/scripts/apps/authoring-react/fields/tag-input/index.tsx
@@ -22,6 +22,7 @@ type TagInputFieldType = ICustomFieldType<
 export function getTagInputField(): TagInputFieldType {
     const field: TagInputFieldType = {
         id: TAG_INPUT_FIELD_ID,
+        generic: true,
         label: gettext('Tag-input (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/time/index.tsx b/scripts/apps/authoring-react/fields/time/index.tsx
@@ -16,6 +16,7 @@ export function getTimeField()
 : ICustomFieldType<ITimeValueOperational, ITimeValueStorage, ITimeFieldConfig, ITimeUserPreferences> {
     const field: ICustomFieldType<ITimeValueOperational, ITimeValueStorage, ITimeFieldConfig, ITimeUserPreferences> = {
         id: TIME_FIELD_ID,
+        generic: true,
         label: gettext('Time (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring-react/fields/urls/index.tsx b/scripts/apps/authoring-react/fields/urls/index.tsx
@@ -16,6 +16,7 @@ export function getUrlsField()
 : ICustomFieldType<IUrlsFieldValueOperational, IUrlsFieldValueStorage, IUrlsFieldConfig, IUrlsFieldUserPreferences> {
     const field: ReturnType<typeof getUrlsField> = {
         id: URL_FIELD_ID,
+        generic: true,
         label: gettext('Urls (authoring-react)'),
         editorComponent: Editor,
         previewComponent: Preview,

diff --git a/scripts/apps/authoring/authoring/authoring-custom-field.spec.tsx b/scripts/apps/authoring/authoring/authoring-custom-field.spec.tsx
@@ -41,6 +41,7 @@ class TestEditorComponent extends React.PureComponent<IEditorComponentProps<stri
 
 const customField: ICustomFieldType<string, string, string, never> = {
     id: 'test-custom-authoring-field',
+    generic: true,
     label: 'Test Field',
     editorComponent: TestEditorComponent,
     previewComponent: () => null,

diff --git a/scripts/apps/vocabularies/controllers/VocabularyEditController.tsx b/scripts/apps/vocabularies/controllers/VocabularyEditController.tsx
@@ -311,7 +311,7 @@ export function VocabularyEditController(
 
     const fields = getFields();
 
-    $scope.customFieldTypes = Object.keys(fields).filter((id) => fields[id].private !== true).map((id) => ({
+    $scope.customFieldTypes = Object.keys(fields).filter((id) => fields[id].generic === true).map((id) => ({
         id: id,
         label: fields[id].label,
     }));

diff --git a/scripts/core/superdesk-api.d.ts b/scripts/core/superdesk-api.d.ts
@@ -3700,9 +3700,12 @@ declare module 'superdesk-api' {
         previewComponent: React.ComponentType<IPreviewComponentProps<IValueOperational, IConfig>>;
 
         /**
-         * Allows for the field to be hidden from custom field type config
+         * Field types should be made generic when possible.
+         * Making field types generic means multiple fields of the same type can be enabled in the same editing view.
+         * Generic fields will be available for adding to content profile via user interface (settings).
          */
-        private?: boolean;
+        generic: boolean;
+
         /**
          * Must return `true` if not empty.
          */

diff --git a/scripts/extensions/booleanField/src/extension.tsx b/scripts/extensions/booleanField/src/extension.tsx
@@ -13,6 +13,7 @@ const {gettext} = superdesk.localization;
 
 const booleanField: ICustomFieldType<IValueOperational, IValueStorage, ICommonFieldConfig, IUserPreferences> = {
     id: 'boolean',
+    generic: true,
     label: gettext('Boolean'),
     editorComponent: Editor,
     previewComponent: Preview,

diff --git a/scripts/extensions/broadcasting/src/authoring-fields/subitems/index.tsx b/scripts/extensions/broadcasting/src/authoring-fields/subitems/index.tsx
@@ -31,7 +31,7 @@ export function getSubItemsField(): ISubItemsFieldType {
         editorComponent: Editor,
         previewComponent: Preview,
 
-        private: true,
+        generic: false,
         hasValue: (valueOperational) => valueOperational != null && Object.keys(valueOperational).length > 0,
         getEmptyValue: () => [],
 

diff --git a/scripts/extensions/datetimeField/src/extension.tsx b/scripts/extensions/datetimeField/src/extension.tsx
@@ -25,6 +25,7 @@ function onTemplateCreate(_value: string, config: IConfig) {
 const datetimeField: ICustomFieldType<IValueOperational, IValueStorage, IConfig, IUserPreferences> = {
     id: 'datetime',
     label: gettext('Datetime'),
+    generic: true,
     editorComponent: Editor,
     previewComponent: Preview,
     configComponent: Config,

diff --git a/scripts/extensions/predefinedTextField/src/extension.tsx b/scripts/extensions/predefinedTextField/src/extension.tsx
@@ -10,6 +10,7 @@ const {gettext} = superdesk.localization;
 const predefinedField: ICustomFieldType<IValueOperational, IValueStorage, IConfig, IUserPreferences> = {
     id: 'predefined-text',
     label: gettext('Predefined text field'),
+    generic: true,
     editorComponent: Editor,
     previewComponent: Preview,
     configComponent: Config,