Documentation

Light-weight, fast, simple and powerful!
 
Translations of this page?:

Introduction

Documenting a plugin’s installation procedure, settings and other behavior properly is always a challenge. To help out, Wolf CMS turns the name of your plugin into a link to the online 1) documentation page if it detects you have one.

Here’s an overview of the current best practice according to the core development team.

  • Provide a readme.txt file in the root directory of your plugin. It should contain a changelog and basic installation information.
  • Provide an online documentation page for your plugin containing all documentation about installation, settings, behavior, 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 as well.

Providing an online 2) documentation page means you will have to:

  • Create a Controller if you don’t already have one
  • Add a documentation() function to the controller
  • Add a documentation view to the plugin

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 the Administration section. So remember to enable the plugin before testing all of this.

A little something about URLs

Wolf CMS 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/wolf/admin/plugin/hello_world

Any requests sent to this URL are interpreted by Wolf CMS 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 documentation 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 in your plugin.

Just in case you were still wondering, the url to access for the documentation() function would be:

http://www.example.com/wolf/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 Providing 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 Wolf CMS will automatically detect that you supply a documentation page. It 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's 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 Wolf CMS plugin has been made available under the GNU GPL3 or later.
</p>
<p>
  Copyright (C) 2009 Your Name &lt;your.email@example.com&gt;
</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.

1) , 2) By “online” we mean within the plugin itself, not on your homepage.
 
tutorials/documenting_plugins.txt · Last modified: 2012-03-13 16:12 by mvdkleijn
 
Except where otherwise noted, content on this wiki is licensed under the following license:GNU Free Documentation License 1.2
Copyright 2010 wolfcms.org / design by yello studio / Wolf CMS Inside