-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.html
228 lines (138 loc) · 10.9 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html><head><title>happstack-lite tutorial</title><link rel='stylesheet' type='text/css' href='hscolour.css' ></head><body>
<h1>Clckwrks</h1>
<h2>Installing and Testing clckwrks</h2>
<p>There are three cabal project directories:</p>
<p>clckwrks - contains the core clckwrks server code
clckwrks-theme-basic - an example clckwrks theme
clckwrks-dot-com - source for the (future) clckwrks.com website</p>
<p>To run this demo you will also need the follow javascript libraries:</p>
<p>jquery
jquery-ui
json2
jstree</p>
<p>The first two can be installed via apt-get:</p>
<pre><code>$ apt-get install libjs-jquery libjs-jquery-ui
</code></pre>
<p>The last two can be installed by running 'make' it the top-level directory.</p>
<p>You will also need to install the binaries:</p>
<p>HsColour
markdown</p>
<p>These can be installed via:</p>
<pre><code>$ apt-get install markdown HsColour
</code></pre>
<p>The demo clckwrks server can be built statically or with dynamic plugins enabled. </p>
<h3>Static clckwrks-dot-com</h3>
<p>To build the server statically run 'cabal install' in clckwrks, clckwrks-theme-basic, and finally clckwrk-dot-com.</p>
<p>The clckwrks-dot-com is currently configured to be run from the clckwrks-dot-com directory. So to run the server do:</p>
<pre><code>cd clckwrks-dot-com
./dist/build/clckwrks-server/clckwrks-server
</code></pre>
<p>It should print out:</p>
<pre><code>Static Server Started.
</code></pre>
<p>You can then point your browser at: http://localhost:8000/</p>
<h3>Dynamic clckwrks-dot-com</h3>
<p>To use plugins to load the theme file you need only install clckwrks. Then do the following:</p>
<pre><code>cd clckwrks-dot-com
ln -sf ../clckwrks-theme-basic/Theme .
runhaskell Setup clean
runhaskell Setup configure --user -fplugins
runhaskell Setup build
./dist/build/clckwrks-server/clckwrks-server
</code></pre>
<p>It should print out:</p>
<pre><code>Dynamic Server Started.
</code></pre>
<p>Now if you edit Theme.Home and reload the homepage, you should see your changes reflected. It may take a second or two for the changes to appear.</p>
<p>Note that symbolic link is needed due to the plugins-auto not handling include directories very well. So, we create a symlink as a work-around.</p>
<h2>A tour of the web-site</h2>
<p>When you first open the site, there should be a big blue box and under it there are three columns which say, "Invalid PageId x".</p>
<p>Those columns are supposed to show previews of the 2nd, 3rd, and 4th pages. But those pages have not been created yet. </p>
<p>So, click on 'admin' to get to the admin console. (in theory, you need to login first, but that is currently not hooked up).</p>
<p>Next click on 'Create New Page'.</p>
<p>The body of the page is processed usThe code is ing markdown. The syntax for markdown is here:</p>
<p>http://daringfireball.net/projects/markdown/syntax</p>
<p>markdown allows you to insert arbitrary HTML as well. So you can either just write some simple text, or you can go nuts with HTML.</p>
<p>If you check the 'Highlight Haskell code with HsColour' option, then you can use bird-notation (aka, >) and include literate Haskell which will be colored using HsColour.</p>
<p>After you click 'update' you should be taken to a view of the page you just created. Notice that the menu on the left has been updated to include the newly created page.</p>
<p>If you now click 'This title rocks!' you should be taken back to the homepage. You will see that the first column now contains a preview of page 2.</p>
<p>If you click on 'admin' again. And then 'this title rocks'. You can edit the title of the page and change it to 'Home'.</p>
<p>In the admin console there is also an 'Edit Menu' feature. This feature is currently incomplete and does not work. It allows you to interactively create and organize the menu.</p>
<h2>A tour of the code</h2>
<p>Looking at the code, we see it is divided into three packages: clckwrks, clckwrks-theme-basic, and clckwrks-dot-com.</p>
<h3>clckwrks</h3>
<p>A majority of the code lives in clckwrks. As an end-user, you would install this library, but never need to modify the code in it. It contains all the codefor the core features. </p>
<h3>clckwrks-theme-basic</h3>
<p>clckwrks-theme-basic is a theme package. Themes conform to a simple theme API so that you can easily swap out one for another. Themes are designed so that they could be distributed as .tar.gz bundles. Switching to a different theme should not require any code changes. </p>
<p>For the static server, you would just edit the clckwrks-dot-com.cabal and change clckwrks-theme-basic to clckwrks-theme-awesome.</p>
<p>For the dynamic server you currently need to edit <code>clckwrksConfig</code> and change the path to the theme. But ultimately, that is a value that you would change via the admin console. I envision that you would be able to go to the theme store, and one-click install and activate new themes.</p>
<p>A typical clckwrks user may never look inside, create, or edit a theme bundle. They could just use the prepackaged themes from the site.</p>
<p>Theme designers, on the other hand would need to know how to modify the theme files. So, let's look briefly at the structure.</p>
<p>Right now the theme API is simple. The theme should provide the follow modules:
page :: XMLGenT (Clck ClckURL) XML
Theme.Home
Theme.Page</p>
<p>which export a function:</p>
<p>page :: XMLGenT (Clck ClckURL) XML</p>
<p>any assets such as .css, .jpgs, etc should go in the 'data' directory.</p>
<p>Looking at Theme/Page.hs we see that it tries hard to look like a normal HTML template. There is a bit of noise at the top of the file that would be nice to reduce/simplify. </p>
<p>The <code>Clckwrks</code> module exports a ton of stuff so that you do not need a bunch of imports.</p>
<p>Looking at the template we see that it is primarily html, with some simple calls to fill in content such as: <code>getPageTitle</code> and <code>getPageContent</code>. Those functions come from the clckwrks modules such as <code>Page.API</code>. The <code>.API</code> modules are supposed to provide a friendly interface for template designers to use.</p>
<p>The internal URLs use web-routes.</p>
<p>Looking at this template, it seems like it should be easy for template designers to do there thing with out having to have much understanding of Haskell.</p>
<p>Obviously, the big hang-up is the error messages that you can encounter while using HSP. As Niklas mentioned in this thread:</p>
<p>https://groups.google.com/group/haskell-server-pages/browse_thread/thread/1b136c7acb448136</p>
<p>There is a long-term plan for addressing that.</p>
<p>Looking at the Theme.Home file, we see a slightly more advanced template that uses a helper function <code>summaryBox</code>.</p>
<p>Hopefully the themes are simple enough that end users can modify an existing theme with out really having to learn any Haskell.</p>
<h3>clckwrks-plugin-media</h3>
<p>One of the most valuable aspects of Clckwrks is the ability to extend it through the use of plugins. The <code>clckwrks-plugin-media</code> adds a media gallery. You can upload images, including them in post, and (eventually) create galleries and slideshows.</p>
<p>plugins can also hook into the markup engine and add new markup commands. For example, in a post you could write:</p>
<pre><code>Check out this great photo I took: {media|id=1}
</code></pre>
<p>And when the page is rendered, the image with id 1 will automatically be included in the message.</p>
<h3>clckwrks-dot-com</h3>
<p>This is where we tie it all together. There are only two files so far.</p>
<pre><code>Main.hs
PageMapper.hs
</code></pre>
<p><code>Main.hs</code> is a bit scary looking due to the <code>CPP</code> code to select between static and dynamic mode. But there is really not much code there. Basically we create a <code>ClckwrksConfig</code> and then call <code>simpleClckwrks</code> to start the server.</p>
<p>The static code path just imports the <code>PageMapper.hs</code> directly and calls <code>pageMapper</code>. The dynamic code path imports that symbol via <code>withMonadIOFile</code>.</p>
<p>It would be nice to hide some of that ugliness away because it is pretty much boiler-plate. The tricky part is that we don't want to link against plugins-auto at all when building the static server. The current solution is the obvious way to do that. But, hopefully, not the best.</p>
<p><code>PageMapper.hs</code> just contains a simple function <code>pageMapper</code>. The purpose of this function is to allow you to specify different page templates for specific pages. For example, we see that PageId 1 will use <code>Home.page</code> and all the other pages will use <code>Page.page</code>. </p>
<p>If you comment out the <code>(PageId 1)</code> you will see that the bluebox disappears from the home page. If you are using the dynamic server, you can comment that line out and refresh the page and it should be automatically recompiled/reloaded. If you are using the static server, then you will need to rebuild to see the changes.</p>
<p>If you are using the dynamic server and have created the symlink, you could also edit the <code>Theme.Home</code> or <code>Theme.Page</code> templates and see the changes reflected after a short delay.</p>
<h3>Beyond <code>simpleClckwrks</code></h3>
<p>The <code>simpleClckwrks</code> entry point is good if you just want a simple wordpress-like site. But, <code>clckwrks</code> is also designed to be integrated into a more sophisticated site such as <code>patch-tag.com</code>.</p>
<p>An example is forth-coming. The essence is that you would create a new URL type for your site which embeds <code>ClckURL</code>:</p>
<pre><code>data MySite = C ClckURL
| Home
| Foo
</code></pre>
<p>And then in your routing function you would call <code>routeClck</code> for the <code>ClckURL</code> case.</p>
<h3>clckwrks-cli</h3>
<p>The <code>clckwrks-cli</code> app provides a command-line interface which communications with a running clckwrks app to perform various administrative features. Right now the only feature it has is the ability to make UserId 1 an Administrator. </p>
<h2>TODO</h2>
<p>There is clearly a bunch of stuff left to do including:</p>
<ul>
<li>requiring authentication for the admin console</li>
<li>adding an image gallery (code partial exists but needs to be integrated)</li>
<li>adding JSON import/export for database</li>
<li>integrate comment module</li>
<li>add RSS feed / bloggy-stuff</li>
<li>tags, searching, etc / CRM</li>
<li>menu editor</li>
</ul>
<p>And then there are a bunch of add-on modules that would be great to have such as:</p>
<ul>
<li>mailing list</li>
<li>web-store</li>
<li>paypal</li>
<li>social media integration</li>
<li>members-only content</li>
<li>post scheduling (aka, write a bunch of posts now, but have them published automatically on a schedule)</li>
<li>and more!</li>
</ul>
</body></html>