Building the Weather plugin

In this tutorial we will describe the process of building a simple Weather plugin. It demonstrates the basic principles of October extensibility. The weather information is loaded from Open Weather Map.

The plugin doesn't work with the database and doesn't implement any complex business logic. It hosts a single CMS component that displays the current weather for a specific city on a page. The component has a number of properties that could be configured either with the Component Inspector in the CMS back-end or manually, in the page template file. You can view the plugin source code or download it form the GitHub repository.

Plugin directory layout

We started with creating the rainlab/weather subdirectory in the October's plugins directory. The rainlab part is the author name and the weather is the plugin name. Every plugin requires a registration file, so we created the Plugin.php script to the plugin directory. We also created the components subdirectory for hosting the component script and partials and the assets subdirectory for storing the plugin's CSS files and images that are used for styling the weather widget on the front-end. This is the directory layout:

plugins/
rainlab/
weather/
assets/
components/
Plugin.php

Registering the plugin

The plugin registration is done in the Plugin.php file. The Weather plugin is very simple, we only need to return the information about the plugin itself and about components it defines. The next example shows the entire contents of the Plugin.php file:

Building the component

The component class is defined in the Weather.php script that we added to the rainlab/weather/components directory. In the component class we prepare the information about the component, define its properties, provide methods for loading the country and state lists, inject the weatherInfo page variable and load data from the Open Weather Map API.

The next snippet shows the component registration and property definition code:

The most interesting part here is the defineProperties() method. As the name suggests it defines the component properties that could be configured with the Component Inspector. The country, state and units properties are drop-down lists. The units drop-down list is static - its options are pre-loaded when Inspector displays. Options for the country and state lists are loaded from the server, and the state list depends on the current country - when the current country changes the state list updates.

To provide the dynamic loading of the country and state options we must define the getCountryOptions() and getStateOptions() methods in the component class. For the simplicity we load the country and state list from a JSON file that we put to the data/countries-and-states.json file.

The getStateOptions() method extracts the selected country code from the POST data. The Inspector POSTs the property values when it requests the dynamic option list from the server.

The remaining part in the component is loading the weather information from Open Weather Map. It's done with the info() method that loads the component property values and builds a URL string. It uses the file_get_contents() function to request the JSON file, parses it and returns the parsed object:

Subscribe to get free tutorials, plugin reviews and news about October CMS

Latest from the blog

In this post we want to reveal some details about October Pond, which we are building at the moment. If you haven't yet heard about Pond, it is an installation manager and deployment tool for Windows and Mac.