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   class TextField {
  39    public:
  40     TextField();
  41     ~TextField();
  42
  43     // Parses |field_json| and populates |text_field| with the contents.  If any
  44     // of the required elements is missing, returns false and leaves text_field
  45     // in a partially populated state.
  46     static bool ParseTextField(const base::DictionaryValue* field_json,
  47                                TextField* text_field);
  48
  49     const base::string16& text() const { return text_; }
  50     int type() const { return type_; }
  51
  52     bool Equals(const TextField& field) const;
  53
  54    private:
  55     base::string16 text_;
  56     int type_;
  57
  58     FRIEND_TEST_ALL_PREFIXES(SuggestionAnswerTest, DifferentValuesAreUnequal);
  59
  60     // No DISALLOW_COPY_AND_ASSIGN since we depend on the copy constructor in
  61     // SuggestionAnswer::copy and the assigment operator as values in vector.
  62   };
  63
  64   class ImageLine {
  65    public:
  66     ImageLine();
  67     explicit ImageLine(const ImageLine& line);
  68     ~ImageLine();
  69
  70     // Parses |line_json| and populates |image_line| with the contents.  If any
  71     // of the required elements is missing, returns false and leaves text_field
  72     // in a partially populated state.
  73     static bool ParseImageLine(const base::DictionaryValue* line_json,
  74                                ImageLine* image_line);
  75
  76     const TextFields& text_fields() const { return text_fields_; }
  77     const TextField* additional_text() const { return additional_text_.get(); }
  78     const TextField* status_text() const { return status_text_.get(); }
  79     const GURL& image_url() const { return image_url_; }
  80
  81     bool Equals(const ImageLine& line) const;
  82
  83    private:
  84     // Forbid assignment.
  85     ImageLine& operator=(const ImageLine&);
  86
  87     TextFields text_fields_;
  88     scoped_ptr<TextField> additional_text_;
  89     scoped_ptr<TextField> status_text_;
  90     GURL image_url_;
  91
  92     FRIEND_TEST_ALL_PREFIXES(SuggestionAnswerTest, DifferentValuesAreUnequal);
  93   };
  94
  95   SuggestionAnswer();
  96   SuggestionAnswer(const SuggestionAnswer& answer);
  97   ~SuggestionAnswer();
  98
  99   // Parses |answer_json| and returns a SuggestionAnswer containing the
 100   // contents.  If the supplied data is not well formed or is missing required
 101   // elements, returns nullptr instead.
 102   static scoped_ptr<SuggestionAnswer> ParseAnswer(
 103         const base::DictionaryValue* answer_json);
 104
 105   // TODO(jdonnelly): Once something like std::optional<T> is available in base/
 106   // (see discussion at http://goo.gl/zN2GNy) remove this in favor of having
 107   // SuggestResult and AutocompleteMatch use optional<SuggestionAnswer>.
 108   static scoped_ptr<SuggestionAnswer> copy(const SuggestionAnswer* source) {
 109     return make_scoped_ptr(source ? new SuggestionAnswer(*source) : nullptr);
 110   }
 111
 112   const ImageLine& first_line() const { return first_line_; }
 113   const ImageLine& second_line() const { return second_line_; }
 114
 115   // Answer type accessors.  Valid types are non-negative and defined at
 116   // https://goto.google.com/visual_element_configuration.
 117   int type() const { return type_; }
 118   void set_type(int type) { type_ = type; }
 119
 120   bool Equals(const SuggestionAnswer& answer) const;
 121
 122   // Retrieves any image URLs appearing in this answer and adds them to |urls|.
 123   void AddImageURLsTo(URLs* urls) const;
 124
 125  private:
 126   // Forbid assignment.
 127   SuggestionAnswer& operator=(const SuggestionAnswer&);
 128
 129   ImageLine first_line_;
 130   ImageLine second_line_;
 131   int type_;
 132
 133   FRIEND_TEST_ALL_PREFIXES(SuggestionAnswerTest, DifferentValuesAreUnequal);
 134 };
 135
 136 #endif  // COMPONENTS_OMNIBOX_SUGGESTION_ANSWER_H_