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