Skip to content
This repository
Newer
Older
100644 155 lines (95 sloc) 5.663 kb
083a03b8 » xeraa
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 » xeraa
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 » xeraa
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 » xeraa
2012-06-10 Minor changes to the documentation
13 ## Installation
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
14
083a03b8 » xeraa
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 » xeraa
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
29
30 to
31
32 mysite/_config/audiencetype.yml
33 mysite/_config/apikey.yml
34
35
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
36 ### APIKeys (mysite/_config/apikey.yml)
37
38 You need to some set the following API keys to use the respective thirdparty services:
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
39
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
40 * **IP-base geo-location:** We are using IPInfoDB for which you can get a free key at
41 [http://ipinfodb.com/register.php](http://ipinfodb.com/register.php).
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
42
43
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
44 ### AudienceTypes (mysite/_config/audiencetype.yml)
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
45
f1be4a08 »
2012-06-12 MINOR Added explanation of audience types.
46 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.
47 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.
48
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
49 You can define AudienceTypes in YAML like this:
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
50
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
51 ```
367bb0c5 »
2012-06-17 MINOR Changed top level name from AudienceType to AudienceTypeDefinit…
52 AudienceTypeDefinition:
5eaa4596 »
2012-06-09 MINOR Changed documents accoring to the previous syntax change.
53 MatchingRule: InclusiveOR
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
54 AudienceTypes:
5eaa4596 »
2012-06-09 MINOR Changed documents accoring to the previous syntax change.
55 NewComer:
56 NewComer: true
57 JapanLinuxUser:
58 Location: Japan
59 Device: Linux
60 Japanese:
61 Location: Japan
9b7f7072 »
2012-06-08 BUGFIX Fixed wrong code block tag in getting_started.md
62 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
63
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
64 After you have changed audience types you must access ``/dev/build/?flush=all`` to reload the configuration.
65
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
66
67 ## Tutorial
68
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
69 In this tutorial we will create a customized block, which shows a welcome message for first time visitors.
70 We will use the audience types from the sample configuration, which already covers this.
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
71
72
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
73 ### 1. Add Personalized Content
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
74
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
75 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.
76
9b7f7072 »
2012-06-08 BUGFIX Fixed wrong code block tag in getting_started.md
77 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
78 $PersonalizedContent('WelcomeBlock')
9b7f7072 »
2012-06-08 BUGFIX Fixed wrong code block tag in getting_started.md
79 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
80
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
81 * ``$PersonalizedContent()`` is a method provided by the module.
82 * ``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.
83
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
84 Now add the BlockHolder to your template.
85 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.
86
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
87 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
88 <aside>
89 <div>$PersonalizedContent('WelcomeBlock')</div>
90 <% if Menu(2) %>
91 <nav class="secondary">
92 <h3>
93 <% loop Level(1) %>
94 $Title
95 <% end_loop %>
96 </h3>
97 <ul>
98 <% loop Menu(2) %>
99 <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>
100 <% end_loop %>
101 </ul>
102 </nav>
103 <% end_if %>
104 </aside>
9b7f7072 »
2012-06-08 BUGFIX Fixed wrong code block tag in getting_started.md
105 ```
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
106
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
107
108 ### 2. Create a Snippet
109
110 Snippets are reusable pieces of HTML, which are the different personalizations your page can display.
111
112 For this tutorial we need to create two Snippets, a ``WelcomeSnippet`` and a ``WelcomeBackSnippet``.
113 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:
114
115 ![Welcome Snippet](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/WelcomeSnippet.png)
116 ![Welcome Back Snippet](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/WelcomeBackSnippet.png)
117
118
119 ### 3. Create a BlockHolder
120
121 BlockHolders are the containers of personalized content. They provide the mapping to the template key from the first step.
122
123 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.
124
125 ![Welcome BlockHolder](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/WelcomeBlockHolder.png)
126
127
128 ### 4. Create a Block
129
130 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.
131
132 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:
133
134 ![Welcome Block](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/WelcomeBlock.png)
135
136
137 ### 5. Define a DefaultSnippet
138
139 Now a new comer gets the ``WelcomeSnippet`` that we have created, but we also want to show the ``WelcomeBackSnippet`` to returning users.
140 To accomplish that, we set the ``WelcomeBackSnippet`` as the DefaultSnippet, which is shown when there is no block that corresponds to the current session.
141
142 Go back to the details page of the current BlockHolder, check *Show default snippet* and set the ``WelcomeBackSnippet`` as the *Default Snippet*.
143
144 ![Default Snippet](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/DefaultSnippet.png)
145
146
f28f807e »
2012-06-08 ENHANCEMENT Added getting started document.
147 ### 6. Congratulations
148
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
149 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.
150
151 And when you access the site again, you will get welcome-back message.
152
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
153 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.
154
083a03b8 » xeraa
2012-06-10 Minor changes to the documentation
155 ![Welcome Message Is Shown](https://github.com/yukiawano/sscpmodule/raw/master/docs/img/WelcomeMessageIsShown.png)
Something went wrong with that request. Please try again.