aboutsummaryrefslogtreecommitdiffstats
path: root/doc/comanche.bb
blob: 4b198d65721246cc1a636cc3a66649cb8881d73f (plain) (blame)
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
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
[b]Comanche Page Description Language[/b]

Comanche is a markup language similar to bbcode with which to create elaborate and complex web pages by assembling them from a series of components - some of which are pre-built and others which can be defined on the fly. Comanche uses a Page Decription Language to create these pages.

Comanche primarily chooses what content will appear in various regions of the page. The various regions have names and these names can change depending on what layout template you choose.

[b]Page Templates[/b]
Currently there are five layout templates, unless your site provides additional layouts.

[code]
	[b]default[/b]
	The default template defines a "nav" region across the top, "aside" as a fixed width sidebar, 
	"content" for the main content region, and "footer" for a page footer.


	[b]full[/b]
	The full template defines the same as the default template with the exception that there is no "aside" region.


	[b]choklet[/b]
	The choklet template provides a number of fluid layout styles which can be specified by flavour:

			(default flavour) - a two column layout similar to the "default" template, but more fluid
            bannertwo - a two column layout with a banner region, compatible with the "default" template on small displays
			three - three column layout (adds a "right_aside" region to the default template)
			edgestwo - two column layout with fixed side margins
			edgesthree - three column layout with fixed side margins
			full - three column layout with fixed side margins and adds a "header" region beneath the navigation bar

	[b]redable[/b] (sic)
	A template for reading longer texts full screen (so without navigation bar). Three columns: aside, content and right_aside.
	For maximum readability it is advised to only use the middle content column.

	[b]zen[/b]
	Gives you the freedom to do everything yourself. Just a blank page with a content region.

[/code]

To choose a layout template, use the 'template' tag.

[code]
	[template]full[/template]

[/code]

To choose the "choklet" template with the "three" flavour:

[code]
	[template=three]choklet[/template]

[/code]

The default template will be used if no other template is specified. The template can use any names it desires for content regions. You will be using 'region' tags to decide what content to place in the respective regions.

Three "macros" have been defined for your use.
[code]
	$htmlhead - replaced with the site head content.
	$nav - replaced with the site navigation bar content.
	$content - replaced with the main page content.

[/code]

By default, $nav is placed in the "nav" page region and $content is placed in the "content" region. You only need to use these macros if you wish to re-arrange where these items appear, either to change the order or to move them to other regions.


To select a theme for your page, use the 'theme' tag.
[code]
	[theme]suckerberg[/theme]

[/code]
This will select the theme named "suckerberg". By default your channel's preferred theme will be used.

[code]
	[theme=passion]suckerberg[/theme]

[/code]
This will select the theme named "suckerberg" and select the "passion" schema (theme variant). Alternatively it may be possible to use a condensed theme notation for this. 

[code]
	[theme]suckerberg:passion[/theme]

[/code]

The condensed notation isn't part of Comanche itself but is recognised by $Projectname platform as a theme specifier.

[b]Regions[/b]
Each region has a name, as noted above. You will specify the region of interest using a 'region' tag, which includes the name. Any content you wish placed in this region should be placed between the opening region tag and the closing tag.

[code]
	[region=htmlhead]....content goes here....[/region]
	[region=aside]....content goes here....[/region]
	[region=nav]....content goes here....[/region]
	[region=content]....content goes here....[/region]

[/code]

[b]CSS and Javascript[/b]
We have the possibility to include javascript and css libraries in the htmlhead region. At present we make use of jquery (js), bootstrap (css/js) and foundation (css/js).
This will overwrite the selected themes htmlhead.

[code]
	[region=htmlhead]
		[css]bootstrap[/css]
		[js]jquery[/js]
		[js]bootstrap[/js]
	[/region]

[/code]

[b]Menus and Blocks[/b]
Your webpage creation tools allow you to create menus and blocks, in addition to page content. These provide a chunk of existing content to be placed in whatever regions and whatever order you specify. Each of these has a name which you define when the menu or block is created.

[code]
	[menu]mymenu[/menu]

[/code]
This places the menu called "mymenu" at this location on the page, which must be inside a region. 

[code]
	[menu=horizontal]mymenu[/menu]

[/code]
This places the menu called "mymenu" at this location on the page, which must be inside a region. Additionally it applies the "horizontal" class to the menu. "horizontal" is defined in the redbasic theme. It may or may not be available in other themes. 

[code]
	[menu][var=wrap]none[/var]mymenu[/menu]

[/code]
The variable [var=wrap]none[/var] in a block removes the wrapping div element from the menu.

[code]
	[block]contributors[/block]
[/code]
This places a block named "contributors" in this region.

[code]
	[block=someclass]contributors[/block]

[/code]
This places a block named "contributors" in this region. Additionally it applies the "someclass" class to the block. This replaces the default block classes "bblock widget".

[code]
	[block][var=wrap]none[/var]contributors[/block]

[/code]
The variable [var=wrap]none[/var] in a block removes the wrapping div element from the block.

[b]Widgets[/b]
Widgets are executable apps provided by the system which you can place on your page. Some widgets take arguments which allows you to tailor the widget to your purpose. (TODO: list available widgets and arguments). The base system provides

[code]
	profile - widget which duplicates the profile sidebar of your channel page. This widget takes no arguments
	tagcloud - provides a tag cloud of categories
		count - maximum number of category tags to list	

[/code]

Widgets and arguments are specified with the 'widget' and 'var' tags.
[code]
	[widget=recent_visitors][var=count]24[/var][/widget]

[/code]

This loads the "recent_visitors" widget and supplies it with the argument "count" set to "24". 
 
[b]Comments[/b]
The 'comment' tag is used to delimit comments. These comments will not appear on the rendered page.

[code]
	[comment]This is a comment[/comment]

[/code]

[b]Conditional Execution[/b]
You can use an 'if' construct to make decisions. These are currently based on system configuration variable or the current observer.

[code]
	[if $config.system.foo]
		... the configuration variable system.foo evaluates to 'true'.
	[else]
		... the configuration variable system.foo evaluates to 'false'.
 	[/if]

	[if $observer]
		... this content will only be show to authenticated viewers
	[/if]

[/code]

	The 'else' clause is optional. 

	Several tests are supported besides boolean evaluation.

[code]
	[if $config.system.foo == bar]
		... the configuration variable system.foo is equal to the string 'bar'
	[/if]
	[if $config.system.foo != bar]
		... the configuration variable system.foo is not equal to the string 'bar'
	[/if]
	[if $config.system.foo {} bar ]
		... the configuration variable system.foo is a simple array containing a value 'bar'
	[/if]
	[if $config.system.foo {*} bar]
		... the configuration variable system.foo is a simple array containing a key named 'bar'
	[/if]
[/code]

[b]Complex Example[/b]
[code]
	[comment]use an existing page template which provides a banner region plus 3 columns beneath it[/comment]

	[template]3-column-with-header[/template]

	[comment]Use the "darknight" theme[/comment]

	[theme]darkknight[/theme]

	[comment]Use the existing site navigation menu[/comment]

	[region=nav]$nav[/region]

	[region=side]

		[comment]Use my chosen menu and a couple of widgets[/comment]

		[menu]myfavouritemenu[/menu]

		[widget=recent_visitors]
			[var=count]24[/var]
			[var=names_only]1[/var]
		[/widget]

		[widget=tagcloud][/widget]
		[block]donate[/block]

	[/region]



	[region=middle]

		[comment]Show the normal page content[/comment]

		$content

	[/region]



	[region=right]

		[comment]Show my condensed channel "wall" feed and allow interaction if the observer is allowed to interact[/comment]

		[widget]channel[/widget]

	[/region]

[/code]

#include doc/macros/main_footer.bb;