Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 173 lines (110 sloc) 6.148 kb
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
1 # Getting started with SilverStripe's Content Personalization Module (SSCP)
2
3
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
4 ## Notice
5
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
6 Please note that this module is **under development** and **not suitable for use in production**!
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
7
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
8 * There will be a lot of changes.
9 * We may change the database structure.
10 * It is not feature complete.
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
11
12
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
13 ## Installation
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
14
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
15 To install this module:
16
17 1. Either clone the code from the GitHub repository with ``git clone https://github.com/yukiawano/sscpmodule.git`` or download it at [https://github.com/yukiawano/sscpmodule/downloads](https://github.com/yukiawano/sscpmodule/downloads).
18 2. Add the folder to your SilverStripe installation and rename it to ``sscp``.
19 3. Access ``/dev/build/?flush=all`` to install the module.
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
20
21
22 ## Configuration
23
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
24 You must configure the module before you can start using it.
25 Copy the two configuration files
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
26
27 sscp/_config/audiencetype.yml.sample
28 sscp/_config/apikey.yml.sample
5c03948 Yuki Awano MINOR Added description about default location to getting started guide.
authored
29 sscp/_config/default_location.yml.sample
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
30
31 to
32
33 mysite/_config/audiencetype.yml
34 mysite/_config/apikey.yml
5c03948 Yuki Awano MINOR Added description about default location to getting started guide.
authored
35 mysite/_config/default_location.yml
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
36
37
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
38 ### APIKeys (mysite/_config/apikey.yml)
39
40 You need to some set the following API keys to use the respective thirdparty services:
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
41
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
42 * **IP-base geo-location:** We are using IPInfoDB for which you can get a free key at
43 [http://ipinfodb.com/register.php](http://ipinfodb.com/register.php).
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
44
45
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
46 ### AudienceTypes (mysite/_config/audiencetype.yml)
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
47
f1be4a0 Yuki Awano MINOR Added explanation of audience types.
authored
48 The module personalizes content based on [AudienceTypes](https://github.com/yukiawano/sscpmodule/blob/master/docs/en/topics/audience-type.md).
bf88a2f Yuki Awano MINOR Added Available Conditions page.
authored
49 An AudienceType is a collection of [conditions](https://github.com/yukiawano/sscpmodule/blob/master/docs/en/conditions.md).
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
50
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
51 You can define AudienceTypes in YAML like this:
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
52
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
53 ```
367bb0c Yuki Awano MINOR Changed top level name from AudienceType to AudienceTypeDefinition...
authored
54 AudienceTypeDefinition:
5eaa459 Yuki Awano MINOR Changed documents accoring to the previous syntax change.
authored
55 MatchingRule: InclusiveOR
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
56 AudienceTypes:
5eaa459 Yuki Awano MINOR Changed documents accoring to the previous syntax change.
authored
57 NewComer:
58 NewComer: true
59 JapanLinuxUser:
60 Location: Japan
61 Device: Linux
62 Japanese:
63 Location: Japan
9b7f707 Yuki Awano BUGFIX Fixed wrong code block tag in getting_started.md
authored
64 ```
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
65
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
66 After you have changed audience types you must access ``/dev/build/?flush=all`` to reload the configuration.
67
5c03948 Yuki Awano MINOR Added description about default location to getting started guide.
authored
68 ## Default Location (mysite/_config/default_location.yml)
69
70 To render the page faster, we getting location of a visitor in background with javascript.
71 Then our module uses default location as the location of new comer.
72
73 You can define default location in YAML like this:
74
75 ```
76 DefaultLocation:
77 Location:
78 Lon: 35.011642
79 Lat: 135.768011
80 Country: Japan
81 Region: Kinki
82 City: Kyoto
83 ```
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
84
85 ## Tutorial
86
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
87 In this tutorial we will create a customized block, which shows a welcome message for first time visitors.
88 We will use the audience types from the sample configuration, which already covers this.
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
89
90
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
91 ### 1. Add Personalized Content
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
92
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
93 A BlockHolder is a place holder for content personalization and looks like this in the template:
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
94
9b7f707 Yuki Awano BUGFIX Fixed wrong code block tag in getting_started.md
authored
95 ```
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
96 $PersonalizedContent('WelcomeBlock')
9b7f707 Yuki Awano BUGFIX Fixed wrong code block tag in getting_started.md
authored
97 ```
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
98
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
99 * ``$PersonalizedContent()`` is a method provided by the module.
100 * ``WelcomeBlock`` is a template key, which we will use to load the desired content. You can select any (unique) name you want.
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
101
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
102 Now add the BlockHolder to your template.
103 If you are using the Simple template that is bundled with SS3, ``includes/SideBar.ss`` may be a good place - the second line is the relevant change:
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
104
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
105 ```
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
106 <aside>
107 <div>$PersonalizedContent('WelcomeBlock')</div>
108 <% if Menu(2) %>
109 <nav class="secondary">
110 <h3>
111 <% loop Level(1) %>
112 $Title
113 <% end_loop %>
114 </h3>
115 <ul>
116 <% loop Menu(2) %>
117 <li class="$LinkingMode"><a href="$Link" title="Go to the $Title.XML page"><span class="arrow">&rarr;</span><span class="text">$MenuTitle.XML</span></a></li>
118 <% end_loop %>
119 </ul>
120 </nav>
121 <% end_if %>
122 </aside>
9b7f707 Yuki Awano BUGFIX Fixed wrong code block tag in getting_started.md
authored
123 ```
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
124
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
125
126 ### 2. Create a Snippet
127
128 Snippets are reusable pieces of HTML, which are the different personalizations your page can display.
129
130 For this tutorial we need to create two Snippets, a ``WelcomeSnippet`` and a ``WelcomeBackSnippet``.
131 Log into the CMS and go to the *Personalization* page (``/admin/personalization``) and click on the *Snippet* tab where you can *Add Snippet* add the information shown in the following two screenshots:
132
133 ![Welcome Snippet](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/WelcomeSnippet.png)
134 ![Welcome Back Snippet](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/WelcomeBackSnippet.png)
135
136
137 ### 3. Create a BlockHolder
138
139 BlockHolders are the containers of personalized content. They provide the mapping to the template key from the first step.
140
141 Go to the *Block Holder* tab and click on the *Add Block Holder*. On the following page set the *Template Key* to ``WelcomeBlock`` and add a title and description to give it some context.
142
143 ![Welcome BlockHolder](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/WelcomeBlockHolder.png)
144
145
146 ### 4. Create a Block
147
148 Once we have defined a BlockHolder, we need to add Blocks to it. These Blocks specify the audience type and map to the correct Snippet.
149
150 On the current page, where we have just defined the *Template Key*, go the *Blocks* tab and hit *Add Block*. There, add the information as shown in the following screenshot:
151
152 ![Welcome Block](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/WelcomeBlock.png)
153
154
155 ### 5. Define a DefaultSnippet
156
157 Now a new comer gets the ``WelcomeSnippet`` that we have created, but we also want to show the ``WelcomeBackSnippet`` to returning users.
158 To accomplish that, we set the ``WelcomeBackSnippet`` as the DefaultSnippet, which is shown when there is no block that corresponds to the current session.
159
160 Go back to the details page of the current BlockHolder, check *Show default snippet* and set the ``WelcomeBackSnippet`` as the *Default Snippet*.
161
162 ![Default Snippet](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/DefaultSnippet.png)
163
164
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
165 ### 6. Congratulations
166
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
167 Now when you access the site for the first time, you will get a welcome message.
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
168
169 And when you access the site again, you will get welcome-back message.
170
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
171 If you want to see welcome message again, delete the cookie of this site or use private browsing mode.
f28f807 Yuki Awano ENHANCEMENT Added getting started document.
authored
172
083a03b Philipp Krenn Minor changes to the documentation
xeraa authored
173 ![Welcome Message Is Shown](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/WelcomeMessageIsShown.png)
Something went wrong with that request. Please try again.