Documenting your plugin
Documenting a plugin’s installation procedure, settings and other behaviour properly is always a challenge. To help out, Frog turns the name of your plugin into a link to the online documentation page if it detects you have one.
Here’s an overview of the current best practice according to the Frog development team.
- Provide a readme.txt file in the root of your plugin with a changelog and basic installation information.
- Provide an online documentation page for your plugin containing all documentation about settings, behaviour, etc.
Note: by “online” we mean within the plugin itself, not on your homepage. You can of course always put the documentation on your homepage aswell.
Providing an online documentation page means you will have to:
- Create a Controller if you don’t already have one
- Add a
documentation()function - Add a documentation view
Before we continue: the link to the documentation page, the plugin’s tab and the documentation page itself will only become available after you have enabled the plugin in Frog’s Administration section. So remember to enable the plugin before testing all of this.
A little something about URLs in Frog
Frog is quite smart about URLs and uses those smarts to simplify calling particular functions in a plugin’s controller. A simple example for our hello_world plugin would be:
http://www.example.com/frog/admin/plugin/hello_world
Any requests sent to this URL are interpreted by Frog to mean that you want to access the index() function of the hello_world plugin’s Controller.
What we are doing in this article is that we want to access the settings page. You could of course type in the URL manually each time you want to access that page, but we provide you with a link to it from the Administration screen and you (as the plugin’s developer) can add a link to it from the sidebar.
Just in case you were still wondering, the url to access for the documentation() function would be:
http://www.example.com/frog/admin/plugin/hello_world/documentation
Creating the Controller
We are assuming that you have already created a Controller, or that you’ve already read through A Settings page for your plugin If you haven’t already created a controller, please read through the mentioned document first.
Note: it is our recommendation that every plugin which provides a tab in the backend and a settings page or documentation page, also provides the sidebar.
Adding the documentation function
Now we have to make certain Frog will automatically detect that you supply a documentation page. Frog does this by verifying whether or not you have a documentation() function in your Controller. To provide it, simply add the following function to your Controller:
function documentation()
{
$this->display('hello_world/views/documentation');
}
This simply displays the documentation view. Since the documentation page contains just documentation, it is essentially just a big HTML page.
Adding the documentation view
The documentation() function we’ve added in the prior section displays a documentation view. We will of course have to provide the plugin with this view. In your plugin directory, create a ‘views’ directory. In this ‘views’ directory create and edit a file called ‘documentation.php’. Here’s an example of what you can put inside:
<h3>How to use this plugin</h3> <p> Some text describing use... </p> <p> You will need to add this code to your layout: </p> <pre> some code.. </pre><h3>Notes</h3> <p> When you ... </p><h3>License</h3> <p> This Frog plugin has been made available under the GNU AGPL3 or later. </p> <p> Copyright (C) 2008 Your Name <your.email@example.com> </p> <p> Please see the full license statement in this plugin's readme.txt file. </p>
As you can see, it is just a big HTML file.
That’s about it. Hopefully this document is clear enough, otherwise let us know in the forum.
