A Quick-Start Guide to Writing Applications in Vanilla

While a plugin can be written in a single file and serve a single purpose, applications contain many folders & files, and represent large groups of functionality. The easiest way to get started writing an application in Vanilla is to create a copy of the "skeleton" application that is bundled with Vanilla and name the folder after the application you are creating.

Getting the Required Files

The skeleton application represents the folder and file structure you need to get started with a new application in Vanilla. I am going to create an extremely simple application to serve as my "welcome" website here on my local installation of Vanilla. So, I've copied my skeleton folder and renamed it to "welcome" in the applications folder of my Vanilla installation.

Defining your Application

Before you can go any further, you need to define some information about your application so that Vanilla knows how to handle your application as it is enabled and disabled through the Vanilla web interface. So, I open up the /welcome/settings/about.php file and edit it like this:

 "This is my new 'welcome' application where I welcome people who access my Vanilla installation.",
   'Version' => '1.0',
   'SetupController' => 'setup',
   'Author' => "My Name",
   'AuthorEmail' => 'My Email',
   'AuthorUrl' => 'http://my.domain.com',
   'License' => 'GPL'
);

There are a bunch of other settings you can define here that do all kinds of awesome things (like running setup and teardown scripts when the application is enabled or disabled by Vanilla). If you want to find out more about those, read the full documentation on applications.

At this point my application is almost ready to be turned on. First I need to rename the default "appcontroller" that all of my controllers in this application will be extended from. It is currently still named after the "skeleton" application, so I open up /welcome/controllers/appcontroller.php and change the class name from SkeletonController to WelcomeController.

Now I can sign into my installation, browse to the applications screen, and turn on my Welcome application:

Creating a Controller and Related Views

So, we've got an application up and running, but it doesn't do anything yet. So, let's make a controller that can show some simple pages. I browse to my /welcome/controllers/ folder, create a file called homepage.php, and fill it with this:

Render();
   }
}

The first line is a security precaution that helps to protect our code by making sure that the file isn't loaded directly through a web browser. The really important part is the class definition. We create a new Controller class called HomePageController, and extend it from the WelcomeController class that we defined in the last step. We've only given it a single "Index" method, and all it does is call the "Render" method.

I can browse to this page right now on my server by going to http://localhost/vanilla/homepage/. However, when I do, I get an error:

That's okay, this is happening because I still haven't defined a view for this controller's method. I'll do that now by going to /welcome/views/ and creating a folder called "homepage" within it, and creating "index.php" within that:

Next I edit the index.php file I just created and add the text "Hello World!". Now if I refresh my browser, I can see my message:

That's it. I can add more methods to this controller as long as I create related views in my /welcome/views/homepage/ folder. In this way you can add as many controllers and views as you like. Of course you can do much more than just simple pages, but this is really all you need to know in order get your own applications up and running.

More Information

• Read all of the general development topics in this documentation
• Detailed information on applications in vanilla