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
127