1 // Copyright 2016 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_NTP_SNIPPETS_CATEGORY_RANKERS_CATEGORY_RANKER_H_
6 #define COMPONENTS_NTP_SNIPPETS_CATEGORY_RANKERS_CATEGORY_RANKER_H_
7 
8 #include <string>
9 #include <vector>
10 
11 #include "base/time/time.h"
12 #include "components/ntp_snippets/category.h"
13 
14 namespace ntp_snippets {
15 
16 // Orders categories.
17 // The order may be dynamic and change at any time.
18 class CategoryRanker {
19  public:
20   virtual ~CategoryRanker() = default;
21 
22   // Compares two categories. True means that |left| precedes |right|, i.e. it
23   // must be located earlier (above) on the NTP. This method must satisfy
24   // "Compare" contract required by sort algorithms.
25   virtual bool Compare(Category left, Category right) const = 0;
26 
27   // Deletes all history related data between |begin| and |end|. After this
28   // call, the category order may not depend on this history range anymore.
29   virtual void ClearHistory(base::Time begin, base::Time end) = 0;
30 
31   // If |category| has not been added previously, it is added after all already
32   // known categories, otherwise nothing is changed.
33   virtual void AppendCategoryIfNecessary(Category category) = 0;
34 
35   // If |category_to_insert| has not been added previously, it is added before
36   // |anchor|, otherwise nothing is changed.
37   virtual void InsertCategoryBeforeIfNecessary(Category category_to_insert,
38                                                Category anchor) = 0;
39 
40   // If |category_to_insert| has not been added previously, it is added after
41   // |anchor|, otherwise nothing is changed.
42   virtual void InsertCategoryAfterIfNecessary(Category category_to_insert,
43                                               Category anchor) = 0;
44 
45   struct DebugDataItem {
46     std::string label;
47     std::string content;
DebugDataItemDebugDataItem48     DebugDataItem(const std::string& label, const std::string& content)
49         : label(label), content(content) {}
50   };
51 
52   // Returns DebugData in form of pairs of strings (label; content),
53   // e.g. describing internal state or parameter values.
54   virtual std::vector<DebugDataItem> GetDebugData() = 0;
55 
56   // Feedback data from the user to update the ranking.
57 
58   // Called whenever a suggestion is opened by the user.
59   virtual void OnSuggestionOpened(Category category) = 0;
60 
61   // Called whenever a category is dismissed by the user.
62   virtual void OnCategoryDismissed(Category category) = 0;
63 };
64 
65 }  // namespace ntp_snippets
66 
67 #endif  // COMPONENTS_NTP_SNIPPETS_CATEGORY_RANKERS_CATEGORY_RANKER_H_
68