HOWTO.html

   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>&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>