components/omnibox/suggestion_answer.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COMPONENTS_OMNIBOX_SUGGESTION_ANSWER_H_
   6 #define COMPONENTS_OMNIBOX_SUGGESTION_ANSWER_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/gtest_prod_util.h"
  12 #include "base/memory/scoped_ptr.h"
  13 #include "url/gurl.h"
  14
  15 namespace base {
  16 class DictionaryValue;
  17 }
  18
  19 // Structured representation of the JSON payload of a suggestion with an answer.
  20 // An answer has exactly two image lines, so called because they are a
  21 // combination of text and an optional image URL.  Each image line has 1 or more
  22 // text fields, each of which is required to contain a string and an integer
  23 // type.  The text fields are contained in a non-empty vector and two optional
  24 // named properties, referred to as "additional text" and "status text".
  25 //
  26 // When represented in the UI, these elements should be styled and laid out
  27 // according to the specification at https://goto.google.com/ais_api.
  28 //
  29 // Each of the three classes has either an explicit or implicity copy
  30 // constructor to support copying answer values (via SuggestionAnswer::copy) as
  31 // members of SuggestResult and AutocompleteMatch.
  32 class SuggestionAnswer {
  33  public:
  34   class TextField;
  35   typedef std::vector<TextField> TextFields;
  36   typedef std::vector<GURL> URLs;
  37
  38   // These values are named and numbered to match a specification at go/ais_api.
  39   // The values are only used for answer results.
  40   enum TextType {
  41     ANSWER = 1,
  42     HEADLINE = 2,
  43     TOP_ALIGNED = 3,
  44     DESCRIPTION = 4,
  45     DESCRIPTION_NEGATIVE = 5,
  46     DESCRIPTION_POSITIVE = 6,
  47     MORE_INFO = 7,
  48     SUGGESTION = 8,
  49     SUGGESTION_POSITIVE = 9,
  50     SUGGESTION_NEGATIVE = 10,
  51     SUGGESTION_LINK = 11,
  52     STATUS = 12,
  53     PERSONALIZED_SUGGESTION = 13,
  54   };
  55
  56   class TextField {
  57    public:
  58     TextField();
  59     ~TextField();
  60
  61     // Parses |field_json| and populates |text_field| with the contents.  If any
  62     // of the required elements is missing, returns false and leaves text_field
  63     // in a partially populated state.
  64     static bool ParseTextField(const base::DictionaryValue* field_json,
  65                                TextField* text_field);
  66
  67     const base::string16& text() const { return text_; }
  68     int type() const { return type_; }
  69
  70     bool Equals(const TextField& field) const;
  71
  72    private:
  73     base::string16 text_;
  74     int type_;
  75
  76     FRIEND_TEST_ALL_PREFIXES(SuggestionAnswerTest, DifferentValuesAreUnequal);
  77
  78     // No DISALLOW_COPY_AND_ASSIGN since we depend on the copy constructor in
  79     // SuggestionAnswer::copy and the assigment operator as values in vector.
  80   };
  81
  82   class ImageLine {
  83    public:
  84     ImageLine();
  85     explicit ImageLine(const ImageLine& line);
  86     ~ImageLine();
  87
  88     // Parses |line_json| and populates |image_line| with the contents.  If any
  89     // of the required elements is missing, returns false and leaves text_field
  90     // in a partially populated state.
  91     static bool ParseImageLine(const base::DictionaryValue* line_json,
  92                                ImageLine* image_line);
  93
  94     const TextFields& text_fields() const { return text_fields_; }
  95     const TextField* additional_text() const { return additional_text_.get(); }
  96     const TextField* status_text() const { return status_text_.get(); }
  97     const GURL& image_url() const { return image_url_; }
  98
  99     bool Equals(const ImageLine& line) const;
 100
 101    private:
 102     // Forbid assignment.
 103     ImageLine& operator=(const ImageLine&);
 104
 105     TextFields text_fields_;
 106     scoped_ptr<TextField> additional_text_;
 107     scoped_ptr<TextField> status_text_;
 108     GURL image_url_;
 109
 110     FRIEND_TEST_ALL_PREFIXES(SuggestionAnswerTest, DifferentValuesAreUnequal);
 111   };
 112
 113   SuggestionAnswer();
 114   SuggestionAnswer(const SuggestionAnswer& answer);
 115   ~SuggestionAnswer();
 116
 117   // Parses |answer_json| and returns a SuggestionAnswer containing the
 118   // contents.  If the supplied data is not well formed or is missing required
 119   // elements, returns nullptr instead.
 120   static scoped_ptr<SuggestionAnswer> ParseAnswer(
 121         const base::DictionaryValue* answer_json);
 122
 123   // TODO(jdonnelly): Once something like std::optional<T> is available in base/
 124   // (see discussion at http://goo.gl/zN2GNy) remove this in favor of having
 125   // SuggestResult and AutocompleteMatch use optional<SuggestionAnswer>.
 126   static scoped_ptr<SuggestionAnswer> copy(const SuggestionAnswer* source) {
 127     return make_scoped_ptr(source ? new SuggestionAnswer(*source) : nullptr);
 128   }
 129
 130   const ImageLine& first_line() const { return first_line_; }
 131   const ImageLine& second_line() const { return second_line_; }
 132
 133   // Answer type accessors.  Valid types are non-negative and defined at
 134   // https://goto.google.com/visual_element_configuration.
 135   int type() const { return type_; }
 136   void set_type(int type) { type_ = type; }
 137
 138   bool Equals(const SuggestionAnswer& answer) const;
 139
 140   // Retrieves any image URLs appearing in this answer and adds them to |urls|.
 141   void AddImageURLsTo(URLs* urls) const;
 142
 143  private:
 144   // Forbid assignment.
 145   SuggestionAnswer& operator=(const SuggestionAnswer&);
 146
 147   ImageLine first_line_;
 148   ImageLine second_line_;
 149   int type_;
 150
 151   FRIEND_TEST_ALL_PREFIXES(SuggestionAnswerTest, DifferentValuesAreUnequal);
 152 };
 153
 154 #endif  // COMPONENTS_OMNIBOX_SUGGESTION_ANSWER_H_