HOWTO.md

   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>&nbsp;</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>&nbsp;</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.