February 24, 2012
I have recently come across a few questions where developers needed to build the path to a tool, so here is a quick refresher.
Tools files are useful for anything where a site needs to respond to a URL request, but doesn't need to serve a page. This could be responding to an ajax request, providing an API service, streaming a file, or whatever you like. For general purpose code responding to a URL request, tools are one way to do it. Other ways include action methods in controllers, but that's a different subject.
concrete5 supports two ways to provide tools files. Block tools and package tools. You can also have tools in a site root /tools directory. That is a bit like a package tool, but without the package.
A block tool lives in a /tools sub-directory of a block.
A package tool lives in a /tools sub-directory of a package.
To obtain the URL to call for a package tool, you need the name of the tool and the handle for the package.
$tool_helper = Loader::helper('concrete/urls');
$tool_url = $tool_helper->getToolsURL('tool_name', 'package_handle');
If the tool is in a /tools root directory, the url can be obtained just with the tool name
$tool_helper = Loader::helper('concrete/urls');
$tool_url = $tool_helper->getToolsURL('tool_name');
Block tools are a little bit trickier. You need to build the actual tool path yourself. Nevertheless, the basic information is similar; you need the name of the tool and the handle for the block.
$tool_helper = Loader::helper('concrete/urls');
$bt = BlockType::getByHandle('block_handle');
$tool_name = $tool_helper->getBlockTypeToolsURL($bt).'/'.'tool_name');
If you are already in a block controller, you can get the block handle by:
$this->btHandle;
You can see examples of package and block tools in use in the Ajax Lessons addon.
Don't forget that a tool responds to a publicly available URL, so you often need to consider the security issue of anyone else simply loading the tool URL in their browser. This is usually resolved by checking user permissions and checking a validation key.
Loading Conversation