README.md

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