[sview.git] / HOWTO.md

## 0. Installation

In the following, I assume your website is located under http\[s\]://domain/topic/ 
and is named "website" (adapt to your case). For example, in https://github.com/blog/ 
domain = github.com and topic = blog.

Get the source code either with `git clone` command or using a zip archive. 
Copy all folder contents in the website/ folder : 
<pre>website/
    a/
    f/
    site/
    .htaccess
    common.php
    defaults.php
    index.php
    s.php
</pre>
- **a/** (for "assets") is the folder for CSS files, images and javascript codes. 
I like to put them respectively in css/, img/ and js/ folders, but the choice is yours.
- **f/** (for "files") is the folder for any downloadable (or browsable) file you may upload. 
- **site/** is the main folder containing all your website pages. Three are already there :
  - **404.php** : the 404 error page;
  - **dl.php** : a script to download binary files;
  - **home.php** : the specifications for the welcome page.
- **.htaccess** : its main job consists in routing everything that is not a resource 
to the index.php file. 
- **common.php** contains shared variables and functions to be used by at least two different pages.
- **defaults.php** defines default variables for any web page, like the title or javascripts block.
- **index.php** contains your website template, which is rendered for any web page 
(and filled with specific values defined in pages under site/ folder; anything can be customized).
- **s.php** consists in the framework code, loaded at the beginning of index.php.

Now (online), in the .htaccess file, change the line `RewriteBase /` to `RewriteBase /topic`.

## 1. Set default contents

Edit the file defaults.php with
- A global title to your website; this title can later be mixed with a more specific 
page-based title, or be replaced.
- A list of references to CSS style sheets and pre-rendering javascript, like 
`<link rel="stylesheet" href="http://cran.r-project.org/R.css"/>`. 
We will see later how to refer to local style sheets (under a/css).
- Some javascript code which will be loaded by default after every page loads
(e.g. [jquery](http://jquery.com/)).

Each variable name is prepended with "b\_" to avoid potential conflicts with your own variables.

## 2. Complete main pages

### index.php

Complete
- The menu (at commented location)
- The banner (near the menu, if you want one)
- The footer (if you don't want one, just drop it).

You can also change the \<meta\> tags if needed.

### site/home.php

The welcome page. You can choose a title ($s\_title) or use the default one 
(by not specifying anything). Style sheets and javascripts can be customized, ...etc. 
Any default variable can be used to define a specific variable (prepended with "s\_"). 

### site/404.php

Customize it; it is probably viewed more often than you think ;-)

## 3. Write all other pages

All pages are under site/ folder, and you can nest them in any directory tree.

**Hint** : if you don't want to load the main template, just end any site file 
with a PHP `exit` directive.

Now we will see how to access pages and resources (images, CSS, files, javascript).

<p>&nbsp;</p>
--------------------------------------------------

## How to view a web page ?

The page at physical location site/some\_folder/mypage.php is viewed in the web browser at the URL 
http\[s\]://domain/topic/website/some\_folder/mypage (thanks to URL rewriting defined in 
the .htaccess file). 

Any page can be linked internally using the `r()` PHP function ('r' for "resource"), like in 
the following : `<a href="<?php echo r('some_folder/mypage'); ?>">'`. This function determines 
the nesting level and output the appropriate path.

## How to access...

*A CSS style sheet* : its path is given by the following PHP function call 
`r('a/css/name_of_the_file.css')` from within any site file (assuming you place all CSS files 
under a/css/. They may be inside a nested folder structure).

*An image* : same as above, with `r('a/img/name_of_the_image.xxx')`.

*A javascript file* : same as above, with `r('a/js/name_of_the_file.js')`.

## How to give a download link ?

Just use a regular link pointing to `r('dl/?f=name_of_the_file.xxx')`, anywhere you want.

<p>&nbsp;</p>
--------------------------------------------------

## Usual workflow

Just add pages under site/ folder, and potential resources and files under a/ and f/. 
All other files will not change a lot.
Commit	Line	Data
	1	## 0. Installation
	2
	3	In the following, I assume your website is located under http\[s\]://domain/topic/
	4	and is named "website" (adapt to your case). For example, in https://github.com/blog/
	5	domain = github.com and topic = blog.
	6
	7	Get the source code either with `git clone` command or using a zip archive.
	8	Copy 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.
	20	I 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
	27	to 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
	34	Now (online), in the .htaccess file, change the line `RewriteBase /` to `RewriteBase /topic`.
	35
	36	## 1. Set default contents
	37
	38	Edit the file defaults.php with
	39	- A global title to your website; this title can later be mixed with a more specific
	40	page-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"/>`.
	43	We 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
	47	Each 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
	53	Complete
	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
	58	You can also change the \<meta\> tags if needed.
	59
	60	### site/home.php
	61
	62	The 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.
	64	Any default variable can be used to define a specific variable (prepended with "s\_").
	65
	66	### site/404.php
	67
	68	Customize it; it is probably viewed more often than you think ;-)
	69
	70	## 3. Write all other pages
	71
	72	All 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
	75	with a PHP `exit` directive.
	76
	77	Now we will see how to access pages and resources (images, CSS, files, javascript).
	78
	79	<p> </p>
	80	--------------------------------------------------
	81
	82	## How to view a web page ?
	83
	84	The page at physical location site/some\_folder/mypage.php is viewed in the web browser at the URL
	85	http\[s\]://domain/topic/website/some\_folder/mypage (thanks to URL rewriting defined in
	86	the .htaccess file).
	87
	88	Any page can be linked internally using the `r()` PHP function ('r' for "resource"), like in
	89	the following : `<a href="<?php echo r('some_folder/mypage'); ?>">'`. This function determines
	90	the 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
	96	under 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
	104	Just use a regular link pointing to `r('dl/?f=name_of_the_file.xxx')`, anywhere you want.
	105
	106	<p> </p>
	107	--------------------------------------------------
	108
	109	## Usual workflow
	110
	111	Just add pages under site/ folder, and potential resources and files under a/ and f/.
	112	All other files will not change a lot.