As a side note, I have built a number of plugins for my own projects and client work that will never be released. The jQuery community needs to stop thinking of plugins only as releasable, open-source projects, and start thinking of them instead as a reusable pieces of code that can help optimize and DRY up a complex website. Take this little plugin as an example:

$.fn.notice = function(){
    return this.slideDown(500).delay(4000).slideUp(500);
}

It simply abstracts the animation for displaying a notice (using jQuery 1.4). Would I ever release this on an open source site? Of course not! But it is still a fully functioning jQuery plugin that can be used over and over throughout a website.

Design Pattern Series Overview

• Basics & Structure (this article)
• Options & Updating
• Callbacks & Custom Events
• Misc. General Practices

Basics

Filename

Every jQuery plugin sits in its own JS file, and is normally named using the following pattern:

jquery.pluginname.js
jquery.pluginname.min.js

Released plugins often also have a version number:

jquery.pluginname-1.3.js
jquery.pluginname-1.3.min.js

If you end up building a lot of plugins for your website, consider also including a namespace to keep all your files together (And of course you would combine and minify them for production, right?):

jquery.mysite.pluginname.js
jquery.mysite.pluginname.js

Basic File Layout

After any comments you choose to put at the top of your file, the very next thing you should have is a self executing anonymous function that will actually wrap your entire plugin. Say what!? Don’t worry, you have seen it before, and it looks like this:

(function($){

   ... code here ...

})(jQuery);

This gives your plugin a private scope to work in, and also allows your plugin to be used with $.noConflict mode without creating a problem. By passing jQuery into the function, the $ will equal jQuery inside the function even if $ means something different outside your plugin.

Structure

There are three basic structures you will see when you look at released plugins:

Contained Function

In this structure, (almost) all the code to run your plugin is contained within the function used to call your plugin. This is the most common format:

(function($){

   $.fn.myPlugin = function(){
      return this.each(function(){
         // do something
      });
   }

})(jQuery);

You should use this this structure when you are writing a simple plugin that acts once upon the jQuery result set on each execution. For complex plugins that need to maintain an adjustable state, you should consider the “Class and Function” structure.

Class and Function

In this structure, a class is used and an instance is created for each DOM element in the result set. You may see these objects attached in some way to the DOM elements they modify:

(function($){
   var MyClass = function(el){
       var $el = $(el);

       // Attach the instance of this object
       // to the jQuery wrapped DOM node
       $el.data('MyClass', this);
   }

   $.fn.myPlugin = function(){
      return this.each(function(){
         (new MyClass(this));
      });
   }

})(jQuery);

You should use this structure if you need to be able to access the object later that is associated with a DOM element. It is far easier to attach a single object vs several key/value pairs using the data() method. In this approach, you can access the object by calling $('selector').data('MyClass'). This functions more like a widget and is a plugin that maintains state and can adjust its state on the fly (Learn how in the next article.).

Note: Widget Factory: The next release of jQuery UI is going to see the addition of a Widget Factory that will be designed to specially assist in developing widget-like plugins.

Extend

In my opinion, this is the least idiomatic way to create a jQuery plugin. It uses the jQuery.fn.extend method instead of jQuery.fn.pluginName:

(function($){

   $.fn.extend({
     myPlugin: function(){
      return this.each(function(){
         // do something
     },
     myOtherPlugin: function(){
      return this.each(function(){
         // do something
     }
   });

})(jQuery);

You will find this structure helpful if you need to add a large number of plugin methods to jQuery. I would contend, however, that if your plugin needs to add that many methods, there may be a better way to structure its implementation.

I feel the extend method is used more by programmers transitioning from other JS libraries. I personally find the simple $.fn.pluginName = structure to be easier to read, and more in line with what you will normally see in jQuery plugins.

Up Next

In the next part of this series, we will look at passing options and providing methods for updating settings and functionality after a plugin has been called.

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

jQuery Plugin Design Patterns: Part I

I was really happy to see so much participation in this giveaway! After seeing how many people entered, I was feeling really bad that only one of them would leave with a copy of the book. I talked to Cody, and he graciously provided two more free copies so we can award a total of three books! I randomly picked three winners (using Random.org) and am happy to announce the following winners:

• Brad Rhine (truetech.org)
• Mila
• Geoff Woodburn (woodburndesigns.com)

Book Review

Late in 2009, Cody Lindley published a PDF book on jQuery titled jQuery Enlightenment. Today we are presenting our view of the book as well as offering a free copy to one lucky reader.

About The Author

Cody Lindley is a core team member of the jQuery project, and the original developer of the well known Thickbox plugin for jQuery. I had the pleasure of meeting and listening to Cody present at the jQuery Conference last year in Boston. He describes himself on his website:

Today I am a Christian, husband, son, brother, professional Web developer, and outdoor enthusiast. I spend a majority of my time sleeping and working, but who doesn’t? In between the daily routines of the average American, I desire an existence that entails a relationship with God, my family, and nature. I would like to consider myself a bookworm (a novice theologian at best), but truth be told, I simply enjoy watching movies and playing xBox way too much. I guess I also have the luxury of pursuing my profession as a personal passion. Yes, I often work even when I am not at work.

Overview

jQuery Enlightenment is a different type of book than I am used to seeing in the tech field. A list of what it is not might help shed light on what I mean. It is not documentation, a tutorial/walkthrough, or just conceptual material. jQuery Enlightenment is an amazingly clear montage of principals and code samples every jQuery developer needs to know grouped by topic. Cody covered topics both basic and profound throughout the pages of the book.

I consider myself quite adept at using jQuery, but found myself constantly amazed at the things I was learning while reading this book. Cody says it picks up where the jQuery documentation leaves off. I can see his point, but I think this book would be a better starting place for a new jQuery developer than even reading through the jQuery API site.

Pros

Code Samples

Code samples make up over 70% of the book (rough estimation). The book is not written in an editorial way at all. It is about presenting what you need to know, demonstrating it with an example, and moving on. For this reason the book is an extremely fast read and perfect for reference on a day to day basis.

Possibly one of the neatest features of the book itself is that (almost) every code sample provided in the book has a link to the same code on JSBin.com. JSBin is an online playground for testing and demonstrating JavaScript, HTML, and CSS technologies. jQuery Enlightenment isn’t a flat reading experience, it allows you to immediately jump in and play with the code samples until everything makes sense.

Additional Notes

Many of the topics are followed by a little box titled ‘Notes’. I am glad Cody didn’t choose some cheesy title for these boxes, but ‘Notes’ really does not sum up what they provide. You will find many undocumented (or hard to find) tips and tricks about the finer points of jQuery in these boxes. Skip over them at your own peril!

No Fluff Quality

Cody doesn’t waste any time on any of the topics presented in the book. The pattern used is simple: explain, demonstrate, move on. I personally will be using this book not just for reference, but for a quick read-through every few weeks to keep my jQuery senses sharp.

Cons

You will be hard pressed to find something negative to say about this book, and it wasn’t until I reached the end that I had one complaint about the content. The chapter on Ajax (Chapter 11) was far too short. Perhaps this is because the documentation is very clear, but I still wanted to learn more and have more examples to glean from. Perhaps the second edition of the book (which will cover jQuery 1.4) will provide more detail on jQuery’s AJAX implementation and associated methods.

Conclusion

I am confident new users and seasoned users alike will find much to learn in jQuery Enlightenment. After reading the book, my only concern is that I won’t remember all of the cool things I learned while reading it!

Win a FREE Copy!

Next Wednesday we will be selecting a winner to receive a free copy of jQuery Enlightenment. Entering the competition is easy!

Head over to jQuery Enlightenment and quickly look through table of contents. Then, leave a comment below telling us what chapter you think you would learn the most from if you were to win the book. Only comments referencing one of the actual chapters in the book will be eligible to win. We will randomly select a winner next Wednesday and announce it here on the site.. Sorry, but the contest is over!

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

jQuery Enlightenment: Book Review and Giveaway (Winners Announced!)

The Problem

As a developer, you are rapidly building your newest web creation. You start with the HTML, knowing full well you don’t have the hyperlinks you will need to complete the design. Nonetheless you put in:

<ul id="nav">
   <li><a href="/">Home</a></li>
   <li><a href="">About</a></li>
   <li><a href="">Contact</a></li>
   ...
</ul>

What seems like a long time later, you get to the point where you finish up your site for demoing or production. How do you quickly find all those empty links? Well, you could use a link checker… or, just use CSS3!

CSS3 Solution

Just paste this line to the end of your last included CSS file for a quick visual display:

/* Find all links where an href is not provided */
html body a:not([href]), html body a[href='']  { background: red !important;}

Then open your site in modern browser that supports CSS3, and any empty link now has a background of red. Edit your HTML, and check the page again. When all the links are fixed, none will have a red background!

You can see for yourself by checking a quick demo:
Standard Page | Page With CSS3 Link Checking

Bonus: Testing Progressive Enhancement

For mission critical functionality it is generally good practice to have a fallback for non JavaScript users. To test if your page has any JavaScript only code, add this rule to your CSS file after the rule we just added:

/* Find all links where the href = # */
html body a[href='#'] { background: yellow !important;}

Next, disable JavaScript in your browser (In Firefox and Safari it is an option in your preferences.).

Now, any of those links you cleverly enhanced with JavaScript, but forgot to add a valid fallback URL, will show up with a yellow background. If an item truly has application only when JavaScript is enable, you should consider adding it dynamically with JavaScript.

Variations

As a leftover vestige from IE6 days, many developers use href='#' so signify an empty url (So the :hover pseudo selector will still work). If this is your case, you have two options: 1) Change your style going forward and use href='' to signify an empty URL and href='#' for JavaScript enhanced links. or 2) Use only the second CSS3 rule and change the color to Red.

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Unconventional: CSS3 Link Checking

Technologies

Firerift

Firerift launched earlier this year as a completely new breed of Content Management Systems.  Firerift is, at its core, a JSON server with an amazing user interface. The mind behind Firerift Drew Wilson refers to it as a Client side CMS. All the tagging is done using CSS classes and valid markup. Released along with Firerift was Titan, an open source JSON templating engine built on top of jQuery. Firerift is a glimpse into the future of highly dynamic, AJAX powered websites.

LESS Framework

The LESS framework for CSS provides simplified execution of advanced CSS. With support for variables, mixins, nested rules and mathematical operations. LESS lives up to its name by letting you write shorter, optimized CSS. Though it is packaged as a Ruby gem, it can be used to prepare CSS files for any technology, even straight HTML/CSS websites. Since it uses CSS syntax, it’s as easy as renaming your .css files to .less and parsing through the LESS engine.

BuddyPress

BuddyPress is an amazing addition to WordPress MU (soon to be merged into WordPress core) that turns WPMU into an open-source social networking platform. From their website:

BuddyPress is a suite of WordPress plugins and themes, each adding a distinct new feature. BuddyPress contains all the features you’d expect from WordPress but aims to let members socially interact.

New Browsers All Around

This year saw major advances in pretty much all the major browsers. Safari 4 saw extreme speed increases in its JavaScript performance as well as support for advanced CSS3 properties. Firefox saw many of the same improvements and support with the 3.5 release. Even the browser developers love to hate saw significant improvements with the release of Internet Explorer 8. (Sadly, still no border-radius support!). Google Chrome seems to see major version number updates much faster than the other browsers, but of significant importance was the final release of a slightly limited Chrome for Mac Beta. Opera continued to improve and innovate their browser as well, but I think a great change this year was that Opera got an icon facelift and the dreaded drop shadow on the “O” is gone!

Notable Events

jQuery Joins The Software Freedom Conservancy

The jQuery team has been planning for a while to join the Software Freedom Conservancy to protect the jQuery project, open the door for future growth, as well as to move the copyright from John Resig’s own name into the Conservancy’s name. From the overview page:

One of the principal benefits of joining the Conservancy is that member projects get all the protections of being a corporate entity without actually having to form and maintain one. These benefits include, most notably, the ability to collect earmarked project donations and protection from personal liability for the developers of the project.

The jQuery team made the first step this year by joining the Conservancy as planned, and are now working to move the copyright as well.

Fix Outlook

A great movement from the guys over at Campaign Montior launched Fix Outlook as a web campaign to make Microsoft aware of how many people disliked the limited email rendering engine in Office 2005 and newer. The campaign saw over 20,000 tweets in the first 24 hours! Microsoft at first responded rather negatively, then changed face a bit and became very thankful of the effort raised by the website. You can read the full account for more details.

Books

Digging Into WordPress

Digging into WordPress is a fantastic new book by Chris Coyier and Jeff Starr. It is only available currently as a PDF book, but a printed version is coming soon. Written in an extremely down to earth manner, this book will provide useful information for anyone looking to take WordPress to the next level. This isn’t a book solving hypothetical problems: the authors only present techniques they have used themselves.

jQuery Enlightenment

Written by jQuery core team member Cody Lindley, jQuery Enlightenment picks up where the jQuery docs leave off. The book is probably 80% code examples and 20% explanation. This is a no fluff, crystal clear presentation of intermediate to advanced jQuery techniques, though I think even beginners would learn a lot through reading this PDF book. An additional innovative feature that I hope other book writers pick up is that almost every code example is linked to a live example on JSBin.com so you can actually play with his examples, even changing the code, to see how they work.

Operating Systems

Windows 7

After nothing less than a PR nightmare with Windows Vista, Microsoft released a fantastic new operating system this year in Windows 7. Far more stable than its predecessor, Windows 7 takes many of the principles and innovations introduced with Vista, but makes them both useable and reliable to users of Windows 7.

Snow Leopard

The innovative and trendy OS for Macintosh computers saw an upgrade this year with the release of Snow Leopard. As its name indicates, this OS is not that different an animal from the previous release of OS X (Leopard). Maintaining the same look and feel, Snow Leopard introduced many innovated technology features to further speed up the already finely tuned Mac line of computers. This has to be the first time in history that the install of a new version of an operating system actually gave you back 7GB of hard drive space!

iPhone 3.0

In the third version of the popular OS in use on iPhones and iPod Touches, users finally were allowed to Cut, Copy, and Paste! In addition, Multimedia Messaging (MMS), Spotlight Search, Voice Memos and Voice Dialing were also introduced. From a developers perspective, Apple opened up over 1,000 new API’s to allow iPhone developers even more freedom and power in their development process.

Android 2.0

For those that prefer an alternative to the Apple iPhone, many users have gravitated to the Android phones. This year saw an upgrade to the Android 2.0 OS and several UI and functional enhancements. Support for Exchange accounts, Combined Inboxes, and Macro Focus and White Balance for the Camera were all features added in this release.

Web Tools

Build It With Me

Some developers can do everything themselves from marketing, to design, to development. The rest of us would rather work on the part of the project we love, and leave the rest to someone better suited for the job. BuildItWith.me is the goto place to meet other developers that either have ideas or time on their hands to work on your ideas. Form new partnerships, find great projects to work on, all within the stylish interface of BuildItWith.me. I love their tag line: “Skip the funding.”

Noteable App

Noteable provides a great way for web developers to seek responses from their clients during the design process. Simply use one of the provided tools to make a screenshot of the a web page you are working on, and send it to your client for approval. The client can draw on the screenshot and make notes, all through a simple web interface. If you are a developer that works remotely from your clients, this service might be just what you are looking for.

Flagrant Self-Promotion

Downloadify

This year saw the release of Flash 10 and with it, the support for client-side file generation and download. Why is this important? Now developers can make web applications that can run fully in the browser, including file saving capabilities, without a round trip to the server. As a personal project, I built and released Downloadify to provide a JavaScript bridge to this amazing Flash functionality. Since the alternate server methods (dataURIs and IE functions) are all prone to usability problems, Downloadify provides a nice simple way to repurpose client side data and turn it into a savable file.

WANT MORE?

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Best of 2009 in the Coding Industry

Did you go to school for programming? How did you get started in this field?

I am a self taught programmer. I guess you could say I fell into the field when I was eight years old. I learned to program, well, mimic on a Commodore 128. I just typed in the code examples, then I changed things here and there and watched to see how it affected the program. I attended the Air Force Academy for electronic engineering and became an encryption programmer in the Air Force.

When I really started getting into the web development field, it was actually as a design and UI guy, not a programmer. I already knew how to program in C++ and Java, but not PHP. A friend of mine turned me on to the backend technologies, and I transitioned into the field of backend programming. I didn’t lose my connection to design and UI as fell deeper into the world of programming. On a side note, back in 1999 I really liked javascript… which if you remember is when most people didn’t like it at all!

Now I program all the time. Literally all the time. I normally program in five different languages all day at work, then do it all over again in the evenings. I don’t watch TV, I program.

It seems you like learning a lot about new technologies. Why is that?

Yes! Its actually a big joke with my family and friends. When Google announced ‘Go’, my brother-in-law called me right up and asked if I knew how to program with it yet. Anytime a new language comes out, I make a point of downloading it and building an application so I can understand how it works. It is really important to me to have a working knowledge of a technology. Then, when it comes up in a conversation I am not just speaking on hearsay. I have actually used it, so I can be more informed. It’s really all about dominance in arguments. :)

How would you recommend someone pick up an additional programming language?

I always recommend the same thing to anyone wanting to pick up a new language. Program something common with it. What I mean by common is something you know how to build in another language. For instance, whenever I learn a new technology I always build a user management app or a todo list app. The methodologies never change with those apps even though the technologies change. By building the same thing over and over with different technologies, I can more accurately compare them to each other. It helps me really learn the language. Hello World apps don’t show you what is really going on with the language.

Do you prefer physical books or searching for the information on the Internet?

I love books. I read a technical manual a month. I go through every step, try every example. When I am picking up a new language, I tell my brain I have never programmed before. Even when reading about MVC, I pretend I have never heard it before. Since each company handles it a little differently, I don’t pretend to understand how that company views it. When working through the examples, I never copy and paste; I type it all out. Even when I write tutorials, I often use screen-shots instead of easily copied code. I know good and well that if a programmer types each piece of code he will be less likely to forget what he learned. If all else fails, I will go to the internet for answers.

How do you get a personal or work project from idea to completion?

I try to crush goals quickly. If you set a milestone that is so large it overwhelms you, it will slow you down. Set a small goal, hit it, then do something else on a different project and with a different language. Switching between projects and languages keeps you from getting burned out. None of my to do lists on a project have more than 4 or 5 items. This is essential to fight burnout. When you fight burnout, you keep yourself happy. Plus switching languages helps you stay very adaptable.

I have also found that feature creep comes from not stopping when your five tasks are done. When you finish what you set out to do, don’t look at it as being half complete. You are done… stop working on it. If you don’t, you will kill your own motivation. The big picture is beautiful, but don’t ruin it because a single leaf isn’t quite as nice as you imagined it.

Its your hobby, its your work. What else do you do when you aren’t programming?

I build furniture. I Build computer desks. As my needs change, so does my desk. As my languages change, my desk changes. I also spend time with my family. When I get home from work, three hours every night is family time.

I enjoy rock climbing and kayaking, but my current hobbies are really golfing and salt water fishing. However, sometimes I just like driving around and seeing how people interact with each other. I get a lot of inspiration for things I build by watching people interact.

Best thing sometimes is to stop and see the world for what it is. Not thinking about programming, but sitting with the family and enjoying life. Clearing your brain like that helps you get ready to code when you need it. I have never met a really stressed out programmer who writes really good code.

Thank you so much for this interview! What advice can you leave us with?

Push the limits of the technology you are using to the edge. Push it to where it shouldn’t even be functioning any more. An example of pushing the bounds is the Cappuccino framework. It is pushing javascript to the edge of what it should even be able to do. It completely blows my mind. Its the same thing Objective-C did to C. They broke the bounds of what the browser is capable of.

If you don’t think you can push the boundaries any further, then break them entirely. Use research to see how other people are using technologies in combination with out-of-the-box thinking. See how they are applying to to solve problems. Keep pushing the envelope.

How can our readers get in touch with you? Do you mind people connecting with you?

I love interacting with people! I am almost always on Freenode in one of the developer channels. I can be reached on AIM by my screen name: wattzilla. Of course my Twitter account is another great way to get in touch with me. I welcome any and all contact, so look me up!

Note: This interview has been adapted to a question and answer format from my much more relaxed interview with Wess last week.

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Interview with Wess Cope, Wattz.net

This is accomplished by using the prototype object. Each native object in JavaScript includes a prototype object. Don’t get this confused with the PrototypeJS framework… the prototype object is a way to extend all objects that have inherited from the base object you extended. You can easily extend the prototype object by adding functions to it like this:

Object.prototype.functionName = function(){

}

You can then call them directly:

var obj = new Object();
obj.functionName();

There are a number of advanced uses of the prototype object, but this is the important thing to remember: any function added to the prototype of an object is available on any object that inherits from it. So if you extend the prototype on the Number object, all numbers will have access to the new function; if you extend the Array object, all arrays can access your custom function. You only use the prototype.functionName syntax when declaring the new function, not when calling it.

Enough theory, lets see some (somewhat) practical uses:

Do you find yourself capitalizing a lot of words in a particular JavaScript app? Just add a capitalize method to the String object.

String.prototype.capitalize = function(){
  if(this.length == 0) return this;
  return this[0].toUpperCase() + this.substr(1);
}

Now you can capitalize any string in your application by calling "lower".capitalize() and get "Lower" in return. Since it returns a string, you could chain it with any other function you can execute on a string.

Do you always find yourself forgetting you can call Number(”25″) to turn a string into a number? Just add a toNumber() function to the String prototype:

String.prototype.toNumber = function(){
  return Number(this);
}

If you need to split large JSON arrays into groups of two or three each, you could extend the Array object like this:

[js]
Array.prototype.inGroupsOf = function(num){
	var ret = [],
		length = this.length,
		groups = Math.ceil(length / num);

	for(var i = 0; i < groups; i++){
		var start = i * num,
			end   = start + num;

		ret.push(this.slice(start, end))
	}
	return ret;
}

Now calling inGroupsOf(3) on any Array would return that same array split into as many parts as needed to ensure no group has more than three items in it.

There are a number of objects you can extend, but the ones you will use the most are String, Array, Object, Number, Date. One trouble area you might face is calling methods on numbers. The following example will fail:

Number.prototype.to_s = function(){
  return this + "";
}

25.to_s();

The prototype function is correct, but the way we called it is wrong. There are two ways to call our custom functions on numbers:

var n = 25;
n.to_s(); // Returns "25"

(25).to_s(); // Also returns "25"

Think Start, Not End

Its important when deciding what object to extend that you focus on what object type you are starting with, not so much which type you plan on ending with. For instance, if you wanted to extend an object to easily parse Twitter date strings you would not extend the Date object. You would extend the String object, and your function would return a Date object.

Load Your Extensions First

It is normally a good idea to load these extensions prior to any other library, including jQuery. Anytime you extend the prototype object, the new method is instantly available to all objects of the same type or any object that has inherited from that type. However, since you want to be sure your methods are always available, you guarantee their availability by loading them first.

How to Group The Extensions

Naming your files Prototype.Date.js and Prototype.Array.js is an easy way to keep all your extensions in one part of your JS folder, and easy to access during development. If you follow this method, you would simply put Date.prototype methods in the Prototype.Date.js file, etc. This starts to break down when you have parallel functions. You might have a toDateFromTwitter() method on the String object and a toTwitterFromDate() method on the Date object. Putting these in separate files might not make sense. At that point, you should put both these extensions in a file named TwitterHelpers.js or something similar. Obviously use what makes sense to you and works with your flow.

Don’t Bloat

Just because you write 500+ awesome Array extensions in the next 2 years, does not mean you need to include them on every project. Be sure to only use this technique when it makes sense for the project and when it helps clean up your code.

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

JavaScript Can Learn: Now Teach It Tricks!

Mini-series Overview

• Part 1: URL Routing and Directory Setup
• Part 2: Templating
• Part 3: Database Interaction

You can download all the files put together during this three part series here:

I’m not going into detail about how to create an ORM or ActiveRecord clone. We are just going to write a simple helper class to setup our connection and query. Also I’m going to assume you know how to create a database and table in the database.

I have created a database called “peanut” and created table:

users:
+----------+--------------+------+-----+---------+----------------+
| Field    | Type         | Null | Key | Default | Extra          |
+----------+--------------+------+-----+---------+----------------+
| id       | int(11)      | NO   | PRI | NULL    | auto_increment |
| username | varchar(255) | NO   |     | NULL    |                |
| password | varchar(255) | NO   |     | NULL    |                |
+----------+--------------+------+-----+---------+----------------+

In this example we are going to use Mysql and the php mysql_ methods. So break open system/database.php and drop the following in:

<?php

// Here is where we are setting up a simple wrapper class around mysql
// functions just to make it a little more convenient.  Our models will
// simple extend our database class and simplify making queries just a bit.
class Database
{
	protected var $connection;
	// Every time you instantiate this class you are going to create
	// a new connection to the database.
	public function __construct()
	{
		// First we setup up a nice little connection to the database,
		// make sure you use your connection information.  If the
		// connection fails we just die with the error.
		$this->connection = mysql_pconnect("localhost", "root", "somepassword") or die("MySQL Error: " . mysql_error());

		// And let's tell mysql which db we are going to use.
		mysql_select_db( "peanut", $this->connection );
	}

	// This is just a helper function to help out against
	// possible sql injection attacks.
	public function escapeString($string)
	{
		// we call mysql's 'cleaning' function on strings
		// just to make sure we get a little safer item to query
		// with.
		return mysql_real_escape_string($string);
	}

	// Here we will query the database with the passed query string,
	// build up an array of objects and return them, simple enough.
	public function query($qry)
	{
		// Here we make our query and set the result to a $result variable
		$result = mysql_query($qry) or die("MySQL Error: " . mysql_error());

		// Create a container array variable to hold all of our result objects.
		$resultObjects = array();

		// This might look weird, but all we are doing is saying,
		// While you are still getting results, please put the next
		// result into the next spot on my array.
		while($resultObjects[] = mysql_fetch_object($result));

		// Now we just return our array that has all our result objects in it
		return $resultObjects;
	}

	// Here we add a simplier method for handling INSERTs and UPDATEs since
	// they do not return a result set.
	public function execute($qry)
	{
		$exec = mysql_query($qry) or die("MySQL Error: " . mysql_error());
		return $exec;
	}
}
?>

So we have our database class in place and ready to use, now we just need to require it in the index.php like we did the others, so pop that bad boy open and after the template require, do one just like it but for the database.php

Now let’s crack open actions/helloworld/models.php and let’s write a simple addUser and getAllUsers method to it. We are going to make our model a class as well so that it can extend our Database class that we wrote.

Here are the guts:

<?php

// All of our database back-and-forth will be handled in our models file
// Don't be mistaken, this is no where close to an ORM (Object Relational Mapper)
// it's just simplified database access.

class myModel extends Database
{
	// When our model is instantiated we just need
	// to also instantiate our parent class (Database)
	// so it knows to make the connection to the database.
	public function __construct()
	{
		// We just call the __construct of Database class.
		parent::__construct();
	}

	// addUser will use the execute method of Database
	// since we are inserting a value and not expecting
	// anything in return.
	public function addUser($username, $password)
	{
		// Here we use that little cleaning method we
		// wrote to make our strings pretty and make sure
		// they will play nice with mysql
		$username = $this->escapeString($username);
		$password = $this->escapeString($password);

		// We execute our insert and if it worked $success
		// will be true else it will be false.
		$success = $this->execute("INSERT INTO users (username, password) VALUES ('{$username}','{$password}')");

		// We return $success to inform our page action that it has or hasn't worked.
		return $success;
	}

	// This method does just what you think it would.
	// We are going to use the query function because
	// we are expecting data back, then we are just
	// going to return the array of user objects.
	public function getAllUsers()
	{
		// Populate the $users variable with the results of our query
		$users = $this->query("SELECT * FROM users");

		// Now we return our results
		return $users;
	}
}
?>

Now we need to change our actions/helloworld/actions.php mypage page action to:

<?php
// We need to include our models file so we can access the database
require(PEANUT_ROOT_DIR . 'actions/helloworld/models.php');

// We simply define the function (the second item in our request url)
// making sure it is the same name as the one in the url.

function mypage()
{
	// Let's do some database work!
	// Here we are going to instantiate our model
	$model = new myModel();

	// Now let's add a user
	// On a funny note, if you keep refreshing it will add this
	// user over and over in your users table so your getAllUsers call
	// will result in a list that grows by one each time.
	$model->addUser("wess", "password");

	// Now let's fetch all of our users and put them in our users
	// variable.
	$users = $model->getAllUsers();

	// Let's create a new template object and pass it the path to our template
	$template = new Template("helloworld/templates/helloworld.php");

	// I bet you want to display a table in your template with all your newly
	// created users. So let's do it

	// That's write we use the same set command, and it will set our array of users
	// to our template variable $users, and since php is our template language
	// it's real easy to print them to the screen.
	$template->set('users', $users);

	// Set our page variable "title" with the value "Hello World"
	$template->set('title', 'Hello World');

	// Set our page variable "message" with our little message
	$template->set('message','This is my first message for my template');

	// Now we can call render and return it to dispatch to
	// display in our browser
	return $template->render();
}
?>

So now you are handing all your users from your database to the template, so let’s display them. Change your actions/helloworld/templates/helloworld.php file to:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-type" content="text/html; charset=utf-8">
		<title>My PEANUT Page</title>

	</head>
	<body>
		<h1><?php echo $title ?></h1>
		<p><?php echo $message ?></p>

		<h2>Users:</h2>
		<table>
			<thead>
				<tr>
					<th>ID</th>
					<th>Username</th>
					<th>Password</th>
				</tr>
			</thead>
			<tbody>
				<!--
					Here we are going to use native php foreach look
					to create each row of the table with our list of users.
					Notice how the foreach is done with a : and surrounding php tags.
				-->
				<?php foreach($users as $user): ?>
					<tr>
						<td><?php echo $user->id ?></td>
						<td><?php echo $user->username ?></td>
						<td><?php echo $user->password ?></td>
					</tr>
				<?php endforeach; ?>
			</tbody>
		</table>
	</body>
</html>

Now if all went well, you should save all your files and open up: http://mywebapp.local/helloworld/mypage and see all the users that you added in a table.

So you have created a template class, url basic url routing, simplified database access, and a page action. You have all the core basics of a PHP Framework at your hands now. This is just for a starting point or foundation of understanding, please do not use this in a production environment.

I have really enjoyed writing this and I hope you learned something from my rambling! The source code is available for download at the top of this article.

Take care,
Wess “Wattz”

Updated October 26, 2009: Thanks to Alex and Ian for spotting some errors in the code and supplying the fixes. The code examples have been updated to reflect the changes as has the ZIP file.

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Roll Your Own PHP Framework: Part III

Below is a screen capture of the final gallery. To see the gallery in action, click here

This tutorial assumes that you have textpattern installed and ready to go.
( Download the latest version of Textpattern here: http://textpattern.com/download)

Galleriffic

This gallery is based on Galleriffic, a jQuery plugin for rendering fast-performing photo galleries. This is adapted from http://www.twospy.com/galleriffic/ to work with textpattern so you (and your clients!) can easily update the gallery. In a nutshell, the gallery works by associating image id #s with a specific article. The article form gallery and article_image_form work together to render the article in the form of all of the associated images (in their thumbnail format) to appear as an unordered list on the left, while the full version of the current image appears on the right. All that is necessary to add or change images, is to change the numbered list appearing in the advanced options on the left of the article containing the images. So easy once implemented, even a client that doesn’t speak nerd can add, subtract or change their own images.

Upload the files

Upload both of the galleriffic files included in the files folder of the download, by uploading them through the Content > Files tab. I modified the jquery.galleriffic.js file so that the pagination does not appear above the thumbnails. Should you wish to further customize the gallery, I do suggest checking out the original Galleriffic demo.

Install the relevant plugins

Install the following plugins (these are included in the Plugins folder in the download):

• upm_image by Mary Fredbord – more powerful image display
• ebl-image-edit by Eric Limegrover – introduces advanced image editing functionality

(I have had technical issues with v.2 of this plugin, so I continue to use v1. Both are included in the plugin folder.)

ebl-image-edit is great for sizing/creating thumbnails on the fly, without having Textpattern automatically centre the thumbnail. It is not essential to this tutorial, but it’s very very handy!

Set up your forms

You can find these forms in the forms folder in the download.

gallery

Create a new form called “gallery” and choose “article” for the type:

<txp:upm_article_image form="article_image_form" wraptag="ul"
class="thumbs noscript" />

article_image_form

Create a new form called “article_image_form” and choose “misc” for the type:

<li><a href="<txp:upm_img_full_url />" title="<txp:upm_img_caption />" class="thumb"><img src="<txp:upm_img_thumb_url />" alt="<txp:upm_img_alt />" /></a>

<div>
<div><txp:upm_img_alt /> </div>
<div><txp:upm_img_caption /></div>
</div>
</li>

If you don’t want captions, delete the whole caption div.

Basically we have taken this code from galleriffic:

<ul> <li> <a href="path/to/slide" title="your image title"> <img src="path/to/thumbnail" alt="your image title again for graceful degradation" /> </a> <div> (Any html can go here) </div> </li> ... (repeat for every image in the gallery) </ul>

and modified it so the article forms generate this code from the image numbers that we will associate with the gallery article. We’re basically saying, “take the images associated with this article, put the thumbnail versions of those images on the left with these classes and this formatting, and put the full version of the selected image on the right.” Huh? Just follow along, I promise it will all make sense soon…

Set up your page

In the pages folder I have included a template for this gallery page (gallery.html). Create a new page template in textpattern: Presentation > Pages. At the bottom, “copy page as”, name it gallery, and click “copy.” Make sure whatever section you are using for the gallery is in fact using the gallery page as its template. At the bottom of the page you will notice the galleriffic script. This is where you can make adjustments to sizes, number of thumbnails, etc. In this example I have set a limit of 9 to the thumbnails. At the bottom of the page, near the top of the script, it looks like:

numThumbs: 9,

Set up your style

I have created a master style sheet that incorporates some of the Textpattern defaults as well as galleriffic specific css. Copy the content from the screen.css file provided in the Styles folder and paste it into your default styles tab under Presentation > Style.

Add your images

Go ahead and start uploading some images, and create some thumbnails. Make sure your images are all using the same size of thumbnail. Take note of the image ID numbers, as that is what you will use to call your images into the article. Make sure to add the Alt text and Caption when you upload, as this is what will appear to the left of the main image (unless you opted to delete the captions).

Create a new article called gallery. On the left hand side, click advanced options, and enter the ID numbers of the images you want to appear in the gallery, separated by commas. Make sure you post the article to the gallery section, or whichever section you have set up to display the gallery, and click publish. Your article should look something like this:

View Site. You should notice that the images have been automatically formatted into thumbnails on the left, with the first one appearing in full on the right. That’s it! You have a galleriffic gallery integrated with Textpattern. Play around with the html, settings, scripts and CSS to customize it to suit your own needs.

If you have any questions, suggestions, or requests for future articles, please do not hesitate to leave a comment.

Thanks, and happy coding!

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Easy to update thumbnail gallery using Textpattern and Galleriffic

Mini-series Overview

• Part 1: URL Routing and Directory Setup
• Part 2: Templating
• Part 3: Database Interaction

Note: I’m assuming you have a little OOP (Object Oriented Programming) experience. There are a ton of tutorials out there, so just a heads up: I won’t be teaching/explaining OOP here.

We are going to create a class Template and add a little code to it so it will return our pretty new page to our browser.

Wipe out system/template.php and add the following code to it:

<?php
// We are creating a simple class here to handle our templating.
// All this class will do is set some variables and return
// a rendered webpage using native php as the template language.
class Template
{
	// We setup $pageVars to hold all our pages
	// variables.
	private $pageVars = array();

	// We setup $template to define what file is our
	// template and were to get it.
	private $template;

	// When a new Template object is instantiated we want to make sure
	// we pass it a shortened path to the file we want it to use
	// as our template.
	// example: $template = new Template("helloworld/templates/helloworld.php");

	public function __construct($template)
	{

		// We setup our action directory
		$actionsDirectory = PEANUT_ROOT_DIR . 'actions';

		// Let's build and set our class var $template to the
		// value of $template that was passed into our __construct method
		$this->template = $actionsDirectory . '/' . $template;
	}

	// Now we create out set method to allow use to set variables that
	// we want in the template.
	// So in our page action we would do:
	// $template->set("title", "hello world");
	// and in our template:
	// <h1><?php echo $title; ?></h1>
	public function set($var, $val)
	{
		// This may look weird, but it's not to bad;
		// what we are doing is setting the index name
		// of our associative array pageVars
		// (we setup earlier at the top of the class)
		// to the value that we pass. so $pageVars["yourVar"] = "yourValue"
		// is basically what it's doing.
		$this->pageVars[$var] = $val;
	}

	// To render we will need to do a couple of things.
	// First we will need to extract those pageVars then
	// include the template, populate the values in the template
	// and return a rendered page to the browser
	//
	// This is far more easy than you think it is
	// trust me!
	public function render()
	{
		// The extract function is a weird bird
		// when you call it on an associative array
		// it creates regular vars.
		// For instance:
		// 		$this->pageVars["yourVar"]
		// becomes:
		// 		$yourVar
		// so basically we are converting all the
		// index keys (with their values), in pageVars to
		// their own respected variables
		extract($this->pageVars);

		// Now that we have all the variables extracted, the vars we set
		// in the template will be replaced by the value of the pageVars variables.
		// Now we start up our output buffer, grab our template and return the
		// buffer with it's "rendered" template
		ob_start();
			require($this->template);
		return ob_get_clean();
	}
}

Well hello templating! Now let’s do a couple of things to hook it up to our framework. First, let’s open up our www/index.php one more time and add the following line:

require(PEANUT_ROOT_DIR . ’system/template.php’);

Right underneath the dispatch.php require statement. Now let’s change our actions/helloworld/actions.php mypage function to look like:

// We simply define the function (the second item in our request url)
// making sure it is the same name as the one in the url.
function mypage()
{
	// Let's create a new template object and pass it the path to our template
	$template = new Template("helloworld/templates/helloworld.php");

	// Set our page variable "title" with the value "Hello World"
	$template->set('title', 'Hello World');

	// Set our page variable "message" with our little message
	$template->set('message','This is my first message for my template');

	// Now we can call render and return it to dispatch to
	// display in our browser
	return $template->render();
}

Ok, so now our page action is setup to use our new found template class, now we need to setup our template

So inside actions/helloworld/templates/helloworld.php template put the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-type" content="text/html; charset=utf-8">
		<title>My PEANUT Page</title>

	</head>
	<body>
		<!--
		See how we use native php here?
		echo out a variable, this is the same
		variable name that you use in your template
		set method ($template->('title', "hello")).
		-->
		<h1><?php echo $title ?></h1>
		<p><?php echo $message ?></p>
	</body>
</html>

Ok, so let’s see where we are at. We have basic url routing, templating, and page actions. We are only missing one thing, a way to talk to the database! That will be the next and final article in our mini-series on rolling your own PHP Framework.

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Roll Your Own PHP Framework: Part II

To help celebrate with our good friends at HTMLRockstars (formally known as CSSRockstars) we are giving away (4) copies of Snow Leopard.

HTMLRockstars provides PSD to HTML service in just 3 days, for only $149. They take your existing design and transform it into valid, high quality, hand-coded markup. They also offer templating/skinning of the hottest CMS, Shopping Carts, and Blogging platforms such as WordPress. With semantic markup, microformat inclusion, documented HTML / HTML, and a money back guarantee, HTMLRockstars offers one of the most feature complete packages available. You can also follow them on Twitter.

Enter for your chance to win Snow Leopard! You will have 2 chances to win 1 of 4 copies courtesy of HTMLRockstars.

Here’s how:

• All you have to do is follow Fuel Your Coding on twitter & Retweet this: (RT @HTMLRockstars Launch + 4 will WIN a copy of Snow Leopard! Enter to Win on @fuelyourcoding http://twurl.nl/2r5jnl #FUELCONTEST)
• Then head over to Fuel Your Creativity to enter for a second chance. *please note: directions differ on Fuel Your Creativity.
• Contest will end on both sites, Sunday at 12 Midnight EST.

Twitter Winners Announced:

1. @brookeduckart
2. @madmanstudios

*To get your copy, please DM me @adellecharles

Be sure to check out Fuel Your Creativity if you didn’t win here!

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Winners Announced: HTMLRockstars Launch + 4 will WIN a copy of Snow Leopard!

Mini-series Overview

• Week 1: URL Routing and Directory Setup
• Week 2: Templating
• Week 3: Database Interaction

To get started let’s setup our directory structure. We are going to call our framework “Peanut” (first thing that popped in my head).
So for our structure let’s make it really basic:

MyWebApp/
  '---actions/
    '---helloworld/
      '--- actions.php
      '--- models.php
      '--- templates/
        '--- yourTemplateHere.php
'---system/
  '--- template.php
  '--- database.php
  '--- dispatch.php
'---www/
  '--- js/
  '--- css/
  '--- images/
  '--- index.php

Let’s break this structure down, it’s simple.

MyWebApp: the root of your web app that will be using our “Peanut” framework

• actions: this will contain all the pages our web app will use.
  • helloworld: is the name of our page action or ’section’ of our site
    • actions.php: is where we will code our page actions
    • models.php: where we will write all our database interaction
    • templates: this is the folder we will store all our views/templates
• system: this is where we will store all our framework specific classes/source/libraries
  • template.php: This will handle all of our template rendering.
  • database.php: This is for our database connection and access
  • dispatch.php: This will parse our url and call the correct page action.
• www: this is our root web directory, it is also where we will pull everything together.
  • js: the directory where you store your javascript
  • css: put your style sheets in here
  • images: guess!
  • index.php: This is the file that will initiate and pull together the pieces of Peanut.

Now that we have a directory structure, let’s setup a virtual host in Apache to accommodate for Peanut. Here is an example of a virtual host you can use (here is what I do on my Mac):

NameVirtualHost *:80

<VirtualHost *:80>
        ServerName      mywebapp.local
        DocumentRoot    /Users/wcope/Sites/mywebapp/www

        AcceptPathInfo On

        RewriteEngine On
        RewriteRule     /*\.(css|js|gif|png|jpe?g)$ - [NC,L]
        RewriteRule "^(.*)$"    "/index.php?_url=$1" [QSA,L]

        <Directory "/Users/wcope/Sites/mywebapp/www">
                AllowOverride All
                Order allow,deny
                Allow from all
        </Directory>

</VirtualHost>

And In my /etc/hosts file I add this line:

127.0.0.1	mywebapp.local

That will allow ‘mywebapp.local’ to resolve to my localhost where Apache will pick it up and kick it off to the virtual host we created. Inside that virtual host we have some rewrite rules that will redirect all request made (except css, js, gif, png, jpeg/jpg) to index.php?_url=$1. To break that down in the simplest way, basically Apache takes: mywebapp.local/some/page and redirects it to index.php?_url=/some/page (but you never see the latter). Also notice that we made the root directory of our virtual host to our www folder where index.php is.

Ok, so now we have our directory structure, virtual host and rewrite rules all setup. If you have any detailed questions about Apache, mod_rewrite, virtual hosts, host files, etc. Sorry they will not be covered here due to the fact that there is tons on it out there… so hit up your local google.com :).

So now let’s get to some code.

So first lets write our dispatch code since that will be what is responsible for routing all our request to the proper pages.

Open up index.php in your favorite text editor and let’s slap some code in it:

In this file is a good place to put constant variables, include any files and call our dispatch (once we write it). But for right now let’s do a little test, and also write a little helper function I’m going to use to print stuff to the screen that can help us see what’s going on.

<?php
// First let's define our apps root directory
define("PEANUT_ROOT_DIR", realpath(dirname(__FILE__) . '/../') . '/');

// now a pretty little dump function (or if you have xdebug you can just use var_dump)
function dump($item, $die=true)
{
	$printString = '<pre>' . print_r($item, true) . '</pre>';
	if($die)
		die($printString);
	else
		echo $printString;
}

// Now let's just dump our URL to make sure that all paths lead here
dump($_GET);
?>

Now if we bring up our url: http://mywebapp.local/some/url/ we should see something like:

Array
(
    [_url] => /some/url/
)

So now we can see that our rewrite is working and we are ready to start writing our dispatch function, so let’s change our index.php code a little.

<?php
// First let's define our apps root directory
define("PEANUT_ROOT_DIR", realpath(dirname(__FILE__) . '/../') . '/');

// now a pretty little dump function (or if you have xdebug you can just use var_dump)
function dump($item, $die=true)
{
	$printString = '<pre>' . print_r($item, true) . '</pre>';
	if($die)
		die($printString);
	else
		echo $printString;
}

// Let's comment this out
// dump($_GET);
// and add this:

// first we are going to drop our dispatch file in here
require(PEANUT_ROOT_DIR . 'system/dispatch.php');

// then call our dispatch function to handle the url
// Notice Im not passing in $_GET or $_GET['_url'], being that
// $_GET is a global system variable, I don't have to worry about it
// here.

dispatch();
?>

So now let’s save that and crack open our system/dispatch.php file and and add some code to it to handle our new found url pattern. As I said before, this will only be a simple router with no config or predefined url pattern to page action mapping.

So, inside dispatch.php, let’s add:

<?php
// Here we are going to handle our url request

function dispatch()
{
	// First we are going to grab our url path and trim the / of the
	// left and the right
	$url = trim($_GET['_url'], '/');

	// Now we are going to split the url on the / which
	// will give us an array with 2 indexes.
	$url = explode('/', $url);

	// Let's just print out our array to get a visual of
	// what we are working with.
	dump($url);
}

?>

Now if you refresh your browser at our current url (http://mywebapp.local/some/url/) you should see:

Array
(
    [0] => some
    [1] => url
)

Great, now we have 2 clean items to work with. So let’s tell dispatch that the item at index 0 will be our folder and item at 1 will be the page action inside our actions.php file. Since our directory structure is setup to use actions/helloworld/actions.php, let’s setup dispatch to include the file with our action in it in the directory that was requested in the url. So change dispatch.php to look like:

// Let's handle that url
function dispatch()
{
	// First we are going to grab the url path and trim the / off
	// the left and the right.
	$url = trim($_GET['_url'], '/');

	// We changed this from before to make it easier to read and also so we can
	// work with easier variables.  using the list (http://php.net/list) function
	// will map the array indexes to the respected order of the var names inside
	// the list function call (better explanation at php.net/lists).
	list($directory, $action) = explode('/', $url);

	// Now we drop in our respected actions file from the directory in the url
	require(PEANUT_ROOT_DIR . 'actions/' . $directory . '/actions.php');

	// And call the action from inside our actions.php file
	// and since we want to end our request with the return value of our requested method
	// let's just die on the return.
	die($action());
}

Now we need to add our action inside our actions.php file, so open it up and drop the following
in it:

<?php

// We simply define the function (the second item in our request url)
// making sure it is the same name as the one in the url.
function mypage()
{
	// For now we are simply going to return "Hello World" string
	return "Hello World";
}

?>

So let’s give this a shot. Open up your web browser and point it to: http://mywebapp.local/helloworld/mypage.You should see a pretty little “Hello World” in the browser. If you do, congrats! You now have routing in your new Peanut framework.

Next week we will see how to add templating into our framework.

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

PHP Frameworks? Just roll your own! – PART 1

All this was inspired yesterday by Janko’s article yesterday, “Automatically generate table of contents using jQuery.” Start by reading his article to get a background on the topic, then head over to the documentation page for the download link as well as three different examples of usage.

This plugin is version 0.8, so please comment on any bugs you find. Feel free to follow or fork the project on github as well! Keep in mind I didn’t spend ages getting the CSS on the example pages to be cross-browser ready, though the plugin itself has full cross-browser support.

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Table of Contents jQuery Plugin

Why Textpattern?

Okay, I will be the first to admit that when I first started with Textpattern, I was in way over my head. I had never worked with a CMS before, and I wasn’t an expert with CSS. I had stumbled upon a beautiful portfolio website by another web designer, and I noticed in the footer that the website was built using Textpattern. I thought to myself, if this designer can build a dynamic portfolio website using Textpattern, surely I can too, right? So I made it my mission to learn and master Textpattern. I learned the hard way, since I didn’t know anyone who was familiar with it (Wordpress always seemed to be the CMS of choice). However, Textpattern has an enormously helpful community and many helpful articles, blogs, and forums where other users were generous enough to share their tips, tricks and plugins. Textpattern has now become my CMS of choice as I have found it to be undeniably powerful and flexible, and it doesn’t require any knowledge or experience with PHP (not to mention, it’s free and open source). Once you wrap your head around the basics, you can bend Textpattern to your will quite easily. Check out the publishing features on the textpattern website.

Getting started

This tutorial assumes that you have a fairly strong understanding of HTML and CSS, however I am using an adapted version of Google Blueprint CSS to keep things extra simple. We will be building a very simple portfolio website with a blog component. I will continue to add articles which will build on textpattern’s functionality, but for now I am stripping a lot of Textpattern’s defaults, which can be quite confusing if you’re not sure about the syntax.

Head over to the textpattern website to download the latest version. Follow the detailed install instructions.

You will also need the files I provided in this zip file:

Login to your site, and you should see something like this:

You will notice that Textpattern has 4 tabs at the top: content, presentation, admin, and view site. Go to your admin tab, and check your diagnostics to make sure that there are no errors in your installation. If all checks have passed, head over to your preferences, and change your site name and slogan (even if you choose for these not to appear as is, you should change them to be relevant to your own site). It is a matter of personal preference, but I like to change my permanent link mode to section/title, as I like the way it appears in my url. Since this is a beginner tutorial, I would recommend leaving the other settings as is until you are more comfortable with Textpattern.

In the Textpattern handbook, it is recommended that you code your site in HTML and CSS before building it on Textpattern. I tend to build my sites live within Textpattern because I find the textpattern tags and plugins can achieve what I want much faster than coding it by hand. It’s really a matter of personal preference.

What I am going to do is STRIP AWAY the Textpattern defaults, and simplify things a little bit. Once you get more comfortable with textpattern, you can begin to add in more functionality, but for the purposes of understanding how textpattern works, I think the defaults are a bit overkill when you’re learning.

In a nutshell

In a nutshell, textpattern works by posting articles (think of articles as your main content) to sections (main navigation) of your site. Each section is associated with a page template. The pages tab under Presentation is where you dictate the HTML structure of your page. This is where your html combines with txp tags to create the functionality of your templates. The style tab under presentation is where the css resides. Forms are the most powerful part of textpattern; they tell an article how, when, where, and why to appear! More details on forms below.

Set up your sections

Think of sections as the main navigation of your site. In this example, we’ll use about, work, blog and contact. There is no need to create a “home” section, as the “default” section IS the home section, and you will notice that textpattern already has an about section by default. So create a work, blog, and contact section. I tend to leave the “articles” section that is there by default, and I use it to post my articles that appear only on the homepage but nowhere else. For the about and contact page, I tend to select NO for the setting: “on front page” , since the homepage can display articles from all sections, and I do not want my contact page to appear on my homepage.

Install your plugins

There are a number of plugins that are incredibly useful that I tend to install by default each time I create a new site. In the download files I have provided a plugin folder where you will find a number of txt files that contain the plugins you will need for this tutorial. Open the txt files one by one, and install the plugins by going to your Admin > Plugins tab. Just copy and paste the text into the field, and hit upload. You will see a preview of the plugin. Scroll down and click Install. You will then see your plugin title, author, and description. By default, the plugins are NOT active until you click “no” under active to switch it to “yes.” Do this with all of the plugins provided in the plugins folder.

Create your forms

Forms work in one of two ways:

1. As a reusable snippet of information.

Your header, footer and navigation are likely to be the same on every page, so you would create this as a form, which you would then call into your page template.

An example of this type of form would be the header form, which you will find in the forms folder of the tutorial download. In your textpattern backend, go to Presentation > Forms, and create a new form. Call it header, and choose “misc” for the type. Copy and paste the following code into the body of the form and save:

 <div id="head">
<h1><txp:site_name /></h1>
<txp:section_list wraptag="ul" break="li" include_default="1" default_title="home" sections=", about, work, blog, contact" active_class="active"/>
</div> 

What this does it creates a div with an ID of head, uses your h1 tag to call your site name, and creates your main navigation. <txp:section_list /> creates a list of all the the site sections. What I have done is narrowed the selection down so it just calls the default section (while naming it “home”), the about section, work, blog and contact. It will wrap the entire list in a “ul”, and wrap each individual section with a “li”. It will also automatically add a class of “active” to the current section’s li. If you want more flexibility with your menu, you can always hard code it with HTML, however, this <txp:section_list /> tag is usually all you really need. By default, the section_list ul is assigned a class of .section_list.

2. It tells an article how to behave

One of the most important tags in your page template will be the <txp:article /> tag.

The following snippet:

<txp:article form="single" listform="default" />

basically means: display the article using the form named “single” if you are on an individual article page, and using the form named “default” when you are displaying a list of articles.

In your Presentation > Forms, the “single” form could look like this: (which would just display the title and the body of the article)

 <h3><txp:title /></h3>
<txp:body /> 

while the “default” form could look something like this: (which would display the title, and excerpt, with a link to the full version of the article)

 <h3><txp:title /></h3> <txp:excerpt />
<p><a class="more" href="<txp:permlink />">read more</a></p> 

A list of the most basic and useful forms are provided to you in the forms folder in the download for this tutorial. Create all of them in the Presentation > Forms. If you notice that some of the forms already exist, just override the textpattern defaults with the ones i’m providing. You should have the following forms (in brackets is the “type” you must select for the form):

• portfolio_listing (article)
• portflio (article)
• intro (article)
• single (article)
• subnav (article)
• article_listing (article)
• default (article)
• head (misc)
• foot (misc) – make sure you add your own copyright info
• meta (misc) – make sure you add your own meta data in this form!
• excerpt (article)
• (article)

Set up your page templates

I have created very simplified versions of the textpattern defaults, which you can build upon as you get more comfortable. In the Pages folder, you will find 3 files: default.html, archive.html and home.html. Override the textpattern defaults with the ones I am providing to you. Make sure you go back to your sections, and tell the default section to use page home, the blog page should use archive, and the rest should use default. You must hit save after each change, you cannot change multiple sections at once.

Set up your style

I have created a master style sheet based on Google Blueprint CSS and incorporates some of the Textpattern defaults. Copy the content from the screen.css file provided in the Styles folder and paste it into your default styles tab under Presentation > Style.

Add your portfolio

I have created this portfolio with certain defaults, to help you get a feel for how textpattern works. Once you understand the basics, you should feel free to use your own image sizes, css, etc. As a basis, portfolio images should be sized to maximum width of 620px. Upload a few of your own images (i’ve included a few placeholder images) through the content > images tab. Specify a size of 300px wide by 200px tall for your thumbnail. Click “crop” to avoid the image being squished to fit your dimensions. Hit save once you are finished. There are additional plugins which are fantastic for offering advanced image editing; if you are feeling adventurous, I highly recommend this plugin: ebl-image-edit, which will allow you greater flexibility for creating thumbnails and cropping, etc. Once you have uploaded an image, you will notice that Textpatern automatically assigns the image an id number. Take note of the id number, as that is how you will refer to your images in the future.

Head over to the Content > Write tab to write your first article. Give it a title, put a description in the body. On the left, click “advanced options” and under article image, enter the id #’s (separated by a comma) of the images you wish to be associated with this article. Then, assign the article to the “work” section. When you are finished, hit “publish.” Continue to write your articles, assigning your images to each article. When you have written a few articles, you should click “view site” in the top right of the textpattern window. I tend to leave one tab with the textpattern backend open, with the live site in another, so I can easily refresh and see any changes (or errors!)

You should see something like this:

This is basically the work page in its “listform.” If you click on any of the thumbnails or article titles, you will see the “individual article,” which should look something like this:

If you take a look at the code in the page template for work, you will notice this textpattern tag:

 <txp:article listform="portfolio_listing" form="portfolio" sort="posted desc" limit="30" /> 

If we analyze the form portfolio_listing, it looks like this:

 <div class="span-8">
<txp:permlink> <txp:upm_article_image type="thumbnail" limit="1" class="border"/>   </txp:permlink>
<h3><txp:permlink><txp:title /></txp:permlink></h3>
<txp:excerpt />
</div> 

This basically tells the page to list articles in the form of a div with a class of .span-8, which contains the “image associated with the article”, in the form of a thumbnail, limit it to 1 image, and link the image to the full version of the article. Underneath the image is the “title” of the article in the style of h3, which also links to the full version of the article. Beneath that, show the excerpt associated with that article.

If you take a look at the form “portfolio”, you should see this:

<div class="span-8">
  <h3><txp:title /></h3>
  <txp:body />
</div>
<div class="span-16 last">
   <txp:upm_article_image />
</div>  

This basically creates a div with a class of .span-8 which contains the title and body of the article. Beside it floats a div with a class of .span-16 last, which contains the images associated with the article. Should you wish for the title to appear above the images on the right, you would simply move the <h3><txp:title /></h3> over to the div with the class of .span-16. These forms basically determine the layout for your articles.

A note about article and article_custom

You will notice in the home.html template, that there are two different ways to call articles: <txp:article /> and <txp:article_custom />. It took me a while to wrap my brain around the difference between the two, but here is how it works:

<txp:article /> will call your full article in whatever form you tell it to use. It is section-specific, which means it will automatically call an article from the section you are currently visiting. You must always have an article tag on your page.

<txp:article_custom /> Think of this as a LIST of your articles, in whatever form you tell it to use. Using this tag, you can call articles from ANY section into a page. For example, one the homepage, I am using the article_custom tag to display a snippet from the work, blog, and articles sections. In the archive template for example, on the left-hand side, I am using article_custom to display a full list of all articles posted to the blog page (in the form of subnav), and I am using the plugin “rvm_if_this_article” to automatically detect the current article and make it active.

Create your contact page

You can use the plugins provided (zem_contact_lang and zem_contact_reborn) to create a contact form on your contact page. If you have already installed the plugins provided, and wish to use the contact form, copy and paste the following details into the body of a new article. To avoid formatting with textile, (textile will automatically render things in paragraphs) put a space before each line. Putting a space tells textpattern to format as is, with html, not textile.

<txp:zem_contact to="recipient@example.com" label="">
<txp:zem_contact_text label="Name" break=""/>
<txp:zem_contact_email label="Email" break=""/>
<txp:zem_contact_textarea label="Message" rows="10" cols="23" break=""/>
<txp:zem_contact_submit label="Send" />
</txp:zem_contact> 

In the excerpt, paste any information you wish to be on the left hand side of the page, such as links to your facebook, twitter, or other profiles. And/or you could place an image here; it’s up to you. Assign the article to the “contact” page, and publish.

Create your about page

Create a new article for your about page. In the body write your bio. In the excerpt, place your photo (or other additional information you wish to provide). In order to call an image, you would write the following: <txp:image id=”#” /> and of course, replace the # with the proper image id number. Assign the article to the about section and publish. If you want to change how this page is displayed, you can edit the form named about.

Create your blog page

There are a million and one ways to organize your blog, and I am just demonstrating a very simplified way, since this is probably a whole other tutorial.

Write your blog article. Add an excerpt (usually the first paragraph of your blog). Publish it to your blog section. (You can feel free to create categories, and assign your article to categories, but I won’t get into how to navigate by category in this tutorial- stay tuned). When you click on the blog page, you should see a list of your articles in the form of a Title with an h3 style, followed by the articles’ excerpt. You can click on the title to reach the full version of the article. You will notice a list of your blog articles on the left. I have limited the page to 10 articles on the listing page. When there are more than 10 articles, the page will display a link on the bottom that says “older” and “newer”. This page will always display the most recent articles first. Should you wish to change the order, you can change the timestamp of the article. Click on the article you wish to edit, and on the bottom right you will see a link that says “more.” Click that and you will notice that you can manually reset the timestamp. Hit save. Obviously, this is somewhat of a temporary solution for a blog, since having many blog postings would create quite a long list on the left. Stay tuned for an article on navigating your blog by category. If you wish for comments to be allowed, you must turn them “on” in the actual article itself. On the right hand side of the article page, you will see “allow comments.” Choose yes or no.

Bring it all Home

Now it’s time to create your homepage.

Create an article that will be an introductory paragraph on the homepage. We are using the form “intro” on this article, so it won’t display the title. If you want this article to use a title, change the form in the tag to “single” instead of “intro”. To clarify, you are looking for this tag in your home page template:

<txp:article_custom status="sticky" sort="posted asc" form="intro"/> 

Otherwise, use the heading of h3 in your body by typing h3. (with a space after the period) before your copy. (As opposed to wrapping your copy in <h3> tags) On the right, choose a status of “sticky”. We are making this article “sticky” because we don’t want it to be affected by newly written articles- it is more or less “static” content. Your work articles will always be displayed with the status of live, and the homepage will always display the most recent work.

You will notice in the “home” page template, that there is this tag: <txp:image id=”3″ />. Replace this number with the # of the image you want to appear here. The size is set to 940px wide by 350px high. Upload an image of that size through your images tab, and then replace the number in that tag with the appropriate id #.

Also on the homepage is a snippet from the most recent blog posting. If you want to change how the blog appears, you must edit the form “article_listing”. Keep in mind, this will change how your blogs appear on your blog page as well. If you wish for your blog to appear differently on the homepage than it does on the blog page, simple change the form used in this tag on your home template form:

 <txp:article_custom form="article_listing" section="blog" limit="1" sort="posted desc"/> 

Try it out!

I’ve provided templates/forms/css to you to help simplify some of Textpattern’s funcionality, but its really up to you to make it work how you want it to. It is a very powerful CMS, and I would recommend looking through some of the textpattern tags to see what is available. There are many powerful “if” statements that provide even greater flexibility. Feel free to change any of the pages/forms/html and css I have provided to tailor it to your own needs. There are tons of resources out there to help you understand how to use it better. I highly recommend setting up a test site where you can play freely and experiment. There are so many different ways to work with textpatterns functionality; this is just the tip of the iceberg! If you think you might want to consider textpattern as your cms of choice, I recommend checking out the following sites:

• http://www.txptips.com
• http://www.textpattern.com
• http://www.welovetxp.com
• http://www.textpattern.org

Stay tuned for articles on how to build an extremely easy to update gallery page with thumbnail and captions, as well as category-based blog navigation, and easy nested sub-menus with automatically detected active class.

This is my first official “tutorial”, so if anything is unclear, feel free to post your comments/questions in the comments below, and I will do my best to answer any questions. I am also open to any feedback you may have as well, or suggestions for future articles.

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Create a Simple Portfolio Website and Blog with Textpattern

• http://guides.rubyonrails.org/
• http://www.rubyonrailstutorials.com/
• http://railstutor.com/

And if you need more help, you can hit the #railsbridge channel of freenodeIRC.

So what are you waiting for? Lets get started with creating our basic rails application!

Getting Started

What is Ruby

Ruby is one of the easiest scripting languages I have ever seen; simple enough for non-tech people, powerful enough for advanced programmers and best of all, it doesn’t have a complex syntax or keywords to be memorized. Instead it is written in a simple English syntax.

What is Rails

Rails is a web development framework written in the Ruby language, which has a general MVC (Models, Views, Controllers) type of structure to make everything simple for the developers. It allows you to write less code but accomplish more than most other languages/frameworks.

Rails MVC Architecture

Rails has a MVC (Models, Views, Controllers) architecture and its benefits include:

From Getting Started With Rails

Models

A model represents the information (data) of the application and the rules to manipulate that data. In the case of Rails, models are primarily used for managing the rules of interaction with a corresponding database table. Most often, a single table in your database will correspond to a single model in your application. The bulk of your application’s business logic will be concentrated in the models.

Views

Views represent the user interface of your application. In Rails, views are often HTML files with embedded Ruby code that performs tasks related solely to the presentation of the data. Views handle the job of providing data to the web browser or other tool that is used to make requests from your application.

Controllers

Controllers provide the “glue” between models and views. In Rails, controllers are responsible for processing the incoming requests from the web browser, interrogating the models for data, and passing that data on to the views for presentation.

Welcome to Rails!

Now lets create the sample ‘Slambook’ Application.

Requirements:

(Note: I will be using ubuntu (linux) and Postgres for building my rails application, but you can also install rails on your Windows or Mac machine as well.]

Once you have everything installed, we can start creating our rails application. To begin, open a terminal (Console, Command Prompt, etc) and type the command:

 rails slambook 

For this example we will use ’slambook’ as the name of the application which we will build. As soon as you hit enter, you will see the scripts flow in your terminal creating a bunch of files (as seen in the picture below):

These are the files which rails automatically generates to create the framework for our application.

Now just change the directory to our application using:

 cd guestbook 

and feel free to explore all the sub-directories and the files inside it to get an idea where the code lives.

Now, lets test if your rails application is working by using the command:

script/server 

Open your favourite browser and type http://localhost:3000/ in the address bar and press Enter.

If you see a page similar to the above image, then your first rails application works fine (pat yourself on the back, you got it right)!

To start off, we are going to create the needed controller, model and views for our guestbooks post functionality which allows your friends to sign your ’slambook’.

Using the command:

 $script/generate scaffold post name:string address:text dob:date desire:text interests:text hobby:text signature:text 

Scaffold command creates a CRUD (Create, Read, Update, Delete) interface for your app ( a quick way of creating the MVC automatically). Alternatively, you can also create your controller, model and view manually using the command

 $script/generate controller <controller name> // for creating controller and views 

 $script/generate model <model name> // for creating model 

Here we are telling rails that we want code generated to handle a “Post” model, which has a string type for name and text for address, date for dob and so on. Notice this will generate some more files, one of which is the database migration file found inside the db/ directory

This is how our first migration file looks (slambook application):

The migration files are used for managing the CRUD (create, read, update and delete) activities of the database. If you haven’t created your database yet we can do it by a command:

 $rake db:create 

Now you might wonder how rails connects our database, and for this purpose we provide our database information in the database.yml file which is found inside the config/ directory:

This is how the database.yml file looks. We mention our database name and user details for rails to make the connection.

Since now we have recently created a new model for Post, a table must be created in our database and requires that we upgrade the database using this command:

 $rake db:migrate // (instead of creating/updating the database table manually) 

This updates the database with the information from the migration file.

(Note: when this command is executed, the migration file inside the db/migrate/ directory say 20090718013114_create_posts.rb is used as an reference for updating the database)

Now lets checkout what we have done so far:

 $script/server 

As before, open your browser and type http://localhost:3000/posts in the address bar and press Enter to see your application:

If your page looks like that, then shout “Wow! I have created my first rails application!”

The page at http://localhost:3000/posts shows the list of post made in your guestbook. Note there you have a link “New Post” which links to the the page at http://localhost/posts/new where your friends can sign your guestbook. You must wonder how these pages were created, so take a look at the app/views/posts directory which contains the html pages that were created by the scaffold command. These html pages have .html.erb extension which means ruby code can be embedded in your html files.

Now lets create a home page for our ’slambook’ application:

 $script/generate controller home index 

This creates a controller “home” along with views in the app/view/home directory. Rails will create several files for you, including app/views/home/index.html.erb file. This is the template that we will use to display the results of the index action (method) in the home controller. Open this file in your text editor and edit it to contain the code that you want to display in your index page:

 <h1>Magesh's Slam-book or Guestbook</h1> <%= link_to "View my book", posts_path %> <%= link_to "Sign my book", new_post_path %> 

The last two lines have added two links in my home page, one for people to view all the posts in my slambook and the other for new friends to use to sign my slambook.

tag is used to display the link. posts_path links to the posts/index page and new_post_path links to the posts/new page.

I suggest you also open the other .html.erb files in app/views/posts directory like index.html.erb, show.html.erb, edit.html.erb and new.html.erb to have a look around. Their functions are described in the file posts_controller.rb (controller) inside the app/controller directory.

Dont get confused with the above image, I will tell you how it works:

Lets take the index method first:

def index @posts = Post.all respond_to do |format|
format.html # index.html.erb
format.xml { render :xml => @posts }
end

@posts variable stores all the posts and format.html is used to render the index.html.erb file in the app/views/posts directory.

Similarly the other methods such as new, edit and show are created. Notice that the methods inside the posts_controller.rb file are related to the files inside app/views/posts directory.

The show method renders the app/views/posts/show.html.erb file and in the same way the edit method renders the app/views/post/edit.html.erb file.

When you hit http://localhost:3000/ in your browser you should get the rails default page instead of our home page. That is because rails has created a default index.html page in the public directory. Since we want to use the home controller to show the index page instead of the rails default page ( public/index.html ), we must delete that public/index.html file first:

 $rm public/index.html 

and then tell rails to point to home controller as the default index page. That is done by editing the config/routes.rb file (rails routing)

Rails routing?

You can learn more about routing by reading Rails Routing from the Outside In.

Edit config/routes.rb in your favorite editor (I prefer emacs)

 ActionController::Routing::Routes.draw do |map|
map.resources :posts
map.resources :home
map.root :controller => "home";
map.connect ':controller/:action/:id'
map.connect ':controller/:action/:id.:format'

Note: Whenever a controller is created we need to inform rails about it using the map.resources : which creates the url say http://localhost/ in our application.

Also check out the 4th line: map.root :controller => “home” tells rails to load the home controller for the default home page.

Now visit http://localhost:3000/ and you should see our new home page:

Conclusion

So this is just the skeleton of our application. We obviously should add CSS to design our rails application to make everything look better!

I hope this helps you start Ruby on Rails with ease! If you have any queries or are facing any problem while trying out this on your machine please feel free to shout your comments below. ;)

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Creating Your First Ruby on Rails Application From Scratch

Introduction

In the world of web development, when building a blog, you don’t always want to refer to a slow, over-featured blogging engine like Wordpress. Thankfully, there is a solution, and its name is Chyrp. Chyrp is a blogging engine that is designed to be extremely lightweight, while still retaining functionality. Alex Suraci, the developer behind Chyrp, codes it in Twig, a language specifically created for this project. The Twig is then put through a compiler and its output is solid PHP.

Before we start, it is important to know how Chyrp is extended: Feathers extend post formats, Modules add functionality, such as a commenting system, and Themes change the look and feel. Keep this in mind.

Interested? Well then, let’s get started!

Installation

Download Chyrp, and open up the folder Chyrp v2.0, which should be in the same directory as the archive. Select all the contents and copy and paste it to a directory on your web server (for the purposes of this article, we’ll be using the /chyrp/ directory). Now would be the time to read the COPYING file, so you don’t break any copyright laws. You can delete it or keep it, along with the README.markdown file. If your server isn’t already started, start it. Go to http://localhost/chyrp/ (Or whatever address you use to access your testing server) in your web browser and you should have two errors at the top of the browser window: one for the .htaccess file, and the other for permissions.

Go ahead and create the .htaccess file with the contents it shows, and save it in the /chyrp/ directory. You also need to CHMOD the /chyrp/includes/ directory to 777. This means changing the permissions to all read and write. Once you’ve done that, refresh the web browser page. Now, go ahead and fill in your database information. In this article, we’ll be using MySQL.

Back at the installation screen, insert your database information. The host is usually localhost. As for a table prefix, we can leave that blank, unless we’re installing multiple instances of Chyrp on the same database.

Once you filled out the form, hit Install. It fills the database with the information and configures the files within the instance. When it is complete, this page will show:

So, delete install.php within /chyrp/, as it poses a security risk if you keep it. If you speak German, you’re in lucky, because that is the only language pack available at the moment. So now, click Take me to my site! and you’ll be taken to the home page.

As you can see, there are no posts. Go to the sidebar and click Login, and use your credentials from before. Once that is done, a toolbar will appear in the top. Click the Admin link and you’ll be taken to the backend.

Writing in Chyrp

When you open the backend (it is located at /chyrp/admin/), the Write section is automatically visible. And because Chyrp is a blogging engine, you can make posts and pages. Posts can come in many different forms, such as photos, videos, and plain old text. These different forms come in extensions called Feathers. If you add a photo, you’ll need the photo Feather in order to do that. The text Feather already comes with Chyrp, and is already activated. The photo, video, link, audio, quote, and chat Feathers already come with the installation, but are not yet activated. We’ll go through activating them later.

To create a post or page, just select the type on the tabs and type up what you’d like to say. If you click More Options you can choose a permission status, slug, trackback, timestamp, and pinned status (whether or not you’d like it as first post, no matter what). Once you’re done, you can save it, or Publish it. Once you hit Publish, Chyrp will take you to the home page, where you can view your post. It’s just that easy!

Manage your Install

Head back to the backend and click on the Manage tab, near the top. This will bring you to this page:

From here you can manage everything about your install. If you click one of the tabs near the middle of the page, you can select what you want to manage. As you add Modules, more tabs will appear.

Modules are ways to extend your install. For example, one Module creates a commenting system, and another allows you to cache pages. We’ll get into this later.

What you need to focus on in the Manage section is the Groups tab. This allows you to change permissions for groups. Currently, you are part of the Admin group. Click on the edit link (it’s on the right side) and you’ll be taken to the page for editing group permissions, as well as the name of the group. Click Save when you’re done.

Change the Settings

The next navigation option is Settings. Under General, you can change your blogs’ name, description, and other settings. Under Content, you can edit posts per page, uploads path, and allowing XML-RPC support. Then, in Users, you can allow r disallow users registering themselves, the default user group, and what group Guests are in (you can even allow all un-registered guests to have Admin permissions, though it is not suggested). Finally, under Routes, you can allow clean URL’s, which will make the URL’s formatted as stated in the form below (I highly recommend it—who wants a URL with a question mark in it?).

Extending your Install

The Extend section is very important. Extensions are what make Chyrp so very powerful and functional. Modules are very powerful, and the ones that are made by the head developer come with Chyrp. Those are:

• Textilize
• SWFUpload
• Paging
• Aggregator
• Tagginator
• Read More
• Comment System
• Markdown
• SmartyPants
• Cacher

All these do exactly what they’re named for. To activate them, just drag it from the red zone into the green zone. When you do that, a dialog pops up, reminding you to change the permissions. Once you’ve added all the Modules you want, go back into Manage > Groups and change the permissions so you can manage the Modules.

Now, go ahead and go into the Feathers section. As you can see, the following Feathers come with Chyrp:

• Photo
• Video
• Link
• Audio
• Quote
• Chat

Plus, the Text Feather, but it is already activated. To activate them, it is the same action as before. If you enable the Photo, Video, or Audio Feather, then you need to create a uploads directory in /chyrp/ and CHMOD it to 777 so you can upload media.

And finally, Themes. The theme that comes with Chyrp is called Stardust. It may be fine for a casual blogger, but for a designer, like me, you need to design your own. That will be in a follow-up article.

Downloading Extensions

There are some more extensions on the Chyrp site. There are not many, but the user base is growing rapidly, and so is the development base. To add Feathers, Modules, Themes, etc, just download it and extract the archive to /themes/, /modules/, or /feathers/, respectively. Then, just go into the backend and activate it. It’s just that simple.

Chyrp vs. Wordpress

You may be questioning, “Why Chyrp? Why not just go with the popular solution: Wordpress?” Well, why Wordpress? There are a lot of functions in Wordpress that you’ll never need or use, so why have them. A fresh Chyrp install is bare bones, and you’re free to install what you need. Plus, Chyrp is a lot faster than Wordpress, on the front and backend.

As well as speed, Chyrp has better code than Wordpress—Alex (founder and sole core-developer) uses Ruby on Rails and Python helpers to have perfect code that is easy to edit.

While retaining functionality, Chyrp is more flexible than Wordpress. It can do a lot of different functions, and is easy to mod to your hearts content.

So why use Wordpress?

The Chyrp Community and Support

Chyrp has a strong community and support group. In the Discuss section of the Chyrp site, you can ask for help or just discuss… whatever. Or, to get instant help, log on to good ol’ IRC on irc://freenode.org/chyrp (that would be irc.freenode.org as the server, then #chyrp as the channel).

In the next article, we’ll be building a custom theme!

Sponsored by

Advertise on Fuel Your Coding.
Fuel Your Coding 2009 cc (creative commons license)

Getting Started with Chyrp