fix typo
[sview.git] / HOWTO.html
CommitLineData
706611cd
BA
1<!DOCTYPE html><html><head><meta charset="UTF-8"><title>HOWTO</title><style>body{width:80%;margin:15px 10% 15px 10%}</style></head><body>
2
3<h1>sview : tiny PHP web framework</h1>
4
5<h2>0. Installation</h2>
6
7<p>
8 In the following, I assume your website is located under http\[s\]://domain/topic/
9 and is named "website" (adapt to your case). For example, in https://github.com/blog/
10 domain = github.com and topic = blog.
11</p>
12
13<p>
14Get the source code either with <code>git clone</code> command or using a zip archive.
15 Copy all folder contents in the website/ folder :
16</p>
17<pre>website/
18 a/
19 f/
20 site/
21 .htaccess
22 common.php
23 defaults.php
24 index.php
25 s.php</pre>
26<ul>
27 <li><b>a/</b> (for "assets") is the folder for CSS files, images and javascript codes.
28 I like to put them respectively in css/, img/ and js/ folders, but the choice is yours.</li>
29 <li><b>f/</b> (for "files") is the folder for any downloadable (or browsable) file you may upload.</li>
30 <li><b>site/</b> is the main folder containing all your website pages. Three are already there :
31 <ul>
32 <li><i>404.php</i> : the 404 error page;</li>
33 <li><i>dl.php</i> : a script to download binary files;</li>
34 <li><i>home.php</i> : the specifications for the welcome page.</li>
35 </ul></li>
36 <li><b>.htaccess</b> : its main job consists in routing everything that is not a resource
37 to the index.php file.</li>
38 <li><b>common.php</b> contains shared variables and functions to be used by at least two different pages.</li>
39 <li><b>defaults.php</b> defines default variables for any web page, like the title or javascripts block.</li>
40 <li><b>index.php</b> contains your website template, which is rendered for any web page
41 (and filled with specific values defined in pages under site/ folder; anything can be customized).</li>
42 <li><b>s.php</b> consists in the framework code, loaded at the beginning of index.php.</li>
43</ul>
44
45<p>
46 Now (online), in the .htaccess file, change the line <code>RewriteBase /</code> to <code>RewriteBase /topic</code>.
47</p>
48
49<h2>1. Set default contents</h2>
50
51<span>Edit the file defaults.php with</span>
52<ul>
53 <li>A global title to your website; this title can later be mixed with a more specific
54 page-based title, or be replaced.</li>
55 <li>A list of references to CSS style sheets and pre-rendering javascript, like
56 <code>&lt;link rel="stylesheet" href="http://cran.r-project.org/R.css"/&gt;</code>.
57 We will see later how to refer to local style sheets (under a/css).</li>
58 <li>Some javascript code which will be loaded by default after every page loads
59 (e.g. <a href="http://jquery.com/">jquery</a>).</li>
60</ul>
61
62<p>
63 Each variable name is prepended with "b_" to avoid potential conflicts with your own variables.
64</p>
65
66<h2>2. Complete main pages</h2>
67
68<h3>index.php</h3>
69
70<span>Complete</span>
71<ul>
72 <li>The menu (at commented location)</li>
73 <li>The banner (near the menu, if you want one)</li>
74 <li>The footer (if you don't want one, just drop it).</li>
75</ul>
76
77<p>
78 You can also change the &lt;meta&gt; tags if needed.
79</p>
80
81<h3>site/home.php</h3>
82
83<p>
84 The welcome page. You can choose a title ($s_title) or use the default one
85 (by not specifying anything). Style sheets and javascripts can be customized, ...etc.
86 Any default variable can be used to define a specific variable (prepended with "s_").
87</p>
88
89<h3>site/404.php</h3>
90
91<p>
92 Customize it; it is probably viewed more often than you think ;-)
93</p>
94
95<h2>3. Write all other pages</h2>
96
97<p>
98 All pages are under site/ folder, and you can nest them in any directory tree.
99</p>
100
101<p>
102 <b>Hint</b> : if you don't want to load the main template, just end any site file
103 with a PHP <code>exit</code> directive.
104</p>
105
106<p>
107 Now we will see how to access pages and resources (images, CSS, files, javascript).
108</p>
109
110<hr/>
111
112<h2>How to view a web page ?</h2>
113
114<p>
115 The page at physical location site/some_folder/mypage.php is viewed in the web browser at the URL
116 http\[s\]://domain/topic/website/some_folder/mypage (thanks to URL rewriting defined in
117 the .htaccess file).
118</p>
119
120<p>
121 Any page can be linked internally using the <code>r()</code> PHP function ('r' for "resource"), like in
122 the following : <code>&lt;a href="&lt;?php echo r('some_folder/mypage'); ?&gt;"&gt;</code>. This function determines
123 the nesting level and output the appropriate path.
124</p>
125
126<h2>How to access...</h2>
127
128<p>
129 <i>A CSS style sheet</i> : its path is given by the following PHP function call
130 <code>r('a/css/name_of_the_file.css')</code> from within any site file (assuming you place all CSS files
131 under a/css/. They may be inside a nested folder structure).
132</p>
133
134<p>
135 <i>An image</i> : same as above, with <code>r('a/img/name_of_the_image.xxx')</code>.
136</p>
137
138<p>
139 <i>A javascript file</i> : same as above, with <code>r('a/js/name_of_the_file.js')</code>.
140</p>
141
142<h2>How to give a download link ?</h2>
143
144<p>
145 Just use a regular link pointing to <code>r('dl/?f=name_of_the_file.xxx')</code>, anywhere you want.
146</p>
147
148<hr/>
149
150<h2>Usual workflow</h2>
151
152<p>
153 Just add pages under site/ folder, and potential resources and files under a/ and f/.
154 All other files will not change a lot.
155</p>
156
157</body></html>