Skip to content
Newer
Older
100644 155 lines (95 sloc) 5.36 KB
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 10, 2012
1 # Getting started with SilverStripe's Content Personalization Module (SSCP)
2
3
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
4 ## Notice
5
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
6 Please note that this module is **under development** and **not suitable for use in production**!
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
7
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
8 * There will be a lot of changes.
9 * We may change the database structure.
10 * It is not feature complete.
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
11
12
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
13 ## Installation
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
14
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
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 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
20
21
22 ## Configuration
23
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
24 You must configure the module before you can start using it.
25 Copy the two configuration files
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
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
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
36 ### APIKeys (mysite/_config/apikey.yml)
37
38 You need to some set the following API keys to use the respective thirdparty services:
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
39
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
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).
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
42
43
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
44 ### AudienceTypes (mysite/_config/audiencetype.yml)
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
45
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
46 The module personalizes content based on AudienceTypes.
47 An AudienceType is a collection of conditions.
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
48
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
49 You can define AudienceTypes in YAML like this:
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
50
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
51 ```
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
52 AudienceType:
5eaa459 @yukiawano MINOR Changed documents accoring to the previous syntax change.
authored Jun 9, 2012
53 MatchingRule: InclusiveOR
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
54 AudienceTypes:
5eaa459 @yukiawano MINOR Changed documents accoring to the previous syntax change.
authored Jun 8, 2012
55 NewComer:
56 NewComer: true
57 JapanLinuxUser:
58 Location: Japan
59 Device: Linux
60 Japanese:
61 Location: Japan
9b7f707 @yukiawano BUGFIX Fixed wrong code block tag in getting_started.md
authored Jun 8, 2012
62 ```
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
63
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
64 After you have changed audience types you must access ``/dev/build/?flush=all`` to reload the configuration.
65
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
66
67 ## Tutorial
68
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
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.
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
71
72
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
73 ### 1. Add Personalized Content
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
74
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
75 A BlockHolder is a place holder for content personalization and looks like this in the template:
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
76
9b7f707 @yukiawano BUGFIX Fixed wrong code block tag in getting_started.md
authored Jun 8, 2012
77 ```
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
78 $PersonalizedContent('WelcomeBlock')
9b7f707 @yukiawano BUGFIX Fixed wrong code block tag in getting_started.md
authored Jun 8, 2012
79 ```
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
80
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
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.
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
83
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
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:
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
86
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
87 ```
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
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>
9b7f707 @yukiawano BUGFIX Fixed wrong code block tag in getting_started.md
authored Jun 8, 2012
105 ```
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
106
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
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
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
147 ### 6. Congratulations
148
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
149 Now when you access the site for the first time, you will get a welcome message.
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
150
151 And when you access the site again, you will get welcome-back message.
152
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
153 If you want to see welcome message again, delete the cookie of this site or use private browsing mode.
f28f807 @yukiawano ENHANCEMENT Added getting started document.
authored Jun 8, 2012
154
083a03b @xeraa Minor changes to the documentation
xeraa authored Jun 9, 2012
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.