@wix/patterns 1.366.0 → 1.370.0

package/dist/docs/CustomFieldsViewWidget.md

@@ -0,0 +1,191 @@
+# CustomFieldsViewWidget
+
+**Category:** Features/Enrich/Data Extension/Components
+
+## Overview
+
+### Introduction
+
+The `CustomFieldsViewWidget` component enhances the entity page by displaying both user-defined custom fields and custom fields that are defined by apps that are installed on the site.
+
+
+  
+
+
+
+### Getting Started
+
+1. Wrap your app with one of the Wix Patterns providers: [WixPatternsProvider](./?path=/story/base-components-providers--wixpatternsprovider).
+
+2. Add `CustomFieldsViewWidget` to one of your child components and pass the `extendedFields` prop to it from the `entity` object and `fqdn`.
+
+   Note: our guidelines is that `CustomFieldsViewWidget` should take 1/3 of the page width.
+
+```diff
+  import { MyEntityCard } from '../components/MyEntityCard';
+  import { MyEntity } from '@wix/ambassador-v1-entity/types';
++ import { CustomFieldsViewWidget } from '@wix/patterns';
+
+  function MyPageContent({ entity }: { entity: MyEntity }) {
+    return (
+        
+          
+            
+              
+            
++           
++             
++           
+          
+        
+    );
+  }
+```
+
+3. That's it! You can now see the `CustomFieldsViewWidget` in your app.
+
+
+## Examples
+
+### Basic
+
+This example demonstrates the component with all existing field types including initial values, showing both user defined fields and app fields.
+
+```tsx
+import React from 'react';
+import { CustomFieldsViewWidget } from '@wix/patterns';
+import { Cell, Layout, Card, Page, Text } from '@wix/design-system';
+import { DummyEntity } from '@wix/ambassador-cairo-dummyservice-v1-dummy-entity/types';
+
+function Basic() {
+  const demoEntity: DummyEntity = {
+    id: 'id',
+    name: 'Hello world!',
+    extendedFields: {
+      namespaces: {
+        _user_fields: {
+          datetime: '2023-05-31T21:00:00.000Z',
+          date: '1990-06-13',
+          shortText: 'Hello world!',
+          longText: 'Hello world! '.repeat(15),
+          checkbox: true,
+          decimal: 3.14,
+          integer: 43,
+          url: 'https://www.wix.com/',
+        },
+        '@company/app': {
+          app_longText: 'Amazing field!',
+        },
+      },
+    },
+  };
+
+  return (
+    <Page>
+      <Page.Header title="My Entity Page" />
+      <Page.Content>
+        <Layout>
+          <Cell span={8}>
+            <Card>
+              <Card.Header title="Name" />
+              <Card.Divider />
+              <Card.Content>
+                <Text>{demoEntity.name}</Text>
+              </Card.Content>
+            </Card>
+          </Cell>
+          <Cell span={4}>
+            <CustomFieldsViewWidget
+              fqdn="wix.patterns.dummyservice.v1.dummy_entity"
+              extendedFields={demoEntity.extendedFields}
+              title="Custom Title"
+            />
+          </Cell>
+        </Layout>
+      </Page.Content>
+    </Page>
+  );
+}
+```
+
+---
+
+### Inline
+
+Render the component in a inline theme. Can fit for a smaller screen like modals or sidebars.
+
+```tsx
+import React from 'react';
+import { CustomFieldsViewWidget } from '@wix/patterns';
+import { DummyEntity } from '@wix/ambassador-cairo-dummyservice-v1-dummy-entity/types';
+
+function Inline() {
+  const demoEntity: DummyEntity = {
+    id: 'id',
+    name: 'Hello world!',
+    extendedFields: {
+      namespaces: {
+        _user_fields: {
+          datetime: '2023-05-31T21:00:00.000Z',
+          date: '1990-06-13',
+          shortText: 'Hello world!',
+          longText: 'Hello world! '.repeat(15),
+          checkbox: true,
+          decimal: 3.14,
+          integer: 43,
+        },
+        '@company/app': {
+          app_longText: 'Amazing field!',
+        },
+      },
+    },
+  };
+
+  return (
+    <CustomFieldsViewWidget
+      fqdn="wix.patterns.dummyservice.v1.dummy_entity"
+      extendedFields={demoEntity.extendedFields}
+      theme="inline"
+    />
+  );
+}
+```
+
+## API
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `dataHook` | `string` | No | - | Applies a data-hook HTML attribute that can be used in tests. |
+| `fqdn` | `string` | Yes | - | The FQDN used to fetch the schema from the data-extension service. |
+| `extendedFields` | `ExtendedFields` | No | - | The current values of the extended fields. Typically, these values are found under the `extendedFields` property of the related entity (e.g., `myEntity.extendedFields`). |
+| `title` | `string` | No | - | A custom title for the widget. Overrides the default title. |
+| `userFieldsTitle` | `string` | No | - | A custom title for the "user-defined fields" section. Overrides the default section title. |
+| `theme` | `"inline" \| "card"` | No | - | Determines the visual style of the widget. - `'inline'`: The widget is rendered inline with the surrounding content. - `'card'`: The widget is displayed in a card container. |
+
+## BI
+
+### Custom Fields View Widget BI Events
+
+| Event | Description |
+| ----- | ----------- |
+| [144:110](https://bo.wix.com/data-tools/bi-catalog-app/event/144:110) | Sent when a Cairo component starts loading. |
+| [144:111](https://bo.wix.com/data-tools/bi-catalog-app/event/144:111) | Sent when a Cairo component is done loading. |
+| [144:141](https://bo.wix.com/data-tools/bi-catalog-app/event/144:141) | Sent when a user clicks on a "try again" CTA. |
+| [144:164](https://bo.wix.com/data-tools/bi-catalog-app/event/144:164) | Sent when a an error in Cairo component loading process happen.  |
+
+
+
+### Component load events
+Event   |   Description   |
+--------- | --------------- |
+[144:110](https://bo.wix.com/data-tools/bi-catalog-app/event/144:110) | Sent when a Wix Patterns component starts loading
+[144:111](https://bo.wix.com/data-tools/bi-catalog-app/event/144:111) | Sent when a Wix Patterns component is done loading
+
+
+#### 🐪 Couldn't find what you need?
+* Check our [BI Catalog](https://bo.wix.com/data-tools/bi-catalog-app?viewId=all-items-view&selectedColumns=src%2Cevid%2Cname%2Cowner%2Cproduct%2CuserType+false%2CdateUpdated%2CdateCreated+false%2CcreatedBy+false%2Cstatus&source=%5B%7B%22id%22%3A%22144%22%2C%22name%22%3A%22144+-+Cairo%22%7D%5D)
+* Contact us on [#cairo-bi](https://wix.slack.com/archives/C03N53KURH9)
+
+