1# Updating Widget Content Through a Proxy
2
3A widget can be updated through a proxy – a system application that has data sharing enabled – when the widget provider is not running.
4
5## Implementation Principles
6
7**Figure 1** Updating widget content through a proxy
8![UpdateWidgetByProxyPrinciple](figures/UpdateWidgetByProxyPrinciple.png)
9
10Compared with the [implementation of the ArkTS widget](arkts-ui-widget-working-principles.md#implementation-principles) alone, updating through a proxy involves the data management service and data provider.
11
12- Data management service: provides a mechanism for data sharing among multiple applications.
13- Data provider: must be a system application that has data sharing enabled. The shared data is identified through the defined **key** + **subscriberId** combination.
14
15> **NOTE**
16>
17> This feature can be used when the system provides applications as data providers and publicly available shared data identifiers.
18
19Processing flow of the widget provider (indicated by the blue arrows in the figure):
20
211. The widget provider sets the **dataProxyEnabled** field to **true** in the **form_config.json** file to enable the update-through-proxy feature.
22> **NOTE**
23>
24> After the update-through-proxy feature is enabled, the settings for [updating periodically](arkts-ui-widget-update-by-time.md) do not work.
25
262. In the [onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onaddform) callback, the widget provider returns the **key** + **subscriberId** combination defined by the data provider to the Widget Manager.
27
283. The Widget Manager parses the subscription information of the widget provider and registers a subscription instance with the data management service.
29
30Processing flow of the widget update proxy (indicated by the red arrows in the figure):
31
321. The data provider uses the **key** + **subscriberId** combination as the data ID to store data to the database.
332. The data management service detects the change in the database and publishes the new data to all currently registered subscription instances.
343. The Widget Manager parses data from the subscription instance and sends the data to the widget rendering service.
354. The widget rendering service runs the widget page code **widgets.abc**, which implements rendering based on the new data and sends the rendered data to the <!--Del-->[<!--DelEnd-->FormComponent<!--Del-->](../reference/apis-arkui/arkui-ts/ts-basic-components-formcomponent-sys.md)<!--DelEnd--> corresponding to the widget host.
36
37There are two types of shared data provided by the data provider:
38
39- Ephemeral data: data that exists only for a specific period of time and can be subscribed to by system and non-system applications alike.
40
41- Persistent data: data that persists over time and can only be subscribed to by system applications.
42
43The update-through-proxy configuration varies by the type of shared data.
44<!--Del-->
45## Data Provider Development
46
47For details, see [Data Management](../database/share-data-by-silent-access.md).
48<!--DelEnd-->
49## Widget Provider Development (Ephemeral Data)
50
51- Set the **dataProxyEnabled** field to **true** in the **form_config.json** file to enable the update-through-proxy feature.
52  ```json
53  {
54    "forms": [
55      {
56        "name": "WidgetProcessData",
57        "description": "$string:ProcessDataEntryAbility_desc",
58        "src": "./ets/widgetprocessdata/pages/WidgetProcessDataCard.ets",
59        "uiSyntax": "arkts",
60        "window": {
61          "designWidth": 720,
62          "autoDesignWidth": true
63        },
64        "colorMode": "auto",
65        "isDefault": true,
66        "updateEnabled": true,
67        "scheduledUpdateTime": "10:30",
68        "defaultDimension": "2*2",
69        "supportDimensions": [
70          "2*2"
71        ],
72        "dataProxyEnabled": true
73      }
74    ]
75  }
76  ```
77
78- Configure the subscription information [proxyData](../reference/apis-form-kit/js-apis-app-form-formBindingData.md#proxydata10) in the [onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onaddform) callback and return the information to the Widget Manager through [formBinding](../reference/apis-form-kit/js-apis-app-form-formBindingData.md#formbindingdata). In this example, **key** is set to **datashareproxy://com.samples.widgetupdatebyproxy/weather** and **subscriberId** is set to **11**.
79  > **NOTE**
80  >
81  > The value of **key** can be a URI or a simple string. The default value of **subscriberId** is the value of **formId**. The actual value depends on the definition of the data provider.
82  ```ts
83  import { formBindingData, FormExtensionAbility } from '@kit.FormKit';
84  import { Want } from '@kit.AbilityKit';
85  import { hilog } from '@kit.PerformanceAnalysisKit';
86
87  const TAG: string = 'ProcessDataFormAbility';
88  const DOMAIN_NUMBER: number = 0xFF00;
89
90  export default class ProcessDataFormAbility extends FormExtensionAbility {
91    onAddForm(want: Want): formBindingData.FormBindingData {
92      let formData: Record<string, Object> = {};
93      let proxies: formBindingData.ProxyData[] = [
94        {
95          key: 'datashareproxy://com.samples.widgetupdatebyproxy/weather',
96          subscriberId: '11'
97        }
98      ];
99      let formBinding = formBindingData.createFormBindingData(formData);
100      formBinding.proxies = proxies;
101      hilog.info(DOMAIN_NUMBER, TAG, 'onAddForm');
102      return formBinding;
103    }
104  }
105  ```
106
107- In the [widget page code file](arkts-ui-widget-creation.md), use the variable in LocalStorage to obtain the subscribed data. The variable in LocalStorage is bound to a string and updates the subscribed data in the key:value pair format. The key must be the same as that subscribed to by the widget provider. In this example, the subscribed data is obtained through **'city'** and displayed in the **Text** component.
108  ```ts
109  let storageProcess = new LocalStorage();
110
111  @Entry(storageProcess)
112  @Component
113  struct WidgetProcessDataCard {
114    @LocalStorageProp('datashareproxy://com.samples.widgetupdatebyproxy/weather') city: ResourceStr = $r('app.string.loading');
115
116    build() {
117      Column() {
118        Column() {
119          Text(this.city)
120            .fontColor('#FFFFFF')
121            .opacity(0.9)
122            .fontSize(14)
123            .margin({ top: '8%', left: '10%' })
124        }.width('100%')
125        .alignItems(HorizontalAlign.Start)
126      }.width('100%').height('100%')
127      .backgroundImage($r('app.media.CardEvent'))
128      .backgroundImageSize(ImageSize.Cover)
129    }
130  }
131  ```
132
133## Widget Provider Development (Persistent Data; for System Applications Only)
134- Set the **dataProxyEnabled** field to **true** in the **form_config.json** file to enable the update-through-proxy feature.
135  ```json
136  {
137    "forms": [
138      {
139        "name": "WidgetPersistentData",
140        "description": "This is a service widget update by proxy using persistent data.",
141        "src": "./ets/widgetpersistentdata/pages/WidgetPersistentDataCard.ets",
142        "uiSyntax": "arkts",
143        "window": {
144          "designWidth": 720,
145          "autoDesignWidth": true
146        },
147        "colorMode": "auto",
148        "isDefault": true,
149        "updateEnabled": true,
150        "scheduledUpdateTime": "10:30",
151        "updateDuration": 1,
152        "defaultDimension": "2*2",
153        "supportDimensions": [
154          "2*2"
155        ],
156        "dataProxyEnabled": true
157      }
158  ]
159  }
160  ```
161
162- Add a subscription template <!--Del-->[<!--DelEnd-->addTemplate<!--Del-->](../reference/apis-arkdata/js-apis-data-dataShare-sys.md#addtemplate10)<!--DelEnd--> to the [onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onaddform) callback and use the template predicates to notify the database of the subscribed data conditions. Then, configure the subscription information [proxyData](../reference/apis-form-kit/js-apis-app-form-formBindingData.md#proxydata10) and return it to the Widget Manager through [formBinding](../reference/apis-form-kit/js-apis-app-form-formBindingData.md#formbindingdata). In the example, the predicate is set to **"list": "select type from TBL00 limit 0,1"**, indicating that the first data record in the **type** column is obtained from the **TBL00** database. The data is returned to the widget page code file **widgets.abc** in {"list":[{"type":"value0"}]} format. When the subscribed persistent data is updated, the system automatically updates the widget data.
163
164  > **NOTE**
165  >
166  > - The value of **key** is a URI, which depends on the definition of the data release party.
167  > - The value of **subscriberId** can be customized. Ensure that the value of **subscriberId** in **addTemplate** is the same as that of **proxies.subscriberId**.
168  ```ts
169  import { formBindingData, FormExtensionAbility } from '@kit.FormKit';
170  import { Want } from '@kit.AbilityKit';
171  import { dataShare } from '@kit.ArkData';
172
173  export default class PersistentDataFormAbility extends FormExtensionAbility {
174    onAddForm(want: Want): formBindingData.FormBindingData {
175      let subscriberId = '111';
176      let template: dataShare.Template = {
177        predicates: {
178          'list': `select type from TBL00 where cityId = ${subscriberId}`
179        },
180        scheduler: ''
181      };
182      dataShare.createDataShareHelper(this.context, 'datashareproxy://com.samples.widgetupdatebyproxy', {
183        isProxy: true
184      }).then((data) => {
185        let dataShareHelper = data;
186        dataShareHelper.addTemplate('datashareproxy://com.samples.widgetupdatebyproxy/test', subscriberId, template);
187      });
188      let formData: Record<string, Object> = {};
189      let proxies: formBindingData.ProxyData[] = [
190        {
191          key: 'datashareproxy://com.samples.widgetupdatebyproxy/test',
192          subscriberId: subscriberId
193        }
194      ];
195
196      let formBinding: formBindingData.FormBindingData = {
197        data: JSON.stringify(formData),
198        proxies: proxies
199      };
200      return formBinding;
201    }
202  }
203  ```
204
205- In the [widget page code file](arkts-ui-widget-creation.md), use the variable in LocalStorage to obtain the subscribed data. The variable in LocalStorage is bound to a string and updates the subscribed data in the key:value pair format. The key must be the same as that subscribed to by the widget provider. In the example, the subscribed data is obtained through **'list'**, and the value of the first element is displayed on the **Text** component.
206  ```ts
207  let storagePersis = new LocalStorage();
208
209  @Entry(storagePersis)
210  @Component
211  struct WidgetPersistentDataCard {
212    readonly FULL_WIDTH_PERCENT: string = '100%';
213    readonly FULL_HEIGHT_PERCENT: string = '100%';
214    @LocalStorageProp('list') list: Record<string, string>[] = [{ 'type': 'a' }];
215
216    build() {
217      Column() {
218        Column() {
219          Text((this.list[0]['type']))
220            .fontColor('#FFFFFF')
221            .opacity(0.9)
222            .fontSize(14)
223            .margin({ top: '8%', left: '10%' })
224        }.width('100%')
225        .alignItems(HorizontalAlign.Start)
226      }.width(this.FULL_WIDTH_PERCENT).height(this.FULL_HEIGHT_PERCENT)
227      .backgroundImage($r('app.media.CardEvent'))
228      .backgroundImageSize(ImageSize.Cover)
229    }
230  }
231  ```
232
233