[sview.git] / HOWTO.html

<!DOCTYPE html><html><head><meta charset="UTF-8"><title>HOWTO</title><style>body{width:80%;margin:15px 10% 15px 10%}</style></head><body>

<h1>sview : tiny PHP web framework</h1>

<h2>0. Installation</h2>

<p>
	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.
</p>

<p>
Get the source code either with <code>git clone</code> command or using a zip archive. 
	Copy all folder contents in the website/ folder : 
</p>
<pre>website/
    a/
    f/
    site/
    .htaccess
    common.php
    defaults.php
    index.php
    s.php</pre>
<ul>
	<li><b>a/</b> (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.</li>
	<li><b>f/</b> (for "files") is the folder for any downloadable (or browsable) file you may upload.</li>
	<li><b>site/</b> is the main folder containing all your website pages. Three are already there :
 	<ul>
 		<li><i>404.php</i> : the 404 error page;</li>
		<li><i>dl.php</i> : a script to download binary files;</li>
		<li><i>home.php</i> : the specifications for the welcome page.</li>
	</ul></li>
	<li><b>.htaccess</b> : its main job consists in routing everything that is not a resource 
		to the index.php file.</li>
	<li><b>common.php</b> contains shared variables and functions to be used by at least two different pages.</li>
	<li><b>defaults.php</b> defines default variables for any web page, like the title or javascripts block.</li>
	<li><b>index.php</b> 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).</li>
	<li><b>s.php</b> consists in the framework code, loaded at the beginning of index.php.</li>
</ul>

<p>
	Now (online), in the .htaccess file, change the line <code>RewriteBase /</code> to <code>RewriteBase /topic</code>.
</p>

<h2>1. Set default contents</h2>

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

<p>
	Each variable name is prepended with "b_" to avoid potential conflicts with your own variables.
</p>

<h2>2. Complete main pages</h2>

<h3>index.php</h3>

<span>Complete</span>
<ul>
	<li>The menu (at commented location)</li>
	<li>The banner (near the menu, if you want one)</li>
	<li>The footer (if you don't want one, just drop it).</li>
</ul>

<p>
	You can also change the &lt;meta&gt; tags if needed.
</p>

<h3>site/home.php</h3>

<p>
	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_"). 
</p>

<h3>site/404.php</h3>

<p>
	Customize it; it is probably viewed more often than you think ;-)
</p>

<h2>3. Write all other pages</h2>

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

<p>
	<b>Hint</b> : if you don't want to load the main template, just end any site file 
	with a PHP <code>exit</code> directive.
</p>

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

<hr/>

<h2>How to view a web page ?</h2>

<p>
	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). 
</p>

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

<h2>How to access...</h2>

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

<p>
	<i>An image</i> : same as above, with <code>r('a/img/name_of_the_image.xxx')</code>.
</p>

<p>
	<i>A javascript file</i> : same as above, with <code>r('a/js/name_of_the_file.js')</code>.
</p>

<h2>How to give a download link ?</h2>

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

<hr/>

<h2>Usual workflow</h2>

<p>
	Just add pages under site/ folder, and potential resources and files under a/ and f/. 
	All other files will not change a lot.
</p>

</body></html>
Commit	Line	Data
	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>
	14	Get 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><link rel="stylesheet" href="http://cran.r-project.org/R.css"/></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 <meta> 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><a href="<?php echo r('some_folder/mypage'); ?>"></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>