LRC Drupal Template Documentation

The LRC Drupal Template provides a starting point for building a local environmental record centre website which features a standard menu structure for you to add content to, online recording and reporting of wildlife records and simple functionality for supporting local recording groups. Wildlife recording functions are provided by integration with the Indicia toolkit.

This guide introduces the basic skills you will need to manage and build upon your new website. It contains tutorials which are designed to be run through in a development or testing environment but the principles can then be applied when you configure your live environment.

Installing the LRC Drupal Template

Preparing to install the LRC Drupal Template site

There are a couple of different ways you can set up the LRC Drupal Template website. Before you start though, you need a webserver ready to install onto. This might be a local machine you are using for development, your existing live web server, or a virtual server or shared web space rented from an Internet Service Provider. The webserver can run on any operating system and must meet the following requirements:

• Support for PHP 5.2 or higher (5.3+ preferred)
• At least 64MB memory limit for PHP, 80MB+ preferred
• MySQL database version 5
• Support the cUrl extensions for PHP to allow it to communicate with the BRC Community Warehouse.
• A tool allowing you to access the MySQL database server such as PhpMyAdmin, MySQL Query Browser or CPanel

If you are installing a local development server, then installing a web-server stack makes the setup process relatively easy. Here are a few examples for your consideration:

Windows

• WampServer

Mac

• MAMP

Any operating system

• XAMPP

Before starting the installation process, you will need to create a MySQL database ready for Drupal to use. The installation documentation for Instant Indicia (which is a Drupal 6 product) cover the steps you need to create the MySQL database. Alternatively, any tutorial on installation of vanilla Drupal will explain the steps required, as the LRC Drupal Template has no special requirements of the MySQL setup.

Installing the LRC Drupal Template from backup

The LRC Drupal Template can be installed from a backup of the site. This is the simplest way to get started. The site backup is provided as 2 files:

• lrctemplate.zip - a backup of the folder structure required by Drupal. This is the same as a download of Drupal from drupal.org but with the addition of a number of modules and theme files required by the LRC Drupal Template.
• lrctemplate.mysql.gz - a backup of the MySQL database.

The first step is to unzip your lrctemplate.zip file into the place you want your website files to run from, as dictated by the web server setup. For this illustration, I’ve made a folder called lrc in the web root folder of an installation of XAMPP running on OS X. This means that my development site copy will be available at http://localhost/lrc. Into this folder, I’ve unzipped the lrctemplate.zip file so that the folder structure is as follows:

Note that I’ve also created a MySQL database called lrc and user account ready to install against as described in the previous step.

File permissions

Depending on your operating system, you may need to change file permissions to get Drupal to run properly. The Drupal folder and its contents should generally be all read-only to the web server process with a few exceptions:

• The sites/default/files folder should be writeable.
• The sites/all/modules/iform/client_helpers/cache folder should be writeable.
• The sites/all/modules/iform/client_helpers/upload folder should be writeable.

You should also at this point copy the file default.settings.php and rename the new file settings.php. This latter file will need to be writeable during the installation process only.

Drupal installation

Now you are ready to run the Drupal installation script. This process is exactly the same as any other installation of Drupal, so you can refer to the standard documentation. Follow the steps described for Drupal 7 installation. Don’t forget to make a note of the site maintenance account details you specify in the installation wizard, as these are used to gain full access to the site.

Once the script has completed, you’ll be presented with a Visit your new site link so click on this to enter the site proper.

Restoring the site database backup

At the moment, you’ve got a basic installation of Drupal with the default Drupal theme, with no content, menus, custom modules, online recording facilities or themes setup. Fortunately all the files required for all this are already in place, so we just need to restore the MySQL database which holds all the configuration information required. The backup and restore process used here depends on a module called Backup & Migrate so the first thing we need to do is to enable this module.

1. Click on the Modules menu item in the black menu bar across the top of the page. We’ll refer to this as the admin toolbar from now on.

2. You are now looking at a list of all the downloaded modules for Drupal with the enabled modules ticked. There are of course many more modules available on drupal.org. Search for the module called Backup and Migrate then tick it:

   

3. Scroll to the bottom of the page and click Save configuration.

4. Backup and Migrate will add an extra page to your website allowing administrators to backup and restore the MySQL database which drives the website. To access this page, click Configuration on the admin toolbar, then find and click the Backup and Migrate link on the right of the page.

5. We want to restore a database, so click the Restore tab.

   

6. Click the Choose file button then browse to and select the lrctemplate.mysql.gz file.

7. Click Restore now.

That’s the basic install process done. You can skip forward to the Post installation steps.

Post installation steps

Although everything is now installed and in place, there are a few more configuration steps required to get your site up and running.

Configure the Drupal file system

Since the site has been restored from a different environment, Drupal might attempt to save temporary files into the wrong location. To fix this:

1. Select Configuration from the admin toolbar then select File system in the Media section on the left.
2. Clear the Temporary directory box then click the Save button. This lets Drupal work out the best path for temporary files in your environment.

Initialise the theme

The LRC Drupal Template is provided with a custom theme which defines the appearance of the entire site. This theme is highly configurable, so you can change everything from the banner to the fonts to the colour schemes. Although we’ll learn about configuring the theme later, an important step in the installation process is to let the theme write out it’s stylesheet and other files according to the current configuration settings. Don’t worry too much about the details of this yet, just follow these steps:

1. Click on the Appearance link in the top admin toolbar, then click on the settings link for the Indicia default theme:

1. Scroll all the way to the bottom of the page then click Save Configuration. This lets all the settings you can configure on this page be compiled into stylesheets and other site template files.

2. Click the home icon in the top left corner of the page to check that your site is displaying OK.

   

Clean URLS

Drupal allows the URL your pages are accessed via to be made more readable. For example, the URL http://www.example.com/?q=my-page can be rewritten as http://www.example.com/my-page, making the URLs easier to remember. This setting requires a compatible configuration of the web server and may not be possible on all servers. To enable the setting, click the Configuration link in the admin toolbar, then click the Clean URLS link in the Search and metadata section. Your site will either detect that clean URLs are supported, in which case you can just click the Enable Clean URLs checkbox and click the Save configuration button, or if Drupal thinks that clean URLs are not supported then you will be presented with a Run the clean URL test button. Refer to the Drupal handbook for more information in this case.

Cron

Cron allows Drupal to run background tasks such as search indexing. Refer to the Drupal documentation for information on how to set this up.

Initialising Indicia

The LRC Drupal Template site, like all other Indicia powered websites, needs a website registration on the appropriate warehouse, in our case the BRC Community Warehouse. This provides a website ID and website password which your website will need in order to securely communicate with the warehouse’s web services. If you don’t already have these details, then please contact BRC. You can find further notes on this setup task on the Indicia documentation website.

Now, click on the Configuration link in the admin menu bar at the top of your Drupal site and click the Settings link in the IForm section, then fill in the following details:

1. This page has already been configured to point to the BRC Community Warehouse and you can leave the Indicia Warehouse configuration option. If developing locally or using the BRC test warehouse then you can configure the URL to the warehouse here.
2. Set the Indicia Website ID* to your website registration’s **website ID.
3. Set the Password and Confirm password prompts to your website registration’s website password. This should be a secure password as it is used to authenticate record submissions from your website to the warehouse as well as all your site’s requests for report data.
4. The GeoPlanet API Key is used to access the Yahoo! GeoPlanet place searching webservice, a handy addition to your online recording forms allowing people to search for towns and villages near to their sites. Follow the link on the configuration page to access the Yahoo! page where you can register to receive your own key which needs to be pasted into this box. The registration process is free and fairly quick.
5. Bing API Key is only required if you plan to use the Bing map layers. Google layers no longer require an API Key.
6. Map Settings allows you to pan and zoom an example map to show your record centre’s locality. This will then be used as a default setting for recording forms and reports. There is also a list of map reference systems which you can use to configure the default behaviuor of your forms. The default is for British National Grid support only, but you might want to tick the box to enable GPS Lat Long coordinates if you feel that is appropriate for your site.

Tip

If you shift drag on the map, you can quickly set the bounding box of an area to zoom into.

Save the settings page when you are done. Now, we want to check that the settings are OK. Click on the Configuration link in the admin toolbar at the top, scroll down and find the IForm Diagnostics link and click it. You will note a warning about a few possible API keys being missing – don’t worry as these are APIs which we are unlikely to use and where the key can be added to the configuration later if needs be. But, ensure that all the other checks this page outputs indicate success:

The most likely type of failure you might observe at this point is for either the cache directory or interim image upload directories to be not writable by the web server. If this happens then the two folders you need to ensure are writeable are:

• sites/all/modules/iform/client_helpers/cache
• sites/all/modules/iform/client_helpers/upload

If you are not sure how to make these folders writable then it may be best to ask the adminstrator of your server.

Create your wildlife survey

The LRC Drupal Template is provided with wildlife recording forms that capture ad-hoc sightings as well as lists of records. You must create a survey on the warehouse into which records will be stored.

Tip

On the warehouse, a survey means a set of observations with a common purpose and methodology. The survey defines the attributes that are available for recording, for example a bat survey might capture information about the roost, whereas a plant survey might capture a DAFOR abundance. In our case, we’ll start out with a casual survey for ad-hoc sightings, but will learn how to setup other surveys later.

As part of the initial setup required to get the LRC Drupal Template site up and running, you will need to ask someone with access to the warehouse database to clone the template survey for you. The survey must be created first using the warehouse user interface. Setting up the survey’s structure can be done with the following database query which is correct for the live BRC Community Warehouse, replacing n with the ID of the survey you created:

select indicia.f_clone_survey(185, n, 1)

Once the survey exists on the warehouse, we need to link the survey to our recording forms. From your site’s home page, select Wildlife recording from the main menu, then select the Submit a sighting link. This will bring you to the submit a single sighting form, currently incorrectly configured as it needs to be pointed to your survey on the warehouse. Because you are logged in with admin rights, you can access the page’s Edit view from here so click on the Edit tab just below the page title. This shows a configuration form where you can change a huge number of settings about the online recording functionality of the current page. Scroll the page down a bit and in the Other IForm Parameters section, drop down the Survey control and choose your survey. There should only be one available as this will only show the surveys linked to your website registration. Scroll to the bottom and press the Save button when you are done.

Now, repeat these steps, this time for the Submit a list of sightings form.

Basic Drupal Skills

In this section, we are going to take a look at some everyday Drupal skills that you will need in order to populate the site’s content.

Site information

An important step in the setup of our website is to provide basic site information such as the name of the site. Click on Configuration in the admin toolbar then select the Site information link from the System section on the right. Fill in the following settings:

• Site name - the name of your site, which will generally appear in the header area of every page.
• Slogan - only needed if you want a “strapline” under your site name.
• Email address - provide the email address that any emails sent out by your website will come from, e.g. those sent out during the account registration process. It is vital that this email address is from the same domain as the main site otherwise emails are likely to be treated as spam. Generally you do not need to allow users to reply to these emails, so it doesn’t matter if it is actually a real monitored email address. Therefore if your site address is http://www.example.com then a good email address might be noreply@example.com.

Other settings on this page can be left as they are at the moment. Save the configuration when you are done.

Theming

One of the key features of a content management system such as Drupal is that you can control the appearance of the entire site using an easily switchable theme. Site banner, fonts, colours and positions of various components are all controlled using the theme. This approach is a vast improvement over static HTML websites where a change to the site’s page structure requires every page of the site to be edited.

The LRC Drupal Template is provided with a purpose built theme called indiciatheme. This theme has the following features:

• Supports changing the site colour scheme, fonts and many other settings via configuration rather than code.
• Built in support for customising the header/banner images.
• Responsive so it works well on everything from a smartphone to a desktop monitor.
• Some built in styles help it to work well with Indicia online recording.

Having said all this, don’t forget that you can install a different Drupal theme selected from drupal.org or if you are feeling brave, write your own. We’ll stick to customising the indiciatheme for now as there are plenty of online resources for Drupal theming in general when you are ready.

Tutorial - configuring indiciatheme

In this tutorial we’re going to take a tour of the configuration options that are available for the indiciatheme Drupal theme provided with the LRC Drupal Template.

Colours

Although you can of course use the traditional approach of using stylesheets to change the site colours, indiciatheme supports the Drupal Color module (sic) which allows you to take full control over the colours used on your site without touching code via an easy to use configuration form.

Note

The purists amongst you might be quaking at the thought, since a flexible colour system like this must surely place inline CSS code into every web page? Fortunately this is not the case; when you save the colour configuration the Color Module cleverly rewrites the theme’s CSS files with the updated colour information so there is no need for untidy inline style information. It can even regenerate image files used, swapping one colour gradient for another.

The colour settings for your site can be found by selecting Appearance on the admin menu, then clicking settings for the Indicia default theme. Scroll down the page until you find a section called Color scheme. Let’s change the colour of the background behind the main site menu. Simply click inside the text box for Main menu background then use the colour wheel to the right to change the selected colour. If you know the CSS colour code you can type that in directly instead of using the colour wheel. If using the colour wheel, note that the circle of colours is used to set the hue only, you then need to click in the square in order to set the saturation and brilliance of the colour.

Try changing the Main menu background to red so you can clearly see the effect and then save the configuration page. Now, return to the theme settings page as before and try experimenting with the different colour options available to see the effect on your site.

Tip

If you get in a mess with your site colours, you can reset to the default by choosing Whites in the Color set control at the top of the list of colours.

Logo and header

The header of your site will by default consist of 3 components:

• A logo image justified to the left,
• The site name, displayed to the right of the logo,
• A user menu, justified to the right.

The theme also has built in support for a banner image which can be displayed behind the entire header area.

To change the logo, select Appearance from the admin toolbar, then select Settings for the Indicia default theme. Click on Logo image settings to expand this section then untick the Use the default logo checkbox. This shows a control for specifying a path to a custom logo or uploading a custom logo image:

Click the Choose file button then browse to select an image on your local disk. You might want to first download an image to use, e.g. by visiting your existing site and right clicking on the logo, then selecting Save image as.... Once you have chosen an image file click Save configuration to apply the settings changes, then click the home button in the top left of the admin toolbar to check that the site looks OK.

Changing the header image is done in a similar way, except that the Noggin module is used to facilitate this, and some default background header images are provided. Return to the theme’s settings page and this time expand the Header image settings section right at the bottom of the page. In the Selected header control choose the Camera lens on white image. Finally choose Right as the option for Image alignment - horizontal and save the settings, then check it has worked OK as before.

Page width

Another aspect of the site that can be easily changed using the theme’s configuration settings is the page width and behaviour on different devices. Back in the theme’s settings page, you will find the Layout & General Settings section right at the top. There are lots of settings in this section for layouts on different devices.

Tip

Because indiciatheme is based on Adaptive Theme you’ll find lots of useful information on theme configuration in the documentation.

The default behaviour of our site is to use up to a maximum of 1400 pixels width on the page. If the browser is narrower than this, then the page will reduce in width. On your home page, try reducing the width of your browser and see what happens. Let’s change to a fixed width site:

1. On the theme’s settings page Layout & General Settings, make sure that the tab for standard layout is selected.
2. Untick the Set a max width checkbox.
3. Change the Unit option in Set a page width to px.
4. Set the Page width to 1200 then save the form.

Visit your home page and try gradually reducing the browser width. You will see that the page width is fixed to 1200 pixels and as you reduce the width below that limit, a scroll bar appears to allow the hidden page content to still be accessed. Reduce the width of your browser and all of a sudden the browser’s scroll bar disappears. The page reverts to the maximum width behaviour we had before. This is because the theme configuration has different layout settings for tablet and phones. These are triggered based on the browser width so as you reduce the browser width, you trigger the tablet layout to kick in and we’ve not reconfigured that to a fixed width.

If you want to know more about layout options in Adaptive Theme, there is more information in the documentation. Don’t forget that you can install your own Drupal theme as an alternative - indiciatheme is just provided as a quick way to get started. There are lots of other cool Drupal 7 responsive themes around, mostly free. Here are a few good “boilerplates” you might like to check out.

• Omega
• Zen

Reset your site to 100% width and max width 1400 pixels before continuing.

Custom CSS

Another feature of the theme settings page is the ability to add your own custom CSS (cascading style sheets) to the site. If CSS is new to you, then there is lots of documentation on the web such as this to get you started - it’s a worthwhile skill. A nice feature of the Adaptive Theme support for custom CSS is that your styles are included rewritten into the theme’s CSS files, which is far cleaner and more efficient than including the custom CSS in the header of every page.

If you visit your home page and have followed the tutorial accurately to this point, you will notice that the font colour used for the user menu is now inappropriate, since it is overlaid onto the dark background of the header image.

This is a good example of a minor style “tweak” that the custom CSS feature is ideal for fixing. If you want a more comprehensive overhaul of your site’s styles, then this is not the way to do it. You should either write your own subtheme, or use an entirely new theme. So, let’s see how to apply minor CSS tweaks to the site:

1. Return to the theme’s settings page.
2. Scroll down to the Extensions section, then click on the Custom CSS tab.
3. Paste the following into the text box, replacing the existing content.

header#header .menu a {
  color: #FFFFFF;
}

1. Save the settings page and reload your home page to check the result.

Editing content

The LRC Drupal Template site has a menu structure prepared for you, with several blank pages for you to fill in. We’ll start by filling in the Contact us page from the About this record centre menu. The good news is Drupal has built in content editing features and, even better, the LRC Drupal Template already has modules installed to make text editing and formatting even easier.

Select About this record centre then Contact us from the main site menu. This takes you to the blank page provided by the template. Because we are logged in with content editing rights, there is a set of tabs at the top of the page with View and Edit options - these tabs are not shown on the page at all for users who cannot edit the page. Click the Edit tab to access the page editing facilities.

This is the standard Drupal page for editing content. Because we are editing a page (there are other content types), the main things we need to specify are the title and body. Try filling in some body text and experimenting with the formatting toolbar to see how it works.

At the bottom of the page, there are a number of sections for different aspects of the page. Some key ones to know about are:

• Menu settings allows you to add or remove a menu link to a page and to choose where in the menu system it will appear.
• URL path settings allows you to control the path your page is accessed at. Every piece of content in a Drupal site is known internally as a node and is given a unique ID. Therefore by default your page might have a path such as http://www.example.com/node/15 or http://www.example.com/?q=node/15 if clean URLs are disabled. In this section you can see that we have overridden the URL alias to “about/contact” making the equivalent URL http://www.example.com/about/contact.
• Publishing options allows you to set pages as unpublished, so that you can work on them in several iterations before publishing them to other site users.

As with many aspects of Drupal, there are lots of options here which can make things look a bit complex at first. However, the good news is that the Drupal community is a big and helpful place to be - there are lots of tutorials around and people willing to help with your questions. As an example, the nodes documentation has links to lots of useful information on the content editing process.

Drupal Menus

We’ve already encountered the Drupal menu system a couple of times so far in this documentation. Let’s take a look in more detail and pick up a few tips on the way.

Drupal’s menus each consist of a hierarchy of links to various pages on the site. There can be any number of menus in a Drupal site and you have already seen the main menu and user menu running on your template site. Menu’s can be rendered onto the page as a pretty simple HTML list by Drupal, or you can write code or (more likey) install a module which outputs the menu in any way you see fit. Our site already has one such module installed, Superfish, which converts our simple menu hierarchies into nice drop down menus which remain accessible and work well across devices. It’s the Superfish module which lets the menu drop down when you hover on the About this record centre menu item, for example. We also use another module, Special menu items, to allow menu items which don’t actually link to a page such as the menu headers over each sub-menu.

To review the menus available on your site, click the Structure link in the admin toolbar then click the Menus link. This takes you to a page listing the available menus:

There are a few menus here, some created by the Drupal core, some by modules added to our site. We’re only using the Main menu and User menu on our site at the moment. Click the list links link by the Main menu to view the links for our menu. This page shows the complete layout of our menu and provides handy drag-handles so that you can re-order menu items and even move them between different menus.

Have a practice moving menu items around and remember to click the Save configuration button if you want to save your changes.

Adding a footer menu

As Drupal allows any number of different menus, let’s create a menu to appear on our page footer. Return to the page listing the menus (use the site breadcrumb trail, or click Structure then Menus again). This time, click the Add menu button. The menu settings popup which appears is pretty simple, so fill it in to describe your menu. There is no need to worry to much about exactly what you specify here as it is just information for site administrators and won’t be shown to the public. Click the Save button when done.

After saving the menu settings, Drupal takes you to the currently empty list of links so click the Add Link button to start populating our menu. Add a link to the existing Contact us page by filling in the following settings:

• Set Menu link title to “Contact us”
• Set Path to “about/contact”
• Set Description to “Contact this record centre”.

Leave the other settings as they are.

Save the page. Your footer menu has now been created and has a link in it, but if you visit your home page you will find that it does not appear anywhere. That’s because Drupal can’t make assumptions about where to put things based on the fact that we called it “footer”, we have to explicitly tell it where to put the menu. Time to learn about another aspect of Drupal - blocks!

Drupal Blocks

Time for some concepts...

A Drupal theme defines the structure of your pages, such as the page size, banner, column layouts etc. But, the theme has no responsibility for site functionality or content, which is why you can swap a theme on the site and the only thing that changes is the layout and appearance, not the functionality or content. Therefore the theme must also define regions, places on the page where content and functionality can do their stuff. At the most basic level, you might have a theme which defined a page with a banner and a single content region as in the following wireframe:

Of course, a real Drupal theme will be somewhat more complex, with multiple regions on the page such as left and right columns and footer areas and possible multiple layout options as our theme does. But the principle is the same.

So, what goes into a theme’s regions? That’s where blocks come in, they are quite literally the building blocks of the page which are laid out on the page by placing them into the theme’s regions. In fact, the reason why when you look at any page on your site you see the page’s content appear is because Drupal defines a core block called Main page content and by default, our theme places it in a region called Main content.

The purpose of all this was to add our footer menu to the page, so click the Structure link in the admin toolbar then select the Blocks link. This shows a page listing the regions available in your theme and the blocks active in each region. Scroll to the bottom where you will find the Disabled blocks section and within it, the Footer block:

In the Region column of the Footer block, choose Footer in the drop down then click the Save blocks button at the bottom of your page. Visit your site’s home page to check that it has worked.

Well, it’s worked, but in my opinion it doesn’t look very nice. The footer area is a bit too dominant and the “Footer” block title is unnecessary. Follow these steps to tidy things up:

1. Hover the mouse near the right of the footer area and you will see a settings “cog” icon appear, indicating that there is a settings menu you can access for this part of the page.

1. Select the Configure block item in the menu. This is a shortcut to the configuration page for this block, which you could also have reached via the Structure - Blocks page.

2. In the Block title box, enter <none> (including the less than and greater than symbols) and click the Save block button.

3. Now let’s lighten up the footer colour a bit in keeping with the rest of the template. Select Appearance then click Settings for Indicia default theme. Scroll down to the Colour scheme section and change the Footer top and Footer bottom colours to 2 shades of light grey. Since the font won’t show very well now, change the Footer text to a dark colour then click Save configuration and revisit the home page to check that it has worked OK. You could of course continue to enhance the footer area by adding other blocks, or using custom CSS to centre the menu etc.

   

Feel free to experiment! If you want to know more about Blocks, then there are some handy resources online, such as Drupal Garden and the Drupal Community documentation.

Drupal Views

Drupal’s Views module is considered a “must have” module, one of those modules which you end up installing on nearly every Drupal site. In fact, this is so much the case that Views has now been integrated into core Drupal for the upcoming Drupal 8 release. So, what’s all the fuss about?

Views is a Swiss Army Knife for building outputs which include a list of items. These lists of items might be:

• a list of content items such as news articles on your home page
• a page listing recent blog posts
• a list of users
• a gallery of photo content items
• a calendar of diary events
• a list of forum sections or forum posts

Think of Views as a custom report builder, though note that Views works against Drupal content not Indicia wildlife records - we have different methods for reporting on records.

The Latest Images page from NatureSpot is a good example of a Drupal View.

Note

Since views are such a powerful aspect of Drupal, please take the time to read through the thorough documentation on Drupal Garden and ensure you run through the views tutorials on that site.

Drupal Panels

Another workhorse of the Drupal modules library is Panels. Like Views Panels is a module I tend to install on most Drupal sites. We have already seen how the layout of a page can be controlled via a combination of your theme and Drupal Blocks, but this approach works well when the blocks are mostly consistent across the site or section of the site. So, for example the blocks approach is good for setting up a site where the left column always contains a navigation menu, and the footer area always contains a consisten set of links. But what about the scenario where you want to layout the content area of the page and perhaps to do this differently on several pages? Your home page might need to contain an area with links to blog posts, an area with links to recent photos and perhaps an area with the block output created by a weather forecast module. Another page might need to show a user’s notifications in one column and a second column containing their direct messages. Although it is possible to use the theming system to create different page templates for each page and to use the blocks system to populate the templates, this approach has 2 major problems:

• Writing page templates requires you to write PHP & HTML template files to upload to the server.
• Drupal’s method of configuring blocks to be shown only on certain pages is designed to only cope with a small amount of variability between pages. Using this technique to make every page different would simply be a nightmare to manage.

This is where Panels steps in. When combined with the Page Manager module, you can take greater control over the user experience of your website, including:

• Create totally custom one-off pages with their own mashup of content
• Create page layouts that will be applied when the current page is a certain content type. For example, you could create a “Species Account” content type with it’s own set of fields and corresponding Panels layout.

The iRecord home page is an example of a panel layout.

Tutorial - Drupal Panels

In this tutorial we’ll learn to use the Panels and Page manager modules to configure a custom home page layout.

Before you start

Since we will be inserting the output of Views into our custom page layout, before following this tutorial please select Modules from the admin toolbar then search for the Views content panes module and tick the checkbox to enable it, then scroll to the bottom and click the Save configuration button.

Also make sure that you have at least the Front page view enabled via the Structure - Views page by clicking the Enable link to the right of the view in the list, so that we can add this view to our page.

Tip

The Views module comes with a set of example views which are disabled by default. One of these is the Front page view which replicates the functionality of the default home page of Drupal. It outputs all content where the Promote to front page option is checked (under the Publishing options section on the Edit tab each page).

1. Click Structure in the admin toolbar then select the Pages link.

2. Click the Add custom page button at the top of the list of pages.

3. Set the Administrative title to “home” and the Administrative description to “Home page layout”.

4. Set the Path to “home”.

5. Tick the Make this your site home page checkbox.

   

6. All the other options on this page can be left at their default setting so click the Continue button when you are ready.

7. On the next page, you need to specify the basic page layout you want. There are several categories of layout available and within each category there may be several layouts. Since we want to use a 2 column layout, choose the AT Responsive Panels - 2 column category and the AT Two Column 50/50 layout.

   

   Tip

   The AT Responsive Panels categories are all provided as part of the base Drupal theme we are using, called Adaptive Theme. They provide layouts which respond well to different devices such as mobile phones and tablets.

8. Click the Continue button to go to the next step. On the next Panel settings page, click Continue again as we don’t want to change any settings on this page.

9. The next page is the content editor for our page. It shows a wireframe of the panels layout we have chosen and allows you to insert any content you like into each region.

   

10. In the region called Left, click the cog icon on the left and select Add content from the popup menu.

11. A dialog will appear allowing you to first choose, then configure, the type of content to add the page. Select New custom content.

12. In the following configuration page, set the Administrative title to “Introduction” and enter some introductory/welcome text in the Body box:

    

    Save the content when you are done by clicking the Finish button to return to the view of the panels layout wireframe.

13. In the Right region, click the cog icon then select Add content as you did before. This time, select Views from the list of categories of content then select the Front page view.

14. Views can be configured with different display variants, for example a single view could output a set of columns when shown in a page, but output a limited set of columns when shown in a block. For this example, on the next step just leave the default option, which is the Display is set to Master and click Continue.

15. On the next page, click the Override title checkbox to allow us to take control of the title displayed for this content in the panel layout and enter “Recent stories” into the associated box. Click Finish when done.

16. Back on the panels layout wireframe, click the Finish button, then click Update and save to save the new panels page. Click the home icon in the top left of the admin toolbar to take you to the home page if you are not already there, so you can check the output.

If you’ve followed the tutorial to the letter, you will end up with a home page along the lines of the following:

Notice that our Front page view is not outputting any content at the moment. This is because the view is configured to only output content that has been promoted to front page and we have none. To get around this, click the add content link near the top left of the page, then choose Article which by default will be promoted to the front page. Set a suitable title and body text for your article then save the content and return to the home page to check that it appears.

This has just been a quick introduction to panels. Panels can output all types of content including:

• The output of other existing content pages.
• Lists of content generated by views.
• Custom text content.
• Custom PHP scripts, including code which interacts with the Indicia API.
• The output of modules which declare blocks, e.g. Weather or Twitter Block.

As usual with anything Drupal, there is lots of further reading available on the internet. Try the drupalize.me article if you want to take this further. There is also a tutorial showing how iRecord’s home page was built in Drupal 6.

Drupal Users and Permissions

Principles

We are using the Drupal login and permissions mechanisms to control access to all the features provided including the Indicia online recording pages.

Drupal permissions are controlled by role membership, so site users belong to roles and roles define the permissions they have. Roles might include things like “administrator” and “data manager”, a bit like a job title. One person can have multiple roles so you could be a “data manager” and a “photo moderator” for example. Visitors to your site can either be logged out or logged in. Each permissions defines one or several tasks that can be performed, for example there are permissions such as “Perform a backup”. When Drupal decides whether to show you the perform backup functionality, it checks if one of your roles has permission to do this and the appropriate links, menu items or buttons are only shown if so. This behaviour runs throughout Drupal; there are permissions for everything from administering users through to the ability to view content.

Logged out, anonymous users automatically belong to a fixed role called anonymous user and logged in users belong to a fixed role called authenticated user. These roles cannot be changed, but you can configure the permissions that are available for these roles so for example, you might configure Drupal so anonymous users cannot even see any content - you have to log in before doing anything. You could even configure Drupal so that anonymous users can administer the site, obviously not a good idea but perfectly possible.

Configuring permissions

You can add roles to the Drupal site yourself. Obviously you must have sufficient permissions to do this, such as when logged in with the site’s admin account. An example might be to setup a site editor role for people who have access to edit site content without having full admin permissions. We’ll work through how to set this up to illustrate all the concepts you need to understand relating to Drupal permissions.

1. Select People from the admin toolbar, then click the Permissions tab in the top right of the page. Click on the roles link near the top left of the page to access the list of roles.

   

   The list of roles

2. Type “site editor” into the Add role box at the bottom of the list, then click the button to add the role.

3. Click the edit permissions link to the right of the role you just added. You will now be looking at a page allowing you to tick each of the permissions you want to allow for the role, organised in a list of permissions by module. Tick the following permissions for our site editor role under the Node module:

   • Article: Create new content
   • Article: Edit own content
   • Article: Edit any content
   • Article: Delete own content
   • Article: Delete any content
   • Basic page: Create new content
   • Basic page: Edit own content
   • Basic page: Edit any content
   • Basic page: Delete own content
   • Basic page: Delete any content

4. Scroll to the bottom then click the Save permissions button.

Tip

If you wanted the site editor role to also be able to configure the online recording pages, reports and maps you would also tick the permissions starting with Indicia pages in the page title.

Adding a user to a role is simply a matter of editing their user account (as long as you have the correct permissions to do this of course). Select People from the admin toolbar then find the appropriate user and click the edit link. This includes various settings for the user account; the one we want to focus on at the moment is the list of roles that the user belongs to. Note that the user can of course belong to several roles – they could be a site editor and a record verifier at the same time for example.

Note

A challenge for you. See if you can add a new user to the list of users then configure them as a site editor, log out and log in as the new user to test the functionality.

When configuring permissions, you can view or edit all the roles and permissions in one big grid by selecting People from the admin toolbar then clicking on the Permissions tab in the top right.

Indicia permissions specifics

The Drupal LRC Website template is provided with a number of pages powered by the Indicia toolkit, under the Wildlife recording item on the main menu. Indicia allows you to easily control permissions on a page by page basis. By default, the Submit a sighting page is accessible to members of the public, whereas all the other online recording and reporting pages are only available to logged in users. There is an All records page which allows users to browse through each other’s records. To illustrate how to control permissions on a per-Indicia page basis, let’s make this page only available to our site editor group. Ensure that you are logged in as admin first.

1. Access the Wildlife recording menu’s All records page.

2. Click the Edit link to access the page’s configuration.

3. Scroll down to the Other IForm Parameters section and tick the View access control box. This means you want to control the permissions for this page separately to the default settings for Indicia forms.

4. In the Permission name for view access control box, enter “view all records”. This will create a new permission that we must then link to the appropriate role(s).

   

5. Scroll to the bottom of the configuration form and save it.

6. Since you are logged in as admin, you can see the form still even though you we haven’t linked one of your roles to the new “view all records” permission. This is because the admin account on a Drupal site is a special account which implicitly has all permissions.

7. Now, go to People in the admin toolbar then select the Permissions tab in the top right of the page.

8. Search on this page for the Indicia form module‘s “view all records” permission.

   

9. Now, scroll to the bottom of the page and save the permissions.

At this point, you may well want to test the permissions out. You’ll need to create a couple of user accounts to do this, or if you already have existing users on your website a really handy tool for testing the results of a permissions change from their point of view is Masquerade. Since this module has already been installed on your site for you, you simply need to access someone’s user account when logged in as admin and you will find a link there to masquerade as that user, so you can use the Drupal site from within their login to check it works as expected. Having rights to masquerade is obviously something you’d only want administrators to do!

Controlling the user registration process

A final note whilst we are on the topic of user management. Although the LRC Drupal Template website comes pre-installed with a module called BOTCHA Spam Prevention, you might still find the occasional spambot user will manage to register on the site. Although spambots rarely manage to submit a valid biological record you might find this is a hassle if you have, for example, added a forum to your website. Therefore you need to think about whether to allow users to register themselves on your website.

If you click on Configuration in the admin toolbar, then click on the Account settings link in the People section, you get to a page allowing various configurations relating to the user account to be set. Under the Registration and cancellation section, you can change the account registration so that:

• an administrator must manually register all users (good for websites with a small group of known users, since spambots cannot register)
• visitors can register
• visitors can register by email verification is required
• visitors can register but admin approval is required.

Have a think about which is most appropriate for the usage of your site.

Configuring online recording

The LRC Drupal Template website is provided with 2 wildlife recording forms under the Wildlife recording menu, one optimised for single record submissions and one for multi-record submissions. You can add new recording forms to your website as and when required. The following tutorials show you how to do this and in the process you’ll pick up many of the basic skills you’ll require to get confident with configuring Indicia recording.

In this example, we’ll add a simple “Spot the amphibian” citizen science survey. You will need a login for the Indicia warehouse which should have been provided to you.

Setting up a new survey on the warehouse

Firstly, note that in Indicia’s terminology a survey is a dataset owned by one online recording website which has been set up with a specific structure, a bit like setting up the columns in a spreadsheet. As well as being used to categorise records, an important use of surveys in Indicia is to allow you to customise the information you will capture for a record at a survey level. For example, you might run a survey of hedgehogs in your area as well as a survey of garden birds. The garden bird survey could allow the user to tick a box for nesting birds as opposed to non-breeding visitors to the garden. Obviously it would not make sense to provide this checkbox on a form for inputting hedgehog records! Don’t worry about dividing your data up into several surveys if you need to in order to get the right attributes for each survey, as it is simple to join the data back together again when producing reports and maps later. Whilst we are on the topic of terminology, we will be using the following:

• record or occurrence describes a unique observation of a species on a specified date, at a specified place, by a specified person(s).
• sample describes the observation event that leads to the taking of zero or more occurrences, e.g. the use of a trap on a particular date by a particular person(s) at a particular place.
• location describes any named place which you are keeping details of in the system. A location may be a site that you visit for recording purposes, but could also be something like a town or other place name.

Follow these steps to register a new survey for recording on the warehouse.

1. Login to the warehouse using your warehouse login.

2. Select Lookup lists > Surveys from the warehouse’s menu. You should now be on a page that shows a grid of surveys that already exist. Note that because your login only has access to configure surveys and other information for your own website, you will only see the survey that is already linked to your website.

3. Click the New survey button. This takes you to the New Survey page.

4. Set the title for your survey to “Spot the amphibian” and optionally fill in the description.

5. Select your website in the Website drop down, to associate the survey with your own website registration.

   

6. Click the Save button.

Setting up our recording form on Drupal

Now that the survey dataset is ready to accept records on the warehouse, let’s add a recording form to our website. Back in your Drupal site, select the Add content link which should be in the shortcuts area near the top left of the page. Select to add an Indicia page.

You will now be presented with the edit page allowing you to add new content to Drupal. It has exactly the same options as you’ve seen early for other Drupal content types such as Basic page - a title, body, publishing options, comment options etc. But, there is a little more to it which we will find out shortly. Set the title for your page to “Spot the amphibian”. Near the bottom of the page, click on the Publishing options section and check the Promoted to front page and Sticky at the top of lists since we want this form to be promoted via the front page rather than hidden in the menus. Also click on URL path settings and set the URL alias to “spot-the-amphibian” so that the URL is nice and memorable.

So far everything we’ve done on this page has been standard Drupal configuration but we are about to dive into setting up the Indicia aspects of the form. In the Form selection box you can pick from a large library of ready made Indicia powered pages called prebuilt forms. Each form has a set of configuration parameters which allow them to be set up to your exact needs, so one form might be usable in many different situations. Prebuilt forms are organised into categories. Select “General Purpose Data Entry Forms” in the Select Form Category control. In the Select Form control, choose “Sample with occurrences form”. This is a really flexible Indicia powered page which can be configured to support a wide range of survey datasets and is the best choice generally as a starting point for building your survey forms.

Now, click the Load Settings Form button. This requests the configuration parameters from the server and in a moment or two, injects the configuration form into the Drupal edit page.

Now, before you panic, there are a huge number of configuration settings for this particular prebuilt form, but many can be left in their default state so the actual number you need to understand is quite low. Also, each individual parameter is often quite simple when viewed in isolation and is accompanied by help text which explains how it works. Here are a list of the relevant settings you need to configure for our survey:

• Other IForm Parameters - View access control can be left unticked in this case to allow the form to be used by the public.
• Other IForm Parameters - Survey should be set to Spot the amphibian.
• Base Map Layers - Preset Base Layers - tick “Google Streets” and “Google Satellite”.
• Species - Allow a single ad-hoc record or a list of records should be set to “Only allow entry of one occurrence at a time”.
• Species - Species List should be set to UK Master List which is the complete of species names provided by UKSI. You may need to pick a different species list to record against if you are on a development server with a different setup.
• Species - Cache lookups should be ticked as this allows for better performance when looking up species names, as well as tolerance of things like differences in hyphenation or spacing.
• Species - Occurrence Images should be ticked to allow photo upload.
• Species - Field used to filter taxa can be set to “Taxon group title”. This allows us to filter the species returned from the entire dictionary by taxon group (i.e. the NBN taxon reporting category).
• Species - Taxon filter items should be set to “amphibian”.

Now scroll to the bottom and click the Save page button. You should have a slightly untidy but working form:

Although it should be functional, having three different tabs to navigate through for such a simple form is somewhat overkill. To fix this, click the Edit button then scroll down to find the User Interface section. Change the Interface Style Option from “Tabs” to “All One Page” then save the form again. This time we have rationalised the form onto a single page, but the form is still rather untidy and the map is very dominant:

Click the Edit button again and find the Initial Map View section. Change the Map Height (px) control to “450”. Before you save the page, scroll down to the User Interface section and find the Form Structure control.

Tip

The Form Structure configuration allows you to control exactly what controls are output onto the page and to take fine control over the configuration parameters passed to each control. Its well worth taking the time at some point to follow the Advanced Configuration using the Form Structure tutorial from the Indicia documentation website.

Copy and paste the following configuration settings into the Form Structure, replacing the existing content, to reformat the layout of the form:

=Misc=
[date]
@class=control-width-4
@helpText=Select the date of the record.
@lockable=true
[species]
@lockable=true
@class=control-width-4
@helpText=Enter the species name using * as a wildcard
@resizeWidth=1500
@resizeHeight=1500
[species attributes]
[location name]
@helpText=Enter the name of the site
[spatial reference]
@label=OSGB Grid Reference
@helpText=Enter a grid reference or click on the map to set the location of the record.
[sample comment]
@label=Comment
@helpText=Please provide any other information about the record which you think will be useful.
[*]
|
[place search]
[map]
=*=

That’s better!

Further Reading

This has been a very quick introduction Drupal and to building your own Indicia powered recording form. If you want to know more, then the links below are a great place to start. Note that a lot of the tutorials on the Indicia documentation website are designed for Drupal 6 but the Indicia configuration process is exactly the same.

• Indicia documentation website
• Adding a custom attribute
• Setting up a custom species list for recording
• Customising Indicia pages by adding your own JavaScript, CSS and language translations
• Learn how iRecord was built
• Get involved in developing Indicia
• Indicia.org
• Indicia forum
• The Drupal.org website
• Drupal Gardens documentation