• SleekPHP Documentation

    Welcome to the SleekPHP documentation! The online home for learning all things SleekPHP.

    If you want to build a site or perhaps even a module on top of SleekPHP you've come to the right place.

Downloading SleekPHP

Since SleekPHP is in early alpha there's no release yet, but if you're feeling really tech you can go ahead and check out the SVN repo over on Google Code.

Getting Started

Once you've downloaded SleekPHP and put the files on a web server you're ready to create your own site.

Creating your site

To create a site, simply create a directory in the Sites/ directory and name it what you want to call your site. SleekPHP best practices is to use PascalCase when naming files and folders as many are used as class names. I'm going to pretend you named your site "MyCoolSite".

You will also need to create a .info file in your new directory with the same name as the directory, ie MyCoolSite.info. For now you can leave it empty.

To tell SleekPHP to run your newly created site we have to open index.php and change this bit SleekPHP::run('SomeSite' to instead read SleekPHP::run('MyCoolSite'. Don't change anything else unless you know what you're doing.

Configuring your site

We're going to create two more files in our newly created site directory. One is used to configure stuff like your name and email and what style you want to use and the other is used to set up your routes.

Config.php

Create a Config.php next to your .info file. The config file should return an array of configuration and can look something like this:

<?php return array(
	'general.site_author'		=> 'You', 
	'general.site_title'		=> 'My Cool Site', 
	'general.site_tagline'		=> 'My Awsome Website', 
	'general.contact_email'		=> 'you@yourdomain.com'
);

What modules you use on your site will determine what config you need to set in there.

Routes.php

Now create a Routes.php file next to Config.php. We need to tell SleekPHP which URLs should point to which pages. SleekPHP won't do anything without any routes.

Similar to the config file, the routes file also simply returns an array of routes and pages and it might look like this:

<?php return array(
	'/' => 'Home'
);

That tells SleekPHP that the / route should point to the Home page. You can create more advanced routes with regexps and variables but we'll get to that later.

Creating your Home page

Now that we've set up our route we need to create the page we pointed the route to. A page in SleekPHP is an XML document that tells SleekPHP which modules should be rendered on that particular page. It can look like this:

<?xml version="1.0" encoding="UTF-8"?>
<Base>
	<NakedDay type="section"/>
	<Wrapper name="wrapper">
		<Header type="header"/>
		<Navigation type="nav"/>
		<Search type="section"/>
		<Breadcrumbs type="section"/>
		<Wrapper name="primary-content">
			<HelloWorld type="section"/>
		</Wrapper>
		<Wrapper name="secondary-content" type="aside">
			<StyleSwitcher type="section"/>
		</Wrapper>
		<Footer type="footer"/>
	</Wrapper>
	<GoogleAnalytics type="none"/>
</Base>

Every page should have a base module that all the other modules reside in. The base module typically consists of stuff like your DOCTYPE, head and body elements.

We can use the type attribute to tell SleekPHP to wrap our module in a different element than div which is default. If you don't want to wrap a module you can set it to "none".

Wrapper elements are not actually modules but are instead turned in to div elements. You'll notice I'm using three wrappers to put different modules in different sections. As you can see you can nest modules inside eachother.

With Config, Routes, Info and Home in place we can now have a look at our site (if you haven't already). You'll notice it's completely empty. This is because we have yet to create any of the modules we put in our Home page.

Here's where you can use one of SleekPHP's features and extend another SleekPHP site. Extending a site gives you access to all the modules, styles and plugins in that site.

A perfect site to extend for basic functionality such as Base, Header and Search is SleekBase. To extend a site, open up your .info file and enter in the following:

@extends SleekBase

If you refresh your window you should now see some stuff on the screen. SleekBase doesn't have all of the modules we put in the Home page - you'll have to create the rest your self.

Creating your first Module

At least one of the modules on our Home page doesn't exist in any of the sites we extend so we're going to have to create it ourselves. I'll use the "HelloWorld" module in the code that follows.

A module can consist of anything from just a single PHP class or template to CSS, JS, images, Flash, config, translations and more. We're going to start with the basics and just put "Hello World" on the screen.

To create the HelloWorld module, first create a directory in your site's root directory called Modules/ and in it create a HelloWorld/ directory.

Since our module doesn't require any logic (all it does is print "Hello World") we don't need to create a PHP class for it. What we do need, however, is a view.

Create a file called HelloWorld.tpl.php inside your HelloWorld/ directory and put this in it:

<h2>Hello, World!</h2>

If you refresh your browser, you should see "Hello, World!" wherever you put the <HelloWorld/> module on the Home page.

Now let's say we want to display today's date in our module as well. That's going to require some PHP logic. Let's update our view to have room for the date:

<h2>Hello, World!</h2>
<p>Today's date is: <php echo $today ?></p>

You could of course put the date logic in the view itself, but we should always strive to keep our views as free of PHP logic as possible.

The place a module's PHP logic belongs is in its controller. Create a file called HellowWorldModule.php next to your view and put this inside:

<?php
class MyCoolSite_HelloWorldModule extends Module {
	public function run () {

	}
}

That's the absolute minimum your module controller should consist of. As you can see I name the class MySiteName_MyModuleNameModule. This is so that other sites can extend your module without them having the same name.

The run method is mandatory and is used to do all the calculations needed for your module view. In our case, all we need is to figure out today's date:

<?php
class MyCoolSite_HelloWorldModule extends Module {
	public function run () {
		$today = date('l jS \of F Y h:i:s A');
	}
}

That won't be enough for the $today variable to be available in our view. Any variables you want to pass from your controller to your view needs to use the data() method of the controller:

<?php
class MyCoolSite_HelloWorldModule extends Module {
	public function run () {
		$this->data('today', date('l jS \of F Y h:i:s A'));
	}
}

That tells SleekPHP to pass a $today variable to our view with the value of date('l jS \of F Y h:i:s A').

Ok, we've now we've set up a basic site with a home page and a custom module but it looks well bland. Let's create a style so we can style it a little bit.

Creating a Style

To create a style for your site, create a directory in your site's root directory called Styles/ then create a directory in the Styles/ directory called MyCoolStyle/

Styles can also be extended. Create a MyCoolStyle.info file in your style directory and put @extends Normalize inside. Normalize is a SleekPHP Style based on the html5boilerplate.com CSS file and gives you a solid base to work from. Normalize also comes with handy SASS @mixins for CSS3 and more.

To add your own CSS, create a directory in your style directory called CSS/. This may seem redundant but styles can have JS, images and Pages as well.

Now add a .scss file to your CSS/ directory. You can name it whatever you want. Put something that will make a difference in there (like body {background: red}). Now we have to re-generate the front-end code.

Re-generating front-end code

SleekPHP merges all your script and styles into one file each so as to keep requests down to a minimumm. This isn't done automatically, you have to use the CodeMerger util for that. Simply visit /Utils/CodeMerger.php and pass in ?site, ?style and ?type, like this: http://localhost/SleekPHP/Utils/CodeMerger.php?site=MyCoolSite&Style=MyCoolStyle&type=scss.

You may also want to regenerate the "js" and "js_head" by changing ?type to one or the other. Make sure your styles directory is writeable by PHP.

If you're using the AutoRegenerateCSSJS plugin the CodeMerger util will automatically be called for each type on every page load. This means you have to reload the page twice after changes though.

Advanced Modules

Soon...

Plugins

Soon...

Disqus

blog comments powered by Disqus