• Clone Kit
• how-to
• admin
• about

how-to

Install

1. Unpack the distribution at the root level of a web site.

   • This code is built under the assumption that it will serve the root of a domain, for example all of http://example.com.
   • Just kicking the tires? Use a web server on your local machine, and have localhost be the domain name. Your httpd.conf might look like:

     
     DocumentRoot "/Users/lucas/proj/clonekit/www"
     <Directory "/Users/lucas/proj/clonekit/www">
       Options Indexes Includes FollowSymLinks MultiViews
       AllowOverride All
       Order allow,deny
       Allow from all
     </Directory>
     

2. Open your browser to the URL of the server you just set up.
3. If you see CloneKit under construction, you need to enable mod_rewrite. Follow the instructions on that page.

Tutorial

1. Open /virtual/config.php and reset the site name, site tagline, and administrator password.
2. Mint a new URL using one of the template URI handlers:
   1. Copy /virtual/templates/helloworld.php to /virtual/page/
   2. Add a menu item for /helloworld by modifying $SITE_MENUS in /virtual/config.php
   3. Hit the "hello world" menu item.
3. Make your first form:
   1. Copy /virtual/templates/form.php to /virtual/page/helloworld.php
   2. Change that code so that the form prints out the sum of user-submitted arguments.
   3. Take a tour of available functions in /virtual/lib and apply them to the form arguments, for example to verify user input.
4. Modify the global HTML template:
   1. Open /virtual/lib/html.php and go to the html_trimmings function.
   2. Change the site footer so that you get the credit for your site instead of me.

Start for real

The page you are reading now is part of CloneKit. Before you start your app you need to clean out this crud.

1. Delete the links you don't want in the global menu. (see $SITE_MENUS in config.php)
2. Delete any corresponding .php files in /virtual/page
3. Delete your tutorial files.

Minting URLs

To mint a new URL on your website like http://example.com/foo, create a PHP file with the same base name (like foo) in /virtual/page. For example, /virtual/page/foo.php would be the handler for the URL http://example.com/foo. /virtual/page/foo.php would also be the handler for the URIs /foo.xml and /foo/bar -- only the first part counts; the extension and subsequent path are ignored.

If you want to use a RESTful programming style, take care to make the base name either a noun or an adjective. If you want another method for mapping incoming URIs to PHP files, edit /init.php. (Look for alias_src in that file).

Within your PHP handler file, mind the following patterns.

• html_init

  At the top of most URL handlers should be something like this:

  html_init(
  	  "headerhowto", // which global navbar item is selected
  	  "how-to" // page subtitle
  	  );
  

  The first argument sets the currently selected item in the global navbar, which tells users where they are. For this page the item is headerhowto, and what that does is make the "how-to" menu item larger and a different color than the other menu items. The constant headerhowto corresponds to an item handle in $SITE_MENUS in /virtual/config.php.

  The second argument sets the page subtitle, which ensures that people who bookmark a page in your application will have a meaningful reminder of what the bookmark is. This will also be used for the H1 element in the current page, and the H1 will make it harder for users to get lost. (The big how-to in the upper left of this page is an example).

• validate_method

  After html_init, run validate_method:

  include_once(SITELIB."/validate.php");
  if(!validate_method(array(GET,HEAD),$msg))
     html_exit(HTTP_405,$msg);

  If you wanted to allow only POST (and not GET or HEAD) on a page you would do:

  if(!validate_method(array(POST),$msg))
     html_exit(HTTP_405,$msg);
  

  Specifying supported methods makes it easier for others to write web clients for your application, whether traditional browsers or new-school mashups. If you follow this and other RESTful programming practices from the beginning, you will be able to avoid writing a separate API for mashups.

Reading the source

1. Start with the /.htaccess file in the root directory of the distribution.
2. Read init.php in the root directory.
3. Read html_trimmings in /virtual/lib/html.php.

Resources

is by Lucas Gonze