how to make an extension

Discuss PivotX 2.0.x extensions here, and view extensions that are available for download.

how to make an extension

Postby marc » Tue Jun 10, 2008 9:30 pm

Is there a "how to make an extension" manual?
Maybe there's a simple example, can anyone help?
User avatar
marc
 
Posts: 39
Joined: Tue Jun 10, 2008 7:32 pm
Location: Utrecht, Netherlands

Re: how to make an extension

Postby hansfn » Tue Jun 10, 2008 11:33 pm

We are planning to make some proper documentation very soon so third party development can start.

Until then your best bet is to look at the existing extension in the "extensions" folder: We recommend one folder per extension - look for example at extensions/hello_world/ If all you want is a simple extra template tag, look at extensions/hello_world/snippet_helloworld.php. If you can tell us what you intend to do, we can offer more advice.
hansfn
Developer
 
Posts: 3282
Joined: Sun Nov 25, 2007 7:48 pm
Location: Molde, Norway

Re: how to make an extension

Postby marc » Wed Jun 11, 2008 7:08 am

thanks, I'll have a look at snippet_helloworld.php. (however it doesn't exist in beta 1.6 but it does in 1.5)
User avatar
marc
 
Posts: 39
Joined: Tue Jun 10, 2008 7:32 pm
Location: Utrecht, Netherlands

Re: how to make an extension

Postby mbootsman » Thu Sep 04, 2008 7:33 am

I'm interested too, I used to have my own flvplayer and mp3player, using [[flvplayer]] and [[mp3player]] snippets. Now, I don't know how to realize this.
mbootsman
 
Posts: 89
Joined: Tue Apr 29, 2008 7:09 am

Re: how to make an extension

Postby Khevor » Thu Sep 04, 2008 11:10 pm

The extension I used as an example to make my calendar was the slideshow extension. The slideshow includes almost everything you need to make sense of it (including helpful comment lines that tell you what each thing does).

You wouldn't think this information is important, but PivotX uses the information in these comments in the Extensions section of the dashboard where it shows you the name, author, version, etc.
Code: Select all
// - Extension: Slideshow
// - Version: 0.5 - development
// - Author: PivotX Team
// - Email: admin@pivotx.net
// - Site: http://www.pivotx.net
// - Updatecheck: http://www.pivotx.net/update.php?ext=slideshow
// - Description: a slideshow widget
// - Date: 2008-02-24
// - Identifier: slideshow



These are your default configuration values. These values are used during the initialization of the extension.
Code: Select all
global $slideshow_config;

$slideshow_config = array(
    'slideshow_width' => "250",
    'slideshow_height' => "180",
    'slideshow_folder' => "slideshow",
    'slideshow_limit' => "15",
    'slideshow_orderby' => "date_desc",
    'slideshow_thickbox' => 1
);


This part is required if you plan on having a page show up in the dashboard configuration (for the purposes of allowing the user to alter default settings).
The things you would change here are 'slideshow' <= the identifier name of your extension; "slideshowAdmin" <= name of the function to call to create the dashboard config page; "Slideshow" <= Not totally sure but I believe this is just the readable name of the extension.
Code: Select all
/**
 * Adds the hook for slideshowAdmin()
 *
 * @see slideshowAdmin()
 */
$this->addHook(
    'configuration_add',
    'slideshow',
    array("slideshowAdmin", "Slideshow")
);


I don't completely understand what this section is for, but I left it in to be on the safe side when I was working on my extensions. 'slideshow' is the identifier name and "smarty_slideshow" is the name of the function that does all the work.
Code: Select all
/**
 * Adds the hook for the actual widget. We just use the same
 * as the snippet, in this case.
 *
 * @see smarty_slideshow()
 */
$this->addHook(
    'widget',
    'slideshow',
    "smarty_slideshow"
);



This part is extremely useful if you need to add anything to the header of the page (stylesheets, javascript, etc.).
The 'after_parse' is something you'll likely want to leave alone (so it doesn't execute any code you want at the header during the creation of the webpage).
The 'insert_before_close_head' is the location where you want your information to go. There are several locations you can use: insert_at_begin, insert_after_open_head, insert_after_close_head, insert_before_open_body, insert_after_open_body, insert_before_close_body, insert_after_close_body, insert_at_end. Warning though, if you use insert_at_begin and you use the DocType line in your pages, it could play havoc with how your page displays.
The third piece of information here is exactly what you want added (putting a comment field before it all such as <!-- slideshow --> is helpful separating actual page code with the stuff you added.). In this case, you can see two lines of javascript were declared as well as a stylesheet.
Code: Select all
/**
 * Add some javascript to the header..
 */
$this->addHook(
    'after_parse',
    'insert_before_close_head',
    "<!-- slideshow -->
    <script type='text/javascript' src='[[pivot_dir]]extensions/slideshow/jquery.slideviewer.1.1.js'></script>
     <script type='text/javascript' src='[[pivot_dir]]extensions/slideshow/jquery.easing.1.2.js'></script>
     <link href='[[pivot_dir]]extensions/slideshow/slideshow.css' rel='stylesheet' type='text/css' />"
    );


This line is the one that creates the tag you want to use in your templates. Simply put, in this case, using [[slideshow]] will call the smarty_slideshow function.
Code: Select all
// Register 'slideshow' as a smarty tag.
$PIVOTX['template']->register_function('slideshow', 'smarty_slideshow');


The next part is the meat of your extension. It's the function that does everything you want your extension to do. One thing to mention here is the use of the $params. This particular variable is an array and it contains any values passed to this function from the tag you used in your templates. For example (and this is not a functioning example, just an illustration), if you wanted to pass the filename of an image to this, in your template, you might use [[slideshow image=myimage.jpg]]. In this function, that information would be accessed via $params['image'] (which would contain "myimage.jpg"). It is flexible enough where you could put in whatever parameters you want (provided you create code in the function that uses them... otherwise it's just wasted space).
Code: Select all
/**
 * Output a slideshow feed
 *
 * @param array $params
 * @return string
 */
function smarty_slideshow($params) {
    global $PIVOTX, $slideshow_config;
    ...
    return $output;
}



This last part is to create the form that will show up in the dashboard for the purposes of configuration. It actually is as easy as it appears. You put in what type of form element you want to appear (such as a textbox, checkbox, etc.), give it a name (bear in mind, the name should match the names of the default settings in the array at the beginning. In this case, $slideshow_config, listed at the top of the widget file.), give it a label and a default value, and so on. The last line here is required (the $form_html['slideshow'] line). Just rename 'slideshow' to be the identifier you used for your extension.
Code: Select all
/**
 * The configuration screen for slideshow
 *
 * @param unknown_type $form_html
 */
function slideshowAdmin(&$form_html) {
    global $PIVOTX, $slideshow_config;

    $form = $PIVOTX['extensions']->getAdminForm('slideshow');

    $form->add( array(
        'type' => 'text',
        'name' => 'slideshow_folder',
        'label' => "Folder name",
        'value' => '',
        'error' => 'That\'s not a proper folder name!',
        'text' => "The name of the folder in where the images are that Slideshow should use. This should be a folder inside your <tt>images</tt> folder. So if you input <tt>slideshow</tt>, the slideshow will look in the <tt>/images/slideshow/</tt> folder. Don't start or finish with a slash.",
        'size' => 32,
        'isrequired' => 1,
        'validation' => 'string|minlen=1|maxlen=32'
    ));

    /**
     * Add the form to our (referenced) $form_html. Make sure you use the same key
     * as the first parameter to $PIVOTX['extensions']->getAdminForm
     */
    $form_html['slideshow'] = $PIVOTX['extensions']->getAdminFormHtml($form, $slideshow_config);

}


And there you have it. There are other parts to extensions as well but I don't know enough about how they all work to even attempt to put up an explanation of those. This is just a description of how to make a basic widget (which, by the way, needs to be named widget_myextension.php and should be in its own folder in the extensions folder of pivot. So, if your extension identifier is 'Iwashere', then there would be a 'Iwashere' folder in the extensions folder. Within that, would be your extension file itself named 'widget_Iwashere.php'. If you included a javascript file or a css in the widget, you'd keep those in this folder as well.

I hope that helped somewhat and sorry if it just made things worse :?
Khevor
 
Posts: 26
Joined: Sun Aug 03, 2008 2:37 am
Location: Ontario, Canada

Re: how to make an extension

Postby mbootsman » Fri Sep 05, 2008 6:58 am

Khevor, can you let us know in what files you did these edits?
mbootsman
 
Posts: 89
Joined: Tue Apr 29, 2008 7:09 am

Re: how to make an extension

Postby Bob » Fri Sep 05, 2008 7:47 pm

Khevor, Nice introduction. Lot's of information. :-)

Warning though, if you use insert_at_begin and you use the DocType line in your pages, it could play havoc with how your page displays.


You're right. This is added as a bug, and will be fixed (it should never come _before_ the doctype): http://tracker.pivotx.net/view.php?id=406
Bob
Lead Developer
 
Posts: 1374
Joined: Tue Nov 20, 2007 11:16 pm

Re: how to make an extension

Postby Khevor » Fri Sep 05, 2008 8:17 pm

mbootsman wrote:Khevor, can you let us know in what files you did these edits?


I'm not sure what you mean. I didn't make any edits. I was just pointing out what the different lines of code were for when you create your own extension.


Bob wrote:Khevor, Nice introduction. Lot's of information. :-)

Warning though, if you use insert_at_begin and you use the DocType line in your pages, it could play havoc with how your page displays.


You're right. This is added as a bug, and will be fixed (it should never come _before_ the doctype): http://tracker.pivotx.net/view.php?id=406


Thanks. :) I hope others find it useful. It's funny though, it never occurred to me that the doctype part was a bug. LOL.
Khevor
 
Posts: 26
Joined: Sun Aug 03, 2008 2:37 am
Location: Ontario, Canada

Re: how to make an extension

Postby Kay » Sun Jan 25, 2009 10:23 pm

I'm in the process of writing a new extension but when I activate it it crashes the blog i.e. every URL results in a white screen. Can someone check the code and tell me what causes the crash? (It doesn't do what it says it does yet, I just wanted to test if the code works so far.)

widget_popent.php
Code: Select all
<?php
// - Extension: Popular Entries
// - Version: 0.1 - development
// - Author: Kay Hermann
// - Email: KayHermann@gmx.net
// - Site: http://www.kay-hermann.de
// - Updatecheck: n/a
// - Description: Lists most popular entries
// - Date: 2009-01-25
// - Identifier: popent

global $popent_config;

$popent_config = array(
    'popent_folder' => "popent",
    'entries' => "10"
);


/**
* Adds the hook for popentAdmin()
*
* @see popentAdmin()
*/
$this->addHook(
   'configuration_add',
   'popent',
   array("popentAdmin", "Popular Entries")
);

/**
* Adds the hook for the actual widget. We just use the same
* as the snippet, in this case.
*
* @see smarty_popent()
*/
$this->addHook(
    'widget',
    'popent',
    "smarty_popent"
);

// Register 'popent' as a smarty tag.
$PIVOTX['template']->register_function('popent', 'smarty_popent');

/**
* Output
*/
function smarty_popent($params) {
    global $PIVOTX, $popent_config;

   /******************************
   *  Get Entries                *
   ******************************/
   
   $aListEntries = $PIVOTX['db']->read_entries(array('show'=>get_entries_count(), 'status'=>"publish");

   
   /******************************
   * List hit count              *
   ******************************/
    $bbclone_path = fixPath($PIVOTX['paths']['pivot_path'].'../../bbclone/');
    $PIVOTX['paths']['bbclone_path'] = $bbclone_path;

    if(!file_exists($bbclone_path)) {
        debug("bbclone directory not found - expected location: $bbclone_path");
        return;
    }

   require($PIVOTX['paths']['bbclone_path']."/var/access.php");

   foreach ($aListEntries as $a) {

    $title = $a['title'];
   
    // bbclone cuts some characters if title is too long (>60) and adds "..."
    // and replaces a few character by its entities
    if (strlen($title) > 60){
        $title = substr($title,(strlen($title) - 57));
        $title = "...".$title;
    }
    $title = htmlspecialchars($title,ENT_QUOTES);

    $hits = $access["page"][$title]["count"];
    if (empty($hits)) { $hits = "0"; }
   
    $output .= $hits . "<br>";
   }
 return $output;
}

/**
* The configuration screen for popent
*
* @param unknown_type $form_html
*/
function popentAdmin(&$form_html) {
    global $PIVOTX, $popent_config;

    $form = $PIVOTX['extensions']->getAdminForm('popent');

    $form->add( array(
        'type' => 'text',
        'name' => 'entries',
        'label' => "Number of entries to be displayed",
        'value' => '10',
        'error' => 'Too short!',
        'text' => "Select how many entries should be listed.",
        'size' => 8,
        'isrequired' => 1,
        'validation' => 'string|minlen=1'
    ));
   
    /**
     * Add the form to our (referenced) $form_html. Make sure you use the same key
     * as the first parameter to $PIVOTX['extensions']->getAdminForm
     */
    $form_html['popent'] = $PIVOTX['extensions']->getAdminFormHtml($form, $popent_config);

}

?>
Kay
Contributor
 
Posts: 24
Joined: Sun Jan 11, 2009 10:48 pm

Re: how to make an extension

Postby hansfn » Mon Jan 26, 2009 7:36 am

You would have seen the error immediately in the server error logs - don't you have access to them? Most hosting services do give you access. Anyway, without testing the code I wonder if the problem is "get_entries_count()" - try replacing it with "$PIVOTX['db']->get_entries_count()". I don't think you should make the number of entries a config option, it should be a tag parameter.

PS! When the code is complete, please consider submitting it to me/us as a patch for the existing bbclone extension - IMHO this should be a separate thing.
hansfn
Developer
 
Posts: 3282
Joined: Sun Nov 25, 2007 7:48 pm
Location: Molde, Norway

Next

Return to 2.x Extensions

Who is online

Users browsing this forum: No registered users and 3 guests

cron