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 {
  16 namespace dom {
  17
  18 class DocumentFragment;
  19 class Element;
  20
  21 class L10nOverlays {
  22  public:
  23   /**
  24    * Translate an element.
  25    *
  26    * Translate the element's text content and attributes. Some HTML markup is
  27    * allowed in the translation. The element's children with the data-l10n-name
  28    * attribute will be treated as arguments to the translation. If the
  29    * translation defines the same children, their attributes and text contents
  30    * will be used for translating the matching source child.
  31    */
  32   static void TranslateElement(const GlobalObject& aGlobal, Element& aElement,
  33                                const L10nMessage& aTranslation,
  34                                Nullable<nsTArray<L10nOverlaysError>>& aErrors);
  35   static void TranslateElement(Element& aElement,
  36                                const L10nMessage& aTranslation,
  37                                nsTArray<L10nOverlaysError>& aErrors,
  38                                ErrorResult& aRv);
  39
  40  private:
  41   /**
  42    * Check if attribute is allowed for the given element.
  43    *
  44    * This method is used by the sanitizer when the translation markup contains
  45    * DOM attributes, or when the translation has traits which map to DOM
  46    * attributes.
  47    *
  48    * `aExplicitlyAllowed` can be passed as a list of attributes explicitly
  49    * allowed on this element.
  50    */
  51   static bool IsAttrNameLocalizable(const nsAtom* nameAtom, Element* aElement,
  52                                     nsTArray<nsString>* aExplicitlyAllowed);
  53
  54   /**
  55    * Create a text node from text content of an Element.
  56    */
  57   static already_AddRefed<nsINode> CreateTextNodeFromTextContent(
  58       Element* aElement, ErrorResult& aRv);
  59
  60   /**
  61    * Transplant localizable attributes of an element to another element.
  62    *
  63    * Any localizable attributes already set on the target element will be
  64    * cleared.
  65    */
  66   static void OverlayAttributes(
  67       const Nullable<Sequence<AttributeNameValue>>& aTranslation,
  68       Element* aToElement, ErrorResult& aRv);
  69   static void OverlayAttributes(Element* aFromElement, Element* aToElement,
  70                                 ErrorResult& aRv);
  71
  72   /**
  73    * Helper to set textContent and localizable attributes on an element.
  74    */
  75   static void ShallowPopulateUsing(Element* aFromElement, Element* aToElement,
  76                                    ErrorResult& aRv);
  77
  78   /**
  79    * Sanitize a child element created by the translation.
  80    *
  81    * Try to find a corresponding child in sourceElement and use it as the base
  82    * for the sanitization. This will preserve functional attributes defined on
  83    * the child element in the source HTML.
  84    */
  85   static already_AddRefed<nsINode> GetNodeForNamedElement(
  86       Element* aSourceElement, Element* aTranslatedChild,
  87       nsTArray<L10nOverlaysError>& aErrors, ErrorResult& aRv);
  88
  89   /**
  90    * Check if element is allowed in the translation.
  91    *
  92    * This method is used by the sanitizer when the translation markup contains
  93    * an element which is not present in the source code.
  94    */
  95   static bool IsElementAllowed(Element* aElement);
  96
  97   /**
  98    * Sanitize an allowed element.
  99    *
 100    * Text-level elements allowed in translations may only use safe attributes
 101    * and will have any nested markup stripped to text content.
 102    */
 103   static already_AddRefed<Element> CreateSanitizedElement(Element* aElement,
 104                                                           ErrorResult& aRv);
 105
 106   /**
 107    * Replace child nodes of an element with child nodes of another element.
 108    *
 109    * The contents of the target element will be cleared and fully replaced with
 110    * sanitized contents of the source element.
 111    */
 112   static void OverlayChildNodes(DocumentFragment* aFromFragment,
 113                                 Element* aToElement,
 114                                 nsTArray<L10nOverlaysError>& aErrors,
 115                                 ErrorResult& aRv);
 116
 117   /**
 118    * A helper used to test if the string contains HTML markup.
 119    */
 120   static bool ContainsMarkup(const nsACString& aStr);
 121 };
 122
 123 }  // namespace dom
 124 }  // namespace mozilla
 125
 126 #endif