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