@supersoniks/concorde 2.0.7 → 3.0.1

package/src/core/utils/Utils.ts

@@ -0,0 +1,12 @@
+export default class Utils {
+  static async queueTaskPromise() {
+    return new Promise((resolve) => {
+      window.queueMicrotask(()=>resolve(null));
+    });
+  }
+  static async delayPromise(timeoutMs: number) {
+    return new Promise((resolve) => {
+      setTimeout(resolve, timeoutMs);
+    });
+  }
+}

package/src/core/utils/api.ts

@@ -0,0 +1,456 @@
+// on désactive une regle eslint pour ce fichier
+/* eslint no-async-promise-executor: 0 */ // --> OFF
+import HTML from "@supersoniks/concorde/core/utils/HTML";
+import Objects from "@supersoniks/concorde/core/utils/Objects";
+import {CoreJSType} from "@supersoniks/concorde/core/_types/types";
+import {PublisherManager} from "./PublisherProxy";
+
+export type APIConfiguration = {
+  serviceURL: string | null;
+  /** un flag pour indiquer de bloquer les appels suivant au même serviceurl tant que celuis-ci n'a pas terminé */
+  blockUntilDone?: boolean;
+  token: string | null;
+  userName: string | null;
+  password: string | null;
+  authToken: string | null;
+  tokenProvider: string | null;
+  addHTTPResponse?: boolean;
+  credentials?: RequestCredentials;
+  cache?: RequestCache;
+};
+export type CallState = "loading" | "done" | "error" | undefined;
+export type ResultTypeInterface = CoreJSType & {_sonic_http_response_?: Response; text?: string};
+export type APICall = {
+  apiMethod: "get" | "send" | "submitFormData";
+  path: string;
+  additionalHeaders: HeadersInit | undefined;
+  method?: string | undefined;
+  data?: unknown;
+  cache?: RequestCache;
+};
+class API {
+  /**
+   * Ce tableau static permet de ne pas appeler plusieurs fois le même service lors d'appel concurrents en GET.
+   */
+  static loadingGetPromises: Map<string, Promise<unknown>> = new Map();
+  /**
+   * L'url de base du service sans endpoint
+   */
+  serviceURL: string | null;
+
+  /**
+   * le nom de l'utilisateur si basic auth est utilisé
+   */
+  userName: string | null;
+
+  /**
+   * le password de l'utilisateur si basic auth est utilisé
+   */
+  password: string | null;
+
+  /**
+   * le bearer token a passer pour les appels REST
+   */
+  private _token: string | null | undefined;
+  set token(token: string | null | undefined) {
+    this._token = token;
+
+    if (!token) {
+      API.tokens.delete(this.serviceURL);
+      return;
+    }
+
+    if (API.invalidTokens.includes(token)) return;
+
+    API.tokens.set(this.serviceURL, token);
+  }
+  get token() {
+    // si le token est marqué invalide, on utilise utilise la dernière version valide connue du token pour ce serviceURL
+    return API.invalidTokens.includes(this._token) ? API.tokens.get(this.serviceURL) : this._token;
+  }
+  /**
+   * Le endPoint pour obtenir le bearer token qui sera concaténé à l'url du service
+   */
+  tokenProvider: string | null;
+
+  /**
+   * le bearer token à passer pour un éventuel renouvellement de token automatique
+   */
+  authToken: string | null;
+
+  /**
+   * credentials
+   */
+  credentials?: RequestCredentials;
+
+  /**
+   * Tableau static des tokens stokés en memoire vive (comportement à revoir à l'occasion)
+   */
+  static tokens = new Map<string | null, string | null | undefined>();
+
+  /**
+   * Tableau stockant l'ensemble des tokens invalides
+   */
+  static invalidTokens: (string | null | undefined)[] = [];
+
+  handleInvalidToken(token: string | null | undefined) {
+    if (!token) return;
+
+    if (API.invalidTokens.includes(token)) return;
+
+    API.invalidTokens.push(token);
+    this.token = null;
+  }
+
+  /**
+   * Tableau static des tentatives échouées de récupération auto du token
+   */
+  static failledTokenUpdates = new Map<string | null, true>();
+  /**
+   * Tableau static des flags pour savoir si le premier appel a été fait pour chaque serviceURL
+   */
+  static firstCallDoneFlags = new Map<string | null, CallState>();
+
+  /**
+   * Le endPoint pour obtenir le bearer token qui sera concaténé à l'url du service
+   */
+  addHTTPResponse = false;
+  cache: RequestCache = "default";
+  lastResult?: Response;
+  isServiceSimulated = false;
+  blockUntilDone = false;
+  constructor(config: APIConfiguration) {
+    this.serviceURL = config.serviceURL;
+    this.blockUntilDone = config.blockUntilDone || false;
+    if (this.serviceURL == "publisher://") {
+      this.isServiceSimulated = true;
+    }
+    if (!this.serviceURL) this.serviceURL = document.location.origin;
+    this.userName = config.userName;
+    this.password = config.password;
+    if (config.token) this.token = config.token;
+    this.tokenProvider = config.tokenProvider;
+    this.authToken = config.authToken;
+    this.addHTTPResponse = config.addHTTPResponse || false;
+    this.credentials = config.credentials;
+    this.cache = config.cache || "default";
+  }
+  async handleResult(fetchResult: Response, lastCall: APICall): Promise<ResultTypeInterface> {
+    API.firstCallDoneFlags.set(this.serviceURL, "done");
+    this.lastResult = fetchResult;
+    const contentType = fetchResult.headers.get("content-type")?.toLowerCase();
+    const httpCode = fetchResult.status;
+
+    let result: ResultTypeInterface = {};
+    if (!contentType || contentType.indexOf("text/") == 0) {
+      const str = await fetchResult.text();
+      result = {text: str} as typeof result;
+    } else {
+      try {
+        result = await fetchResult.json();
+      } catch (e) {
+        result = {} as typeof result;
+      }
+    }
+    if (this.addHTTPResponse && Objects.isObject(result)) {
+      result._sonic_http_response_ = fetchResult;
+    }
+
+    if (httpCode === 498 && !API.failledTokenUpdates.has(this.serviceURL)) {
+      this.handleInvalidToken(this.token);
+      if (lastCall.apiMethod === "get") {
+        result = await this[lastCall.apiMethod](lastCall.path, lastCall.additionalHeaders);
+      } else {
+        result = await this[lastCall.apiMethod](lastCall.path, lastCall.data, lastCall.method, lastCall.additionalHeaders);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Basic auth
+   */
+  async auth() {
+    if (this.token) return;
+    if (API.tokens.has(this.serviceURL)) {
+      this.token = API.tokens.get(this.serviceURL);
+      return;
+    }
+    if (!this.tokenProvider) return;
+
+    let headers = {};
+    if (this.userName && this.password) {
+      headers = {
+        Authorization: "Basic " + window.btoa(unescape(encodeURIComponent(this.userName + ":" + this.password))),
+      };
+    } else if (this.authToken) {
+      headers = {
+        Authorization: "Bearer " + this.authToken,
+      };
+    }
+
+    const serviceURL = new URL(this.serviceURL as string);
+    const serviceHost = serviceURL.protocol + "//" + serviceURL.host;
+    const result = await fetch(this.computeURL(this.tokenProvider as string, {serviceHost: serviceHost}), {
+      headers: headers,
+      credentials: this.credentials,
+    });
+
+    try {
+      const json = await result.json();
+      const newToken = json.token;
+      if (newToken) {
+        this.token = json.token;
+      } else {
+        API.failledTokenUpdates.set(this.serviceURL, true);
+      }
+    } catch (e) {
+      API.failledTokenUpdates.set(this.serviceURL, true);
+    }
+  }
+
+  /**
+   * avec localget, on ne passe pas par le système de token
+   * on recupère path sans les searchparams nommée pathWithoutSearchParams
+   * on cherche dans PublisherManager.get(pathWithoutSearchParams).get() les données qui matchent les searchparams présents dans path
+   * on retourne les données selon le même format que le retour de get
+   *
+   * @todo netttoyer
+   */
+  async localGet<T>(dataProvider: string, searchString: string) {
+    const publisher = PublisherManager.get(dataProvider);
+
+    console.log(publisher);
+    const searchParams = new URLSearchParams(searchString.split("?")[1] || "");
+    const dataObject = publisher.get();
+    let data = [];
+    if (!Array.isArray(dataObject)) {
+      data = [dataObject];
+    } else {
+      data = dataObject;
+    }
+
+    const result = [];
+
+    let limit = Number.POSITIVE_INFINITY;
+    let offset = 0;
+    let limitOffsetparams = 0;
+    if (searchParams.has("limit")) {
+      limit = parseInt(searchParams.get("limit") || "0");
+      limitOffsetparams++;
+    }
+    if (searchParams.has("offset")) {
+      offset = parseInt(searchParams.get("offset") || "0");
+      limitOffsetparams++;
+    }
+    if (limitOffsetparams > 0) {
+      searchParams.delete("limit");
+      searchParams.delete("offset");
+    }
+    if (searchParams.size === 0) return data.slice(offset, offset + limit) as T & ResultTypeInterface;
+    for (const [key, value] of searchParams.entries()) {
+      const values = value.split(",").map((s) => s.trim());
+      for (const v of values) {
+        for (const item of data) {
+          //si l'item est une valeur primitive on regarde si vaue correspond à item simplement
+          if (typeof item !== "object") {
+            if (!isNaN(+value)) {
+              if (item == value) {
+                result.push(item);
+              }
+            } else if (item.toString().includes(value)) {
+              result.push(item);
+            }
+          } else {
+            const record = item as Record<string, unknown>;
+            //si l'item est un objet
+            //faire un comparaison de la version string de la même clef dans item pour voir si elle contient value
+            if (!record[key]) continue;
+
+            //si la valeur est un nombre, on compare les valeurs directement
+            if (!isNaN(+v)) {
+              if (record[key] == v) {
+                result.push(item);
+              }
+            } else {
+              if (record[key]?.toString().toLowerCase().includes(v.toLowerCase())) {
+                result.push(item);
+              }
+            }
+          }
+        }
+      }
+    }
+    return result.slice(offset, offset + limit) as T & ResultTypeInterface;
+  }
+
+  /**
+   * firstCallDone is a function that returns a promise that is resolved when the first call to the API is done for each serviceURL whatever api instance is used
+   */
+  firstCallDone() {
+    return new Promise((resolve) => {
+      if (!API.firstCallDoneFlags.has(this.serviceURL)) {
+        API.firstCallDoneFlags.set(this.serviceURL, "loading");
+        resolve(true);
+      } else {
+        const loop = () => {
+          if (![undefined, "loading"].includes(API.firstCallDoneFlags.get(this.serviceURL))) {
+            resolve(true);
+          } else {
+            window.requestAnimationFrame(loop);
+          }
+        };
+        loop();
+      }
+    });
+  }
+
+  async get<T>(path: string, additionalHeaders?: HeadersInit) {
+    await this.firstCallDone();
+    if (this.blockUntilDone) {
+      API.firstCallDoneFlags.set(this.serviceURL, "loading");
+    }
+    const regExp = /dataProvider\((.*?)\)(.*?)$/;
+    if (regExp.test(path)) {
+      const match = path.match(regExp);
+      if (!match) throw new Error("dataProvider path is not valid");
+      return await this.localGet<T>(match[1], match[2]);
+    }
+    const lastCall: APICall = {
+      apiMethod: "get",
+      path: path,
+      additionalHeaders: additionalHeaders,
+    };
+    const headers = await this.createHeaders(additionalHeaders);
+    const url = this.computeURL(path);
+    const mapKey = JSON.stringify({
+      url: url,
+      headers: headers,
+    });
+    if (!API.loadingGetPromises.has(mapKey)) {
+      const promise = new Promise(async (resolve) => {
+        try {
+          const result = await fetch(url, {headers: headers, credentials: this.credentials, cache: this.cache});
+          const handledResult = await this.handleResult(result, lastCall);
+          resolve(handledResult);
+        } catch (e) {
+          resolve(null);
+        }
+      });
+      API.loadingGetPromises.set(mapKey, promise);
+    }
+    const result = (await API.loadingGetPromises.get(mapKey)) as T;
+    API.loadingGetPromises.delete(mapKey);
+    return result as T & ResultTypeInterface;
+  }
+  /**
+   * Création du header, avec authentification si besoin
+   * ajout du language via le header accept-language qui contient le langue du navigateur
+   */
+  async createHeaders(additionalHeaders?: HeadersInit) {
+    await this.auth();
+    const headers: HeadersInit = {};
+    if (this.token) headers.Authorization = "Bearer " + this.token;
+    headers["Accept-Language"] = HTML.getLanguage();
+    if (additionalHeaders) {
+      Object.assign(headers, additionalHeaders);
+    }
+    return headers;
+  }
+
+  /**
+   * Concatène le serviceURL et le endpoint donné en paramètre
+   */
+  computeURL(path: string, query: Record<string, string> = {}) {
+    let url = "";
+    if (path.startsWith("http")) url = path as string;
+    else url = this.serviceURL + "/" + path;
+
+    if (!url.startsWith("http")) url = window.location.origin + url;
+
+    const computedUrl = new URL(url);
+    for (const key in query) {
+      computedUrl.searchParams.set(key, query[key]);
+    }
+
+    return computedUrl.toString().replace(/([^(https?:)])\/{2,}/g, "$1/");
+  }
+
+  /*
+   * Envoie des données au endPoint passé en paramètre. par défaut en POST
+   */
+  async send<T, SendType = CoreJSType>(path: string, data: SendType, method = "POST", additionalHeaders?: HeadersInit) {
+    const lastCall: APICall = {
+      apiMethod: "send",
+      path: path,
+      additionalHeaders: additionalHeaders,
+      method: method,
+      data: data,
+    };
+
+    const headers = await this.createHeaders(additionalHeaders);
+    headers["Accept"] = "application/json";
+    headers["Content-Type"] = "application/json";
+    const result = await fetch(this.computeURL(path), {
+      headers: headers,
+      credentials: this.credentials,
+      method: method,
+      body: JSON.stringify(data),
+    });
+    return (await this.handleResult(result, lastCall)) as T & ResultTypeInterface;
+  }
+
+  /**
+   * Agit comme une soumission de formulaire, mais attends un json en réponse
+   */
+  async submitFormData<T, SendType = CoreJSType>(path: string, data: SendType, method = "POST", additionalHeaders?: HeadersInit) {
+    const lastCall: APICall = {
+      apiMethod: "submitFormData",
+      path: path,
+      additionalHeaders: additionalHeaders,
+      method: method,
+      data: data,
+    };
+    const headers = await this.createHeaders(additionalHeaders);
+    headers["Accept"] = "application/json";
+    const formData = new FormData();
+    const dynamicData = data as unknown as {[property: string]: string};
+    for (const z in dynamicData) formData.set(z, dynamicData[z]);
+    const result = await fetch(this.computeURL(path), {
+      headers: headers,
+      credentials: this.credentials,
+      method: method,
+      body: formData,
+    });
+    return (await this.handleResult(result, lastCall)) as T & ResultTypeInterface;
+  }
+
+  /**
+   * Appel send en utilisant le méthode PUT
+   */
+  async put<T, SendType = CoreJSType>(path: string, data: SendType, additionalHeaders?: HeadersInit) {
+    return this.send<T, SendType>(path, data, "PUT", additionalHeaders);
+  }
+
+  /**
+   * Appel send en utilisant le méthode POST
+   */
+  async post<T, SendType = CoreJSType>(path: string, data: SendType, additionalHeaders?: HeadersInit) {
+    return this.send<T, SendType>(path, data, "POST", additionalHeaders);
+  }
+  /**
+   * Appel send en utilisant le méthode PATCH
+   */
+  async patch<T, SendType = CoreJSType>(path: string, data: SendType, additionalHeaders?: HeadersInit) {
+    return this.send<T, SendType>(path, data, "PATCH", additionalHeaders);
+  }
+
+  /**
+   * Appel send en utilisant le méthode delete
+   */
+  async delete<T, SendType = CoreJSType>(path: string, data: SendType, additionalHeaders?: HeadersInit) {
+    return this.send<T, SendType>(path, data, "delete", additionalHeaders);
+  }
+}
+export default API;

package/{core/utils/url-pattern.d.ts → src/core/utils/url-pattern.ts}

@@ -1,2 +1,3 @@
 import UrlPattern from "url-pattern";
+
 export default UrlPattern;

package/{decorators.js → src/decorators.ts}

@@ -1,8 +1,12 @@
 import * as mySubscriber from "@supersoniks/concorde/core/decorators/Subscriber";
 export const bind = mySubscriber.bind;
 export const onAssign = mySubscriber.onAssign;
+
+import {ConcordeWindow} from "./core/_types/types";
+declare const window: ConcordeWindow;
+
 window["concorde-decorator-subscriber"] = window["concorde-decorator-subscriber"] || {};
 window["concorde-decorator-subscriber"] = {
-    bind: mySubscriber.bind,
-    onAssing: mySubscriber.onAssign,
+  bind: mySubscriber.bind,
+  onAssing: mySubscriber.onAssign,
 };

package/{directives.js → src/directives.ts}

@@ -1,16 +1,21 @@
 import * as myDataProvider from "@supersoniks/concorde/core/directives/DataProvider";
+
+import {ConcordeWindow} from "./core/_types/types";
 export const dp = myDataProvider.dp;
 export const dataProvider = myDataProvider.dataProvider;
 export const subscribe = myDataProvider.subscribe;
 export const sub = myDataProvider.sub;
 export const get = myDataProvider.get;
 export const set = myDataProvider.set;
+
+declare const window: ConcordeWindow;
+
 window["concorde-directives-data-provider"] = window["concorde-directives-data-provider"] || {};
 window["concorde-directives-data-provider"] = {
-    dp: myDataProvider.dp,
-    dataProvider: myDataProvider.dataProvider,
-    sub: myDataProvider.sub,
-    subscribe: myDataProvider.subscribe,
-    get: myDataProvider.get,
-    set: myDataProvider.set,
+  dp: myDataProvider.dp,
+  dataProvider: myDataProvider.dataProvider,
+  sub: myDataProvider.sub,
+  subscribe: myDataProvider.subscribe,
+  get: myDataProvider.get,
+  set: myDataProvider.set,
 };

package/src/docs/_core-concept/overview.md

@@ -0,0 +1,57 @@
+# lit + tailwind + vite
+
+**Some notes for an overview of Concorde's functioning**
+
+## Standard Web components
+A web component is simply a **custom HTML element** created using web standards:
+
+**web component** = [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) + [shadowDom](https://developer.mozilla.org/fr/docs/Web/Web_Components/Using_shadow_DOM) + [HTML templates](https://developer.mozilla.org/fr/docs/Web/HTML/Element/template)
+
+## Lit Library
+
+Concorde components are written using the lightweight Lit library: https://lit.dev/.
+
+A good portion of the elements documented on the Lit website are standard JavaScript concepts (e.g., [mixins](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#mix-ins), [tagged template literals](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Template_literals#gabarits_%C3%A9tiquet%C3%A9s)).
+
+The **library simplifies the writing of web components** by automating certain tasks:
+
+- Creation of an **open mode shadow DOM** (the component is accessible from the outside via its shadow root property).
+- [Rendering function](https://lit.dev/docs/components/rendering/) based on [tagged template literals](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Template_literals#gabarits_%C3%A9tiquet%C3%A9s)
+- [Reactive properties](https://lit.dev/docs/components/properties/) that trigger rendering when modified.
+
+Our use of Lit rarely goes beyond this [hello world](https://lit.dev/playground/#sample=examples/hello-world)
+
+## Typescript Language
+
+We write the components in [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html), which is then compiled into JS.
+
+Static and inferred typing provides stronger validation of the program's functioning during compilation.
+However, we often use the "any" type due to time constraints.
+
+Lit uses TypeScript to simplify development through metadata:
+- Simplified declaration of `custom elements` via @customElement
+- Generation of `reactive properties` via @property.
+
+☢️**Warning**:
+- During development, we operate in interpreted mode, which is faster but allows errors that won't pass during the build.
+- It is important to **build a distribution before pushing the code** to ensure everything is fine.
+
+## Compatibility with Classic JS Libraries
+
+Compatibility issues may arise when using JS libraries, particularly regarding DOM traversal.
+This is because these libraries are blocked from traversing the DOM due to the presence of the shadow DOM.
+Here are some examples of things that may cause problems:
+
+- Latest FontAwesome in SVG mode, icons are not replaced
+- Libraries associated with jQuery
+- document.getElementById
+- ...
+
+## Topics to Explore for Further Learning
+
+
+[🧱 Creating components](#docs/_getting-started/create-a-component.md/create-a-component)
+
+[🎨 Adding styles](#docs/_getting-started/theming.md/theming)
+
+[🥨 Sharing data](#docs/_getting-started/pubsub.md/pubsub)

package/src/docs/_core-concept/subscriber.md

@@ -0,0 +1,76 @@
+# 🔔 The subscriber mixin
+
+This is a mixin that is commonly extended by Concorde core components and destination components. Pure UI components usually don't extend it, especially those outside of form components.
+
+## DataProvider Attribute: Automatic Filling of Subscriber Properties
+
+Upon being added to the DOM (connectedCallback), subscribers search for the first occurrence of the `dataProvider` attribute in their parent's HTML structure.
+
+The value of this attribute is used to obtain a publisher via the PublisherManager (see [🥨 Sharing Data](#docs/_getting-started/pubsub.md/pubsub)).
+
+The subscriber then subscribes to the publisher as a data template to be filled.
+
+The reactive properties of the component reflect in real-time the properties with the same name in the publisher.
+
+This functionality is commonly used in the generic components [fetch](#core/components/functional/fetch/fetch.md/fetch), [queue](#core/components/functional/queue/queue.md/queue), and [list](#core/components/functional/list/list.md/list).
+
+If the subscriber is inside another subscriber, it can subscribe to a data of its parent using the attribute `subDataProvider = 'address.of.my.data'` instead of the parent's data. This allows for dynamic behavior.
+
+## Automated Translation
+
+In a similar manner, searching for ancestor attributes can be used to configure automatic translation for any property starting with "wording" and ending with a label identifier recognized by the wordingProvider API.
+
+Normally, this API is globally configured and not within the component. Therefore, remember to prefix translatable label identifiers present in the ticketing system, for example, with "wording".
+
+## Reactive Property `props`
+
+The value of this property can be provided as a JSON object or any other value. This value is then assigned to the associated publisher via the `dataProvider` attribute. As a result, the reactive properties of all subscribers associated with the same `dataProvider` are filled as mentioned above.
+
+## Disabling Automatic Filling of Reactive Properties
+
+It is possible to disable the automatic filling of reactive properties in a particular component. To do so, set the variable `noAutoFill = true` in the component's class. However, the reactive property `props` will still be updated.
+
+For example, `sonic-subscriber` and `sonic-fetch` have this attribute because they do not have reactive properties.
+
+**☢ CAUTION:** When creating an object of type Subscriber or Fetcher, make sure to use the mixins and not directly extend the concrete fetch component (`sonic-fetch`) and subscriber component (`sonic-subscriber`). This is because the `noAutofill = true` attribute is set in those components.
+
+**TIPS:** 
+If you disable automatic filling, you will likely make the rendering dynamic by writing expressions like `this.props.my.subproperty`. If `props` is updated, the rendering will be triggered. However, if `this.props.my.subproperty` is directly modified, the rendering will not be triggered. To achieve more reactivity, you can enable rendering when any subproperty is modified. Simply set the variable `renderOnPropsInternalChange = true` in the class that implements the corresponding mixin.
+
+## Data Binding
+
+Suppose that:
+
+- You have a subscriber subscribed to a publisher via its `dataProvider` attribute.
+- The published data has the following structure:
+
+<sonic-code language="javascript">
+  <template>
+    {"img": { "avatar": "my-avatar.jpg", "caption": "look at my smile" }, "email": "an.email@example.com" }
+  </template>
+</sonic-code>
+- We want to keep the display of an image and its `title` attribute up to date, as well as a "contact" button to email the person in the photo. The content of the subscriber could be as follows:
+
+<sonic-code language="html">
+  <template>
+<img data-bind ::src="$img.avatar" ::title="ucFirst|$img.caption" />
+<a data-bind ::href="mailto:$email" ::inner-html="$email"></a>
+  </template>
+</sonic-code>
+
+This example also illustrates:
+
+- Binding to subproperties using dot syntax, as done for the `src` attribute of the `img` tag.
+- Using a simple expression to include the property within a string, as in creating a `mailto` link.
+- Using formatting functions, as in the `title` attribute of the `img` tag. You can find (and add) formatting functions in the `core/utils/Format.ts` file.
+- Writing for properties that are in camel case. Convert everything to lowercase and add hyphens. Note that `innerHTML` (or `outerHTML`) is a special case where no hyphens are added between each letter.
+
+**Note:** Data binding implies that updating the `img.src` data via the publisher will change the photo without any additional calls.
+
+**Special Variables:**
+- `_self_` targets the root of the data. This is useful, for example, when the data is a pure string.
+- `_parent_` targets the parent publisher of the current publisher, if any. For example, the subscribers of lists have the complete data of the list as their parent.
+- `_metadata_` is only used in the case of *sonic-list* at the moment. In a simple list, `_metadata_` see the (list)[] component for further details
+
+**Disabling this functionality:**
+You can disable data binding if it is not needed by calling `DataBinding.disable()`.