Symphony.

I love this extension czheng and I love the idea behind it.

Do you think in the future (could be related to 3.) that it would be possible for extensions to provide their own documentation that this extension could then read?

Do you think in the future (could be related to 3.) that it would be possible for extensions to provide their own documentation that this extension could then read?

Very nice idea. Will have to think about that one…

In 2.0.6 work like a charm. Your extension saves me a lot of time creating documention for my client. I think it shoud be in default theme instalation, filled with explanations for newbies. I found only one cosmetic bug: when creating new documentation, saving errors red border is not shown on Title and Pages fields.

Thanks Craig, I will probably use this for all future client projects!

A related idea: how about an extension that lets you add a description to individual section fields?

A related idea: how about an extension that lets you add a description to individual section fields?

There is the Publish Notes Field Extension.

There is the Publish Notes Field Extension.

Thanks klaftertief, didn’t know about that extension!

Posted an issue in the extension’s issue tracker where the ‘Help’ menu item isn’t aligning with the menu when maintenance mode is activated on your site.

I found only one cosmetic bug: when creating new documentation, saving errors red border is not shown on Title and Pages fields.

Will look into it, thanks.

Posted an issue in the extension’s issue tracker where the ‘Help’ menu item isn’t aligning with the menu when maintenance mode is activated on your site.

Ha! Just discovered that one yesterday myself. Thanks. Will try to figure it out.

Great extension, craig. I think i may have found one issue:

if you try saving an entry w/o the content field filled out, you get returned to the same page and prompted to fill out the content field. when you try and save again, you get a symphony error page (sorry, didn’t take a screen grab) that has something to do with function.implode around line 20.

found one display issue. after saving an entry, the “help” menu does not move according to the symphony UI.

Yeah this is the same as reported above. When a page alert is present, the positioning is thrown off.

ah, sorry, didn’t read the previous posts!

found one display issue. after saving an entry, the “help” menu does not move according to the symphony UI.

I found a quick fix myself.

Step one: add the “Help” button to the navigation bar. In extension.driver.php replace lines 96-104 with:

$backend_page = &$context['parent']->Page->Form->getChildren();
$navigation = $backend_page[1];
$listitem = new XMLElement('li', NULL, array('id' => 'doc_item'));
$link = Widget::Anchor($this->_Parent->Configuration->get('button-text', 'documentation'), '#', __('View Documentation'), NULL, 'doc_link');
$listitem->appendChild($link);
$navigation->appendChild($listitem);
$docs = new XMLElement('div', NULL, array('id' => 'docs'));
$title = new XMLElement('h2', $doc_item['title']);
$docs->appendChild($title);
$content = new XMLElement('div', $doc_item['content_formatted']);
$docs->appendChild($content);
$listitem->appendChild($docs);

Step two: replace the old documenter.css with the one attached to this post.

It works with Chrome 4.0, Firefox 3.5 and Opera 10. I can’t test it on IE, though. Anyone?

Attachments:

documenter.css

Thanks for that, eKoeS. Will try it out on IE today or tomorrow.

czheng, I thought I’d try to experiment with delegates considering I’ve never done so before and came up with this.

It allows extensions to provide documentation through two delegates, appendDocsPre and appendDocsPost. appendDocsPre lets the extension register the page for the documentation to appear. appendDocsPost lets the extension add the title and content_formatted.

I also made the change so that it will handle documentation provided by an extension as well as user defined rules through the Documenter interface.

An example of an extension using the these delegates:

    public function appendDocsPre($context) {
        $context['pages'][] = array('pages' => '/extension/export_entry/export/');
    }

    public function appendDocsPost($context) {
        $context['doc_item'][] = array(
           'title' => "Testing",
           'content_formatted' => "<p>Hello <strong>world</strong></p>"
        );
    }

Like I said, I haven’t had any experience with delegates before, and the documentation isn’t quite there yet for extension developers so if I’ve missed anything please let me know.

I’ll submitted a pull request via GitHub too (untested with 2.0.7 for now).

Thanks brendo. Will look at incorporating this.

Hold off for now czheng, I’d like to spend this evening looking at a implementing a different method.

I’m thinking a better approach, especially from a localisation angle would be to have a lang folder inside the extensions that provide a documenter.{$lang}.html file for the delegate to read.

This saves cramming HTML into the extension driver, adds localisation, and lets the extension developers customise the HTML easier (inline CSS if they really must).

I was thinking of providing an interface to read TM/Markdown depending on the Documenter’s preference, but I think this adds too much work for the extension developer, and offers no real advantages, so have opted for the aforementioned.

I’ll look at incorporating eKoeS’s changes too.

Thoughts are welcome.

Done. After thinking about it, didn’t require many changes from before :)

I’ve just modified it to have a look at the $doc_item. It’s assumed that if $doc_item['title'] is absent, then the content has been loaded directly from a file.

Few other minor changes included incorporating eKoeS’s code, changing the SQL to only return title, content_formatted (I didn’t see a need for the other fields?) and minor JS change.

An extension can now take advantage of the delegate as mentioned before if the developer wants, but the following is an example of how to load from another file (modified from Nils code).

    public function appendDocsPre($context) {
        $context['pages'][] = array('pages' => '/extension/export_entry/export/');
    }

    public function appendDocsPost($context) {
        $lang = Administration::instance()->Configuration->get('lang', 'symphony');

        if(file_exists(EXTENSIONS . '/export_entry/lang/documenter.' . $lang . '.html')) {
            $context['doc_item'][] = array(
                'content_formatted' => file_get_contents(EXTENSIONS . '/export_entry/lang/documenter.' . $lang . '.html');
            );
        } else {
            $context['doc_item'][] = array(
                'content_formatted' => file_get_contents(EXTENSIONS . '/export_entry/lang/documenter.en.html');
            );
        }
    }

Sweet. Let me know if you want to do any more of my work ;)

Few other minor changes included incorporating eKoeS’s code

Thank you for including that. I think you can safely remove all the comments inside documenter.css, as they were there for testing purposes only. ;)