Creating Addons - Tutorial 1: Overriding default top-menu

From SocialStrap Wiki
Jump to: navigation, search

Introduction

If you’ve been using SocialStrap for a while, and you want to develop your own addons to the application, this is the guide for you!

After reading this guide (and working through the examples), you will have an understanding of how SocialStrap works and how you can extend it to meet the needs of your community. You will find how incredibly easy it is to develop extra features for SocialStrap.

From the start of the project, SocialStrap has been developed with add-ons in mind. SocialStrap is a powerful PHP application that allows you to completely adapt script to your needs.

In this guide, I will teach you the basics of SocialStrap’s architecture.

If you encounter any problems with the examples in this guide, or if you have any questions or comments, just drop me a mail (info -at- socialstrap.net). This is the first version of the guide, so some things may not be clear enough yet. I welcome any suggestions for improvements.

Prerequisites

In order to develop add-ons for SocialStrap, you should have some knowledge about programming in PHP, since that is the language script was written in. You don’t need to be a guru or a Zend expert but knowledge of the basic concepts will help you understand this guide. If you have never used PHP before, find a tutorial on the web. The official PHP site, www.php.net, is a good starting point if you want to learn more about PHP.

I assume you have a working SocialStrap installation that you are able to develop. Don’t use your production installation, or production database!

Finally, all you need is a text editor. I can recommend notepad++ which is a free source code editor which features syntax highlighting. But of course you can use the text editor you are most comfortable with.

So. If any of the above did not scare you away, we are now ready to start.


Create your first add-on

Fist let's go inside addons/ folder and create a new folder for your add-on. We can call it "mytopmenu".

Each add-on has to contain main file called init.php so let's create one inside addons/mytopmenu/ folder with this content:

<?php
$name = 'My Top-Menu';
$version = '1.0';
$author = 'George';
$description = 'Custom top menu';

After this step the new add-on will show up in your Addons section. Log in as admin and go to "Addons".


Layout overriding

SocialStrap's default layout is stored here: app/core/views/layout/

Inside this folder you will find all template files required for application to render html output.

In this example I will teach you how to override default layout by overriding the main top-menu and adding few extra links on it.

In order to override the main layout we will use Hooks. We need one specific system Hook called "hook_app_init".

Create a second file inside your new add-on folder called addons/mytopmenu/hooks.php with following content:

<?php
$this->attach('hook_app_init', 10, function ($app)
{
	
	$view = $app['view'];
	
	$view->addScriptPath(realpath(dirname(__FILE__) . '/customlayout'));
});

and we need one more folder to store our custom layout templates:

addons/mytopmenu/customlayout/

Basically, the code inside your new file hooks.php will instruct the SocialStrap to check if there is some custom template file inside your addons/mytopmenu/customlayout/ folder and if it is then render this one instead of core template file from here app/core/views/layout/


In the next step we will copy the original top-menu template file to our custom folder.

Since top menu is located inside sub-folder called "_layout" you will have to create that folder first:

addons/mytopmenu/customlayout/_layout/

Now copy the file from here app/core/views/layout/_layout/topmenu.phtml to here addons/mytopmenu/customlayout/_layout/topmenu.phtml.

By now you should have this filesystem structure inside your new add-on:

addons/mytopmenu/
addons/mytopmenu/hooks.php
addons/mytopmenu/init.php
addons/mytopmenu/customlayout/
addons/mytopmenu/customlayout/_layout/
addons/mytopmenu/customlayout/_layout/topmenu.phtml

This add-on will now force SocialStrap to use this new top-menu instead of original one. So, let's edit that file and add some extra fields.


Customizing top-menu file

Edit your addons/mytopmenu/customlayout/_layout/topmenu.phtml file and add some extra links.

In this example I will add a link to "All Posts" next to "Home" link. Looking at the few last lines of original file:

   ...

				
			<ul class="nav navbar-nav navbar-right">
				<li><a href="<?php echo $this->baseUrl()?>/" data-toggle="modal"><?php echo $this->translate('Home');?>
				</a>
				</li>
			</ul>

		</div>

	</div>
</div>

Let's add one more li element:

   ...

				
			<ul class="nav navbar-nav navbar-right">
				<li><a href="<?php echo $this->baseUrl()?>/" data-toggle="modal"><?php echo $this->translate('Home');?>
				</a>
				</li>
				<li><a href="<?php echo $this->baseUrl()?>/search/posts" data-toggle="modal"><?php echo $this->translate('All Posts');?>
				</a>
				</li>				
			</ul>

		</div>

	</div>

Now jump to your browser, re-load the page and check if this is working. It is? Great!

You can download the source code from here: Example Source Code


Conclusion

Why should I do this the hard way? Can I just edit the original files inside the core layout: app/core/views/layout/?

The main reason for doing this trough add-ons is software update. When you change application's core files you are loosing the ability to automatically update your software.

If you mess with application core files then you have to be careful when you update your script and re-apply all your custom code when files are updated.

You can create one single add-on and store all your custom html overrides there. Furthermore, you can create a custom layouts like this and sell it on CodeCanyon!

There are many more Hooks available and you can create all sorts of add-ons. You can download some from Add-ons Directory and check the code and the logic behind them.