Lesson 2: Modifying a section of a page

Transcription

1 Lesson 2: Modifying a section of a page Overriding a view is covered in this lesson. Problem There is a section of the Elgg page structure that you want to change. Perhaps you want to include an ad in the footer or rearrange the topbar. You could search for that specific HTML code in Elgg and hack it to get what you want, but then upgrades to the latest version of Elgg would be difficult. You want to do this the right way. Solution Elgg divides up its page structure into views, a view is a chunk of HTML code. The topbar and header are views. The search box is a view inside the header view. By changing one of these views, we change every Elgg page that uses it. With Elgg, the primary way to change a view is to override it. Overriding a view results in our HTML replacing the HTML of the core view. Example The default Elgg theme has a header with the site name, a search bar, and a set of menu tabs: We are adding a tagline below the site name: Step 1: Find the view to override All the HTML views for the core Elgg engine are stored in /views/default. Looking through all the directories could take a lot of time, so we will try two different approaches to find the view with the site name in it: Using Firebug or the equivalent tool for your browser, start the inspect tool and click on the site title in the header. The Firebug panel will display the HTML code for that area of the page. You will notice a link with a class of elgg-heading-site:

2 Searching for the string elgg-heading-site should find the view that we want to override. Using the Developer Settings page which has a setting called Wrap views. When it is enabled, comments are placed around each view with the name of the view in the comment. By configuring Firebug to show comments, we can use the inspect tool to select the site name and find that it is wrapped by the comment for the 'page/elements/header_logo' view. We now know that the view is located at /views/default/page/elements/header_logo.php

3 Step 2: Create the plugin structure We call our plugin custom_logo. It needs a plugin manifest file and start.php. Add those files and update the manifest to describe the purpose of the plugin. Overriding a view requires that we add a view in the same relative location in our plugin as it exists in the default Elgg theme. As the view is located at: /views/default/page/elements/header_logo.php We create our view at: /mod/custom_logo/views/default/page/elements/header_logo.php. When Elgg detects the view there, it automatically replaces the core view with our view. The last file our plugin needs is a CSS view so that we can style our tagline. Create a file named css.phpin a custom_logo directory under views/default/. The reason that we put our plugin's CSS view in a directory named after the plugin is to prevent conflicts with other plugins. This is a best practice for plugin development. After the files and directories have been created, we have the following plugin structure: Step 3: Edit the logo view We could start with a blank view or we could copy the current view code into our view as a starting point. Let's copy the code as we only want to add the tagline. After we do that, our view's code looks like the following: <?php /** * Elgg header logo */ $site = elgg_get_site_entity(); $site_name = $site->name; $site_url = elgg_get_site_url();?>

4 <h1> <a class="elgg-heading-site" href="<?php echo $site_url;?>"> <?php echo $site_name;?> </a> </h1> Now is a great time to make a small edit, copy the plugin to our server, and make sure we are changing the correct view. Remember that it is a good idea to test your plugins often as you write them. Insert some arbitrary text directly above the <h1> element and then check that it appears in the header when you view the website. To add a tagline, we append our text to the bottom of the view and wrap it in a heading tag: <?php /** * Overriding the page/elements/header_logo view */ $site = elgg_get_site_entity(); $site_name = $site->name; $site_url = elgg_get_site_url();?> <h1> <a class="elgg-heading-site" href="<?php echo $site_url;?>"> <?php echo $site_name;?> </a> </h1> <h2 class="custom-logo-heading"> Hello, tagline! </h2> The tagline appears in the header, but is extremely difficult to read due to its position and color. We need to style it with CSS. Step 4: Style the header Before we add any CSS to the 'custom_logo/css' view, we need to inform Elgg that we want that view included with the main CSS file. We do this in our start.php file, as follows: elgg_register_event_handler('init', 'system', 'custom_logo_init'); function custom_logo_init() {

5 } elgg_extend_view('css/elgg', 'custom_logo/css'); This code tells Elgg to add the output of 'custom_logo/css' to that of 'css/elgg'. If we wanted to add CSS to the admin theme instead, then we would extend the 'css/admin' view. In our plugin's css.php file, we add the following:.elgg-page-default.elgg-page-header >.elgg-inner { height: 120px; }.custom-logo-heading { color: white; font-family: Georgia,times,serif; font-style: italic; font-size: 1.2em; text-shadow: 1px 2px 4px #333333; } The first statement makes the header taller so that our tagline will not overlap with the site menu. The second part styles the tagline text giving it the appearance of white text set off by a dark shadow. When you view your site now, it should look like the screenshot from the beginning of this lesson Exercise You can continue to work with the custom_logo by replacing the site name heading with an image. You can also pull the tagline text from the optional site description that is set on the Basic Settings page in the administration area. The text is retrieved like the following: <h2 class="custom-logo-heading"> <?php echo $site->description;?> </h2> To practice overriding views, try replacing the footer of Elgg with your own custom footer. After overriding views a few times, the process of finding the view and setting up the plugin will become easy for you. Then, you can focus on writing the HTML code and the CSS. If you override a view that belongs to a plugin, then your plugin must be loaded after that plugin.