Go Back   vb.org Archive > vBulletin Article Depository > Read An Article > vBulletin 4 Articles
Reload this Page Writing a basic widget.
FAQ Community Calendar Today's Posts Search

Reply
 
Thread Tools
Writing a basic widget.
Carnage
Join Date: Jan 2005
Posts: 760

 

uk
Show Printable Version Email this Page Subscription
Carnage Carnage is offline 02-17-2010, 10:00 PM
This guide will show you how to make a widget properly. I'm basing this on how I created a Top Posters widget, the source code for the entire widget will be avaliable as a mod on here in the next few days. I will update this page once that has been done. I used the default vbulletin direct php execution widget as a template for this; If you are struggling to follow this, taking a look at the code in there would be a good idea as its fairly simple and easy to follow.

Step 1.
Create a product in the normal manner. Make a note of your product id.

Step 2.
You need to insert rows into the following tables, this will eventually need to be done in the installation code, however for development purposes you can just insert it manually.

Package:
  • packageid
    - auto inc field, leave blank but make a note of the number it gets set to
  • productid
    - your product id
  • class
    - any valid name for a php class. This name will be used as a prefix for ALL the classes you make, ensure its unique enough to prevent clashes with other mods; vbCms, vbBlog or any other name begining vb should be avoided

Cms_widgettype:
  • widgettypeid
    - auto inc field, leave blank
  • package
    - your packageid from before (auto inc from package table
  • class
    - any valid name for a php class. This name will be used as a postfix for all your classes; you can be fairly uncreative here; but make sure its unique within your package.

Step 3:
In this step, we will create the required directory structure for a widget.

In the packages directory of your vbulletin installation you will need to create a new directory. This should match the class name from the Packages table however should be lowercase.

Inside this directory you need to create two directories named widget and item and inside the item directory, you need to create a second widget directory

the setup looks a bit like this:
  • packages
    • packageclassname
      • item
        • widget
      • widget

Step 4:
The item file.

For your widget to function, it needs an item class. This should be placed inside the item/widget directory. It should be named after your widget class name (from the widgettype table) The following code is the basic requirement for a widget item class:

PHP Code:
class yourPackageClassName_Item_Widget_yourWidgetTypeClassName extends vBCms_Item_Widget
{
    protected $package = 'yourPackageClassName';
    protected $class = 'yourWidgetTypeClassName';
    protected $config = array();
} 
Step 5:
The widget file.

The widget file is what does the work. It should be placed in the widget directory. It should be named after your widget class name (from the widgettype table) The following code is the basic requirement for a widget class:

PHP Code:
class yourPackageClassName_Widget_yourWidgetTypeClassName extends vBCms_Widget
{
    protected $package = 'yourPackageClassName';
    protected $class = 'yourWidgetTypeClassName';
    protected $canconfig = false;

    public function getPageView()
    {
         $this->assertWidget(); 
         $view = new vBCms_View_Widget('yourpackageclassname_widget_yourwidgettypeclassname_page');             $view->class = $this->widget->getClass();
         $view->title = $view->widget_title = $this->widget->getTitle();
         $view->description = $this->widget->getDescription();
         return $view;
    }
} 
Step 6:
the widget template.

Create the template yourpackageclassname_widget_yourwidgettypeclassnam e_page I suggest copying the contents of the static html widget template into it. You can then replace the {vb:var} for the content with your own template code.

For registering variables, its done differantly than to the rest of the forum. In the getPageView function, you need to set the propertys of the view object instead. If you would normally do $templater->register('myvar',$myvar) instead do $view->myvar = $myvar

Step 7:
You also need to create some phrases; anything your widget uses in its template should be a phrase in order to assist translations, you must also create the phrase widgettype_yourpackageclassname_yourwidgettypeclas sname in the group CMS widget types, this is the name of the type that gets displayed in the admin cp, don't forget to select your product from the drop down so that the phrase gets exported with your product. Any other phrases you need should be created in the Content Management System group.

There may be other phrases that are needed, but so far my widget is working fine using just the widgetype phrase and some others for inside its templates.

Step 8:
Install code; the install code is easy for this basic widget; all you need to do is write code to do this table inserts from step 2.

This is a bit of a work in progress, i've not yet found all the phrases that need to be added and theres more work to be done to allow configuring a widget, but these basics should get you started until i've finished this guide.
Reply With Quote
  #2  
Old 02-18-2010, 09:52 PM
cellarius's Avatar
cellarius cellarius is offline
 
Join Date: Aug 2005
Posts: 1,987
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Great one, thanks Carnage! Looking forward to see this finished.
Reply With Quote
  #3  
Old 02-19-2010, 02:38 AM
Mythotical Mythotical is offline
 
Join Date: Jun 2004
Location: Booneville, AR, USA
Posts: 1,428
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Very nice, you gave a tut on doing it by inserting into the database, I did one by adding and using a custom template.
Reply With Quote
  #4  
Old 03-08-2010, 08:49 AM
Carnage Carnage is offline
 
Join Date: Jan 2005
Location: uk
Posts: 760
Благодарил(а): 0 раз(а)
Поблагодарили: 0 раз(а) в 0 сообщениях
Default
Creating a new widget requires creating a lot of code which is repeated for every widget, to assist in this process i've created the widget wizard.

Using this wizard skips a lot of the steps above. It creates:
  • A product file including the minimum required template, phrase and install code
  • The directory structure required
  • The widget item file
  • The widget controler file.

All you need to do to create a widget now is:

1. Fill out the form here: http://vb4.giveupalready.com/ww/wizard.php

2. Install the product and upload the files provided.

3. Fill in the code logic for your widget display (packages/yourpackage/widget/yourwidget.php) you'll need to add some logic to the getViewData() function to fill out the information you want in your widget; basic information is already filled out for you.

4. Edit the provided template (yourpackage_widget_yourwidget_page) again, it contains basic markup, you just need to replace the <vb:comment></vb:comment> tags i've left in there with your own content.

4. Optional extra if you wish to release your widget on vborg: write some uninstallation code; essentially needs to do the opposite of the installation code. (I left it out on purpose as if someone decided to play around with this and was uncreative with their package name they could end up trashing their board by removing default vb widgets)

When I finish the tutorial on widgets to include adding widget configs; I will update the wizard to generate those functions as well.
Reply With Quote
Reply

« Previous Thread | Next Thread »

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts
BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Forum Jump


All times are GMT. The time now is 10:01 AM.

Contact Us - Archive - Top

Powered by vBulletin® Version 3.8.12 by vBS
Copyright ©2000 - 2024, vBulletin Solutions Inc.
X vBulletin 3.8.12 by vBS Debug Information
  • Page Generation 0.03887 seconds
  • Memory Usage 2,240KB
  • Queries Executed 17 (?)
More Information
Template Usage:
  • (1)SHOWTHREAD
  • (1)ad_footer_end
  • (1)ad_footer_start
  • (1)ad_header_end
  • (1)ad_header_logo
  • (1)ad_navbar_below
  • (1)ad_showthread_beforeqr
  • (2)bbcode_php
  • (1)footer
  • (1)forumjump
  • (1)forumrules
  • (1)gobutton
  • (1)header
  • (1)headinclude
  • (1)modsystem_article
  • (1)navbar
  • (4)navbar_link
  • (120)option
  • (4)post_thanks_box
  • (4)post_thanks_button
  • (1)post_thanks_javascript
  • (1)post_thanks_navbar_search
  • (4)post_thanks_postbit_info
  • (3)postbit
  • (4)postbit_onlinestatus
  • (4)postbit_wrapper
  • (1)spacer_close
  • (1)spacer_open
  • (1)tagbit_wrapper 
Phrase Groups Available:
  • global
  • inlinemod
  • postbit
  • posting
  • reputationlevel
  • showthread
Included Files:
  • ./showthread.php
  • ./global.php
  • ./includes/init.php
  • ./includes/class_core.php
  • ./includes/config.php
  • ./includes/functions.php
  • ./includes/class_hook.php
  • ./includes/modsystem_functions.php
  • ./includes/functions_bigthree.php
  • ./includes/class_postbit.php
  • ./includes/class_bbcode.php
  • ./includes/functions_reputation.php
  • ./includes/functions_post_thanks.php 
Hooks Called:
  • init_startup
  • init_startup_session_setup_start
  • init_startup_session_setup_complete
  • cache_permissions
  • fetch_threadinfo_query
  • fetch_threadinfo
  • fetch_foruminfo
  • style_fetch
  • cache_templates
  • global_start
  • parse_templates
  • global_setup_complete
  • showthread_start
  • showthread_getinfo
  • forumjump
  • showthread_post_start
  • showthread_query_postids
  • showthread_query
  • bbcode_fetch_tags
  • bbcode_create
  • showthread_postbit_create
  • postbit_factory
  • postbit_display_start
  • post_thanks_function_post_thanks_off_start
  • post_thanks_function_post_thanks_off_end
  • post_thanks_function_fetch_thanks_start
  • post_thanks_function_fetch_thanks_end
  • post_thanks_function_thanked_already_start
  • post_thanks_function_thanked_already_end
  • fetch_musername
  • postbit_imicons
  • bbcode_parse_start
  • bbcode_parse_complete_precache
  • bbcode_parse_complete
  • postbit_display_complete
  • post_thanks_function_can_thank_this_post_start
  • tag_fetchbit_complete
  • forumrules
  • navbits
  • navbits_complete
  • showthread_complete