README.html

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