Whenever I start looking into how an application works, the first thing I do is browse through the files & folders to see where everything is. And, interestingly enough, where the files and folders reside in Garden have a lot to do with how Garden works.
[Edit – After some good suggestions in the comments of this post, I’ve made some changes to this post and updated appropriately.]
Let’s start by looking at the root folder of my development version of Garden:
Here’s a breakdown of what each root folder/file is:
applications: The applications folder contains folders, which in turn contain all of the files specific to each application. As you can see, I’ve got four applications listed here. The “garden” application is the base application of the framework that handles signing in, user, role, permission, plugin, and application management. The “scaffolding” application is the first application that I developed with Garden, which you may remember from a few months ago. Sadly, after months of changing how the core Garden libraries work, the Scaffolding application is now very broken. The “skeleton” application is a set of folders and files that represents an empty application. My idea with Skeleton was to have a set of files that a developer could copy as their starting point for a new application (You could also call it an “application template”). The “vanilla” application is, of course, Vanilla!
cache: The cache folder is *currently* used as a general purpose cache. At the time of this writing, it contains cached application settings. These are things like mappings of class names to their location on the filesystem, mappings of locale sources (ie. all “en-CA” definition files from all plugins and applications), etc. There may come a time when there are entirely cached pages or page views, but that will not be present at time of release.
conf: Anyone familiar with Vanilla 1 knows exactly what this folder is. The conf folder contains all of your custom configuration settings in a number of different php files as associative arrays. This folder and the cache folder will need write permissions for PHP.
js: Obviously, like Vanilla 1, this is where all of the javascript in Garden resides. The only difference from Vanilla 1 is that there is a “library” folder within the javascript folder that contains jquery libraries – some of which I’ve written and others that come from the jquery website.
library: This is the core libraries for Garden (aka. “where the magic happens”).
plugins: This folder is the equivalent of the extensions folder in Vanilla 1. It contains folders which, in turn, contain all of the files for a specific plugin. I’ll be getting into Plugins in another Garden Preview.
themes: Similar to themes in Vanilla 1, but far more flexible. I’ll be getting into themes and theming in another Garden preview.
.htaccess, INSTALL.txt, LICENSE.txt: These three files should be self explanatory.
default.php: This is the file that all requests to garden are made through.
So, now that you know what the root folder looks like, let’s take a look at one of the application folders. I’ll use Skeleton since it is a basic representation of any application:
controllers: As previously mentioned, Garden is a Model-View-Controller (MVC) framework. The controllers folder contains all of the controllers for this application. Controllers handle all page, partial-page, rss, or any other kind of requests, and act as an intermediary between the models and the views.
design: Obviously there are themes available in Garden, but each application can also have it’s own set of css and image files – those will be placed in the design folder. I’ll get into more detail on this folder when I talk about theming in another Garden preview.
js: Javascript files specific to this application.
locale: Localization files for this application.
models: Models in garden will interact directly with your data sources (databases, flat configuration files, etc) and perform get, set, and delete operations. As previously mentioned in the first Garden preview, there is a general purpose model that Garden provides so that you don’t need to create a model class to represent every data structure. However, there are times when you need to customize a model to suit the needs of your application. When you do, this folder is where you’ll put those models.
settings: The settings folder for each application is the equivalent of the “appg” folder in Vanilla 1. It contains the default application settings for that specific application. In Garden, it also contains the about.php file – a file which defines all of the information about this application. That information includes things like: Application name, version, author, requirements, licensing info, etc.
views: Of course, this folder represents the Views in the MVC pattern. This is where all of your xhtml for the pages will go, and it relates directly to the controllers that handle them.
bootstrap.php: The bootstrap file for each application is included before any of the major libraries in Garden are loaded. So far, with the three applications I’ve been working on, I haven’t needed to use it very much. But I’m keeping it there just-in-case a need arises.
Conclusion
There is still a lot to explain, but I’ve given you a breakdown of where things are in Garden. In the next Garden Preview I’ll be diving further into the root default.php file, the application request dispatcher, the MVC folders, and explaining how views, master views, and page requests are handled.