dom/l10n/L10nOverlays.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_dom_l10n_L10nOverlays_h
   8 #define mozilla_dom_l10n_L10nOverlays_h
   9
  10 #include "mozilla/dom/L10nOverlaysBinding.h"
  11 #include "mozilla/dom/LocalizationBinding.h"
  12
  13 class nsINode;
  14
  15 namespace mozilla::dom {
  16
  17 class DocumentFragment;
  18 class Element;
  19
  20 class L10nOverlays {
  21  public:
  22   /**
  23    * Translate an element.
  24    *
  25    * Translate the element's text content and attributes. Some HTML markup is
  26    * allowed in the translation. The element's children with the data-l10n-name
  27    * attribute will be treated as arguments to the translation. If the
  28    * translation defines the same children, their attributes and text contents
  29    * will be used for translating the matching source child.
  30    */
  31   static void TranslateElement(const GlobalObject& aGlobal, Element& aElement,
  32                                const L10nMessage& aTranslation,
  33                                Nullable<nsTArray<L10nOverlaysError>>& aErrors);
  34   static void TranslateElement(Element& aElement,
  35                                const L10nMessage& aTranslation,
  36                                nsTArray<L10nOverlaysError>& aErrors,
  37                                ErrorResult& aRv);
  38
  39  private:
  40   /**
  41    * Create a text node from text content of an Element.
  42    */
  43   static already_AddRefed<nsINode> CreateTextNodeFromTextContent(
  44       Element* aElement, ErrorResult& aRv);
  45
  46   /**
  47    * Transplant localizable attributes of an element to another element.
  48    *
  49    * Any localizable attributes already set on the target element will be
  50    * cleared.
  51    */
  52   static void OverlayAttributes(
  53       const Nullable<Sequence<AttributeNameValue>>& aTranslation,
  54       Element* aToElement, ErrorResult& aRv);
  55   static void OverlayAttributes(Element* aFromElement, Element* aToElement,
  56                                 ErrorResult& aRv);
  57
  58   /**
  59    * Helper to set textContent and localizable attributes on an element.
  60    */
  61   static void ShallowPopulateUsing(Element* aFromElement, Element* aToElement,
  62                                    ErrorResult& aRv);
  63
  64   /**
  65    * Sanitize a child element created by the translation.
  66    *
  67    * Try to find a corresponding child in sourceElement and use it as the base
  68    * for the sanitization. This will preserve functional attributes defined on
  69    * the child element in the source HTML.
  70    */
  71   static already_AddRefed<nsINode> GetNodeForNamedElement(
  72       Element* aSourceElement, Element* aTranslatedChild,
  73       nsTArray<L10nOverlaysError>& aErrors, ErrorResult& aRv);
  74
  75   /**
  76    * Check if element is allowed in the translation.
  77    *
  78    * This method is used by the sanitizer when the translation markup contains
  79    * an element which is not present in the source code.
  80    */
  81   static bool IsElementAllowed(Element* aElement);
  82
  83   /**
  84    * Sanitize an allowed element.
  85    *
  86    * Text-level elements allowed in translations may only use safe attributes
  87    * and will have any nested markup stripped to text content.
  88    */
  89   static already_AddRefed<Element> CreateSanitizedElement(Element* aElement,
  90                                                           ErrorResult& aRv);
  91
  92   /**
  93    * Replace child nodes of an element with child nodes of another element.
  94    *
  95    * The contents of the target element will be cleared and fully replaced with
  96    * sanitized contents of the source element.
  97    */
  98   static void OverlayChildNodes(DocumentFragment* aFromFragment,
  99                                 Element* aToElement,
 100                                 nsTArray<L10nOverlaysError>& aErrors,
 101                                 ErrorResult& aRv);
 102
 103   /**
 104    * A helper used to test if the string contains HTML markup.
 105    */
 106   static bool ContainsMarkup(const nsACString& aStr);
 107 };
 108
 109 }  // namespace mozilla::dom
 110
 111 #endif