Skip to content
This repository
Newer
Older
100644 173 lines (110 sloc) 6.148 kb
083a03b8 »
2012-06-10 Minor changes to the documentation
1 # Getting started with SilverStripe's Content Personalization Module (SSCP)
2
3
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
4 ## Notice
5
083a03b8 »
2012-06-10 Minor changes to the documentation
6 Please note that this module is **under development** and **not suitable for use in production**!
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
7
083a03b8 »
2012-06-10 Minor changes to the documentation
8 * There will be a lot of changes.
9 * We may change the database structure.
10 * It is not feature complete.
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
11
12
083a03b8 »
2012-06-10 Minor changes to the documentation
13 ## Installation
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
14
083a03b8 »
2012-06-10 Minor changes to the documentation
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.
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
20
21
22 ## Configuration
23
083a03b8 »
2012-06-10 Minor changes to the documentation
24 You must configure the module before you can start using it.
25 Copy the two configuration files
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
26
27 sscp/_config/audiencetype.yml.sample
28 sscp/_config/apikey.yml.sample
5c03948a »
2012-08-04 MINOR Added description about default location to getting started guide.
29 sscp/_config/default_location.yml.sample
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
30
31 to
32
33 mysite/_config/audiencetype.yml
34 mysite/_config/apikey.yml
5c03948a »
2012-08-04 MINOR Added description about default location to getting started guide.
35 mysite/_config/default_location.yml
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
36
37
083a03b8 »
2012-06-10 Minor changes to the documentation
38 ### APIKeys (mysite/_config/apikey.yml)
39
40 You need to some set the following API keys to use the respective thirdparty services:
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
41
083a03b8 »
2012-06-10 Minor changes to the documentation
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).
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
44
45
083a03b8 »
2012-06-10 Minor changes to the documentation
46 ### AudienceTypes (mysite/_config/audiencetype.yml)
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
47
f1be4a08 »
2012-06-12 MINOR Added explanation of audience types.
48 The module personalizes content based on [AudienceTypes](https://github.com/yukiawano/sscpmodule/blob/master/docs/en/topics/audience-type.md).
bf88a2f4 »
2012-06-13 MINOR Added Available Conditions page.
49 An AudienceType is a collection of [conditions](https://github.com/yukiawano/sscpmodule/blob/master/docs/en/conditions.md).
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
50
083a03b8 »
2012-06-10 Minor changes to the documentation
51 You can define AudienceTypes in YAML like this:
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
52
083a03b8 »
2012-06-10 Minor changes to the documentation
53 ```
367bb0c5 »
2012-06-17 MINOR Changed top level name from AudienceType to AudienceTypeDefinit…
54 AudienceTypeDefinition:
5eaa4596 »
2012-06-09 MINOR Changed documents accoring to the previous syntax change.
55 MatchingRule: InclusiveOR
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
56 AudienceTypes:
5eaa4596 »
2012-06-09 MINOR Changed documents accoring to the previous syntax change.
57 NewComer:
58 NewComer: true
59 JapanLinuxUser:
60 Location: Japan
61 Device: Linux
62 Japanese:
63 Location: Japan
9b7f7072 »
2012-06-08 BUGFIX Fixed wrong code block tag in getting_started.md
64 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
65
083a03b8 »
2012-06-10 Minor changes to the documentation
66 After you have changed audience types you must access ``/dev/build/?flush=all`` to reload the configuration.
67
5c03948a »
2012-08-04 MINOR Added description about default location to getting started guide.
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 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
84
85 ## Tutorial
86
083a03b8 »
2012-06-10 Minor changes to the documentation
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.
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
89
90
083a03b8 »
2012-06-10 Minor changes to the documentation
91 ### 1. Add Personalized Content
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
92
083a03b8 »
2012-06-10 Minor changes to the documentation
93 A BlockHolder is a place holder for content personalization and looks like this in the template:
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
94
9b7f7072 »
2012-06-08 BUGFIX Fixed wrong code block tag in getting_started.md
95 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
96 $PersonalizedContent('WelcomeBlock')
9b7f7072 »
2012-06-08 BUGFIX Fixed wrong code block tag in getting_started.md
97 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
98
083a03b8 »
2012-06-10 Minor changes to the documentation
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.
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
101
083a03b8 »
2012-06-10 Minor changes to the documentation
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:
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
104
083a03b8 »
2012-06-10 Minor changes to the documentation
105 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
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>
9b7f7072 »
2012-06-08 BUGFIX Fixed wrong code block tag in getting_started.md
123 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
124
083a03b8 »
2012-06-10 Minor changes to the documentation
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
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
165 ### 6. Congratulations
166
083a03b8 »
2012-06-10 Minor changes to the documentation
167 Now when you access the site for the first time, you will get a welcome message.
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
168
169 And when you access the site again, you will get welcome-back message.
170
083a03b8 »
2012-06-10 Minor changes to the documentation
171 If you want to see welcome message again, delete the cookie of this site or use private browsing mode.
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
172
083a03b8 »
2012-06-10 Minor changes to the documentation
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.