Assistance Required: My First Plugin

[Ctwizzy]

Would appreciate some assistance from the vets. I have read the documentation, and am using the html_nugget event plugin as reference.

Goal:
To simply print a list in the header of the blog.
example: <ul> <li><a href="$path">$linkname</li></ul>

Once I learn this I should be able to change it to what I really want.
Im going to go over section by section, if I am misinterpreting something please correct me.

Code: Select all

<?php 
$probelang = dirname(__FILE__) . '/' . $serendipity['charset'] . 'lang_' . $serendipity['lang'] . '.inc.php';
if (file_exists($probelang)) {
    include $probelang;
}

include dirname(__FILE__) . '/lang_en.inc.php';

Above reads in the values of certain varibles decalred in a different file.

Code: Select all

class serendipity_event_page_nugget extends serendipity_event
{
   //introspect defines all data for the plugin 
	function introspect(&$propbag)
    {
        global $serendipity;

        $propbag->add('name',          PLUGIN_NAVBAR_NAME);
        $propbag->add('description',   PLUGIN_NAVBAR_DESC);
        $propbag->add('stackable',     true);
        $propbag->add('author',        'CR');
        $propbag->add('version',       '0.1');
        $propbag->add('requirements',  array(
            'serendipity' => '0.8',
            'smarty'      => '2.6.7',
            'php'         => '4.1.0'
        ));

I took this right from the html nugget plugin, I noticed all plugins pretty much have this.

Q1: What does the stackable property do?

Code: Select all

$propbag->add('groups', 'FRONTEND_ENTRY_RELATED');

Q2: Seeing as I want my list to display in the header it is frontend related? Groups I think just means where your plugin will apply?

Code: Select all

$propbag->add('event_hooks', 'frontend_header');

Q3: This is the actual hook we want to use, so for me I want to be in the frontend header?

Code: Select all

        $propbag->add('configuration', array('linkname','path'));

		return true;
    }

Q4: Configuration property would defining those values that would be changed in the admin of the plugin I assume?

Code: Select all

	function introspect_config_item($name, &$propbag)
    {
		//I think this assumes we are ONLY modifying configuration
        switch($name) {

            //title1
		case 'linkname':
		$propbag->add('type',        'string');
                $propbag->add('name',        PLUGIN_LINK_NAME);
                $propbag->add('description', PLUGIN_LINK_NAME_DETAILS);
                $propbag->add('default',     '');
                break;			

        	case 'path':
                $propbag->add('type',        'string');
                $propbag->add('name',        PLUGIN_PATH);
		$propbag->add('description', PLUGIN_PATH_DETAILS);
                $propbag->add('default',     '');
       		break;
        	
            default:
                return false;
        }
        return true;
    }

Q5: This method to me looks like it would only configure the configuration property defined earlier, but looks like it could be called with any property defined earlier. Im assuming this was done for other parts of the code?

Code: Select all

    function generate_content(&$title)
    {
        $title = $this->get_config('title');
    }

Q6: I dont think I need this besides the $title. As far as my reading got me, this is only used for sidebar plugins.

Code: Select all

    function event_hook($event, &$bag, &$eventData, $addData = null) {
        global $serendipity;

        $hooks = &$bag->get('event_hooks');

		$linkname = $this->get_config('linkname');
		$path = $this->get_config('path');
		}
    }

Q7: I think this is where the meat of my plugin should be, and if someone could explain to me how I use the hooks to pass my information to the page? I just want to print <ul><li><a href="$path">$linkname</li></ul>

Thanks for any help anyone gives.

[garvinhicking]

Hi!

Okay, I try to keep it short because that's what I am on time right now *g*

Q1: What does the stackable property do?

It is a boolean value that indicates if a plugin can be installed multiple times (true: yes, false: no)

Q2: Seeing as I want my list to display in the header it is frontend related? Groups I think just means where your plugin will apply?

This defines a single (or multiple) groups that a plugin is categorized into by the Spartacus groups. A list of available groupnames is here:

http://php-blog.cvs.sourceforge.net/php ... iew=markup

Q3: This is the actual hook we want to use, so for me I want to be in the frontend header?

Actually this is just a list of event hooks that your plugin "listens" on. A plugin is not limited to executing a single hook, but can "watch" multiple ones, which all need to be registered there.

Q4: Configuration property would defining those values that would be changed in the admin of the plugin I assume?

Right, just a list of configuration item key names that are later defined in introspect_config_item.

Q5: This method to me looks like it would only configure the configuration property defined earlier, but looks like it could be called with any property defined earlier. Im assuming this was done for other parts of the code?

Right, it catches any configuration option using the "switch" statement, and will be called multiple times.

Q6: I dont think I need this besides the $title. As far as my reading got me, this is only used for sidebar plugins.

You can only copy that stump, the $title variable is somewhat important to indicate the title of a plugin in the plugin configuration manager.

Q7: I think this is where the meat of my plugin should be, and if someone could explain to me how I use the hooks to pass my information to the page? I just want to print <ul><li><a href="$path">$linkname</li></ul>

Exactly, this is the central part. You need to add a "switch ..." case with the name of the event where you emit your text (as configured in the array of your Q2. Then you need to check if in that case you can echo() output, or if you need to stuff it in the $eventData array.

HTH,
Garvin

[Ctwizzy]

Hey Garvin,

Thanks for your help thus far.

So I have made progress, I finally have something printing to the page. I am amazed lol.

Its not what I intended yet but Im close!

Code: Select all

function event_hook($event, &$bag, &$eventData, $addData = null) {
        global $serendipity;

		//Collect all variables.
        $hooks			= &$bag->get('event_hooks');
		$linkname		= $this->get_config('linkname');
		$path			= $this->get_config('path');

		//Determine the event.
		if ($event == 'genpage') 
		{
			print ("<ul class=\"sitesections\">");
			print ("<li>");
			print ("<a href='$path'>$linkname</a>");
			print ("</li>");
			print ("</ul>");
		}


		}
    }

The Hook Genpage is the one I think is most suitable.

So I now only have 2 issues before I can start making this do exactly what I need it to.

#1 CSS seems to have no affect on it. I am ASSUMING that this is because of the hook (genpage), and that it is being displayed after the CSS takes effect. Is there a hook (I read through the descriptions and thought this was the best) that I have missed that would be better suited?

I added CSS to my hooks and used:

Code: Select all

if ($event == 'genpage' || $event == 'css') 
		{
			print ("<ul class=\"sitesections\">");
			print ("<li>");
			print ("<a href='$path'>$linkname</a>");
			print ("</li>");
			print ("</ul>");
		}

Still no CSS is applying, the css class is correct..

#2 The list is being displayed at the very bottom of the page, I would like it to print at the end of the serendipity banner.

Code: Select all

<div id="serendipity_banner">
    <h1><a class="homelink1" href="http://24.57.71.142/serendipity/">Chris Rayson</a></h1>
    <!--<h2><a class="homelink2" href="http://24.57.71.142/serendipity/"></a></h2>-->
    
RIGHT HERE!!!    
</div>

Is this possible? I am assuming it is I just dont know how, and none of the other plugins I am looking at seem to specify a position like the one I am looking to do.

Thanks Garvin or anyone else who answers my Q's.

[Ctwizzy]

1 more thing garvin,

My Nav bar via plugin could have 1-X links. What im debating is:

Should there be a cut off or not?
If I specify a cutoff it makes my life easier.
Say 4 entries MAX, configuration would have an array of elements such as:
linkname1, path1, linkname2, path2, linkname3, path3, linkname4, path4.

Then if the user didnt put anything in the path/link then when displaying do a quick check and dont output that entry and keep iterating.

But if I wanted to make it so the user could potentially have like 20 entries in his nav bar then I am a lil stumped at how I would do this as I have to have the plugin working with your config interface so having a button to add another linkname/path but then how do I have this work with the configuration... seems way more complex and maybe unneccesary.

What do you think?

Thanks!

[judebert]

OK, lots to cover. Garvin's on vacation, so I'll take a shot at it.


#1 - Actually, CSS is called separately, and applied by the browser. It applies to everything output on the page. You could try SlayerOffice MODI to make sure it's got the right class, and FireFox's EditCSS extension to modify it on the fly. I already have those tools installed; if you give me a URL, I'll take a look at it, too.

The CSS hook is used to add styles to the stylesheet. The hook you created adds HTML, which is invalid in a stylesheet. You probably want to hook css separately, and do something like:

Code: Select all

if ($event == 'css') {
    print('.sitesections { color: blue; }');
}

or whatever CSS you're trying to apply.

#2 - Unfortunately, there is no hook directly after the banner. The "genpage" hook is before anything (IIRC), so whatever you print there will be rendered separately from the other HTML output.

The "frontend_header" hook is called just before </head>. You can verify this in your index.tpl. That's not where you want your navbar; in fact, if you tried to put it there, the stuff either wouldn't show up at all, or would be rendered elsewhere, depending on the browser.

However, there is an "entries_header" hook just before all the entries. That shows up between the sidebars, but it's a good start for this project. Instead of hooking "genpage", hook "entries_header" and echo your output there. (To get what you *really* want, you would need to add a new hook in the template's index.tpl, just after the banner. That's not difficult, but it sorta defeats the purpose of making it a plugin.)

# of links: It's possible to get an undefined number of links, but it's not immediately easy. PHP allows arrays in its form variables with the PHP array operator: linkname[1], path[1], etc.

For the first version of the plugin, I'd limit it to five links. Then I'd come back to it later and try to extend it to unlimited links.

[Ctwizzy]

Thanks for the help.

Im not writing any CSS, my CSS file already exists and the styles are applying to the current navbar.

So what your saying is that I cant have my html in the navbar unless I abs position it? that kind of sucks...

The entries header seems as close as I can get it, Ill just try using CSS posititioning, I dont like doing it this way, but no biggie..

I was using a config.inc.php and calling the navbar in the .tpl file, but changed it to build a plugin as I wanted the experience and to understand how to make serendipity do more for me.

I dont know how the standard s9y users do navbars but I thought a plugin might be useful.

I got the CSS rendering it properly, was an error on my part.

Ok so 1 more Q then.
Say I want to have an about page.
Do I create a about.php and copy the index.php formatting, or do I make it so that the page I wana view would be passed to serendipity then have an event check for the variable and show that instead of entries?

i.e.
www.mypage.com/serendipity/index.php?about
www.mypage.com/serendipity/about.php

I think passing a variable might be easier to keep the formatting. Once again Im looking for how the average user is acomplishing these things.

Thanks!

[judebert]

Im not writing any CSS, my CSS file already exists and the styles are applying to the current navbar.

In which case, you either want to either:

• *Write the contents of that file on the "css" hook
  *Write a link to that file on the "frontend_header" hook
  *Add those styles to the style.css file in the current directory

Of course, only the first two are really useful for plugins.

I was using a config.inc.php and calling the navbar in the .tpl file, but changed it to build a plugin as I wanted the experience and to understand how to make serendipity do more for me.

And you've done an excellent job thus far. Congratulations!

Say I want to have an about page

The average user would install the "Static Pages" event plugin, create his about page, and either link to it directly in an HTML sidebar nugget or with the linklist sidebar plugin (which detects the "about" and "forum" pages).

[Ctwizzy]

And what would be the optimal way??

lol thanks jude

[judebert]

Haha! Turns out the common way is the optimal way.

Good luck!

[stm999999999]

Hi!

Okay, I try to keep it short because that's what I am on time right now *g*

Q1: What does the stackable property do?

It is a boolean value that indicates if a plugin can be installed multiple times (true: yes, false: no)

Hey, cool explanation! I think it should be linked in the tech documention!

[garvinhicking]

Hi stephan!

It's already in there for some months: http://www.s9y.org/43.html#A26

Regards
Garvin

[stm999999999]

I did not mean only the stackable, I thought about the whole "this are the internal of a plugin"-explanation.