PHPCow Documentation

Feed Management

phpcow — Wed, 19 Nov 2008 10:40:56 -0500

Feed Management

Through our Feed Directory interface, you can easily manage content categories and feeds in one place. No need for jumping between pages, as everything you need is composed as a single page application. With its integrated drag and drop functionality you can easily achieve your goals with minimum effort.

Language Tools

phpcow — Wed, 19 Nov 2008 10:41:43 -0500

Language Tools

MyWeb supports i18n and is not limited to only one language; this tool will be your perfect assistant for creating, translating and managing languages to tailor the system to your users needs. You can create one or more languages for each of the countries (for example there are four languages in Switzerland) and easily manage them.

Local Content

phpcow — Wed, 19 Nov 2008 10:41:09 -0500

Local Content

Through the local content interface, you can choose any country from selected region and create content (logically organize feeds into categories) that is related to the selected country, allowing dashboard users to select content not only by topic but also by their geographical preferences.

MySql Tools

phpcow — Wed, 19 Nov 2008 10:39:49 -0500

MySql Tools

MySql Toolbox allows you to manage your database. You can perform necessary database related actions through this easy-to-use interface. With just a few mouse clicks you can: Optimize, Analyze, Check, Repair, Export and even browse a table's content and its structure.

System Logs

phpcow — Wed, 19 Nov 2008 10:40:26 -0500

System Logs

System Logs combines both, CP Login Logs and CP Action logs administrative tools.

CP Action Logs

Through CP Logs you can monitor all actions of your Control Panel users. You are able to see their activity, as well as search or remove old and unnecessary data.

CP Login Logs

Through this interface you can easily monitor users who have accessed or tried to access your control panel. You can see login status, and examine logged HTTP data.

User Management

phpcow — Wed, 19 Nov 2008 10:41:31 -0500

User Management

User management interface is the main tool for managing all of your users if you are running MyWeb as a standalone service, and using it, you can easily create, edit, activate or disable users.

Widget Management

phpcow — Wed, 19 Nov 2008 10:41:20 -0500

Widget Management

Through the Widget Management Interface, you can decide which widget will be available for dashboard users. Install/uninstall can be done with just one click. Also you can easily configure widgets through the same interface as some of the widgets require additional configuration parameters (e.g. API key, User ID).

Advanced Widget Example

phpcow — Wed, 19 Nov 2008 10:44:59 -0500

Advanced Widget Example

In this article we will create Google Search Widget based on Google AJAX Search API. First of all lets look at this document to find out what Google offers. As you can see Google returns JSON response that we will use for implementing Google Search Widget.

Lets begin with creating required files. As you may remember from hello world example there are one required folder and two required files, but for this example we will use additional CSS file. Look at the picture:

Now open config.xml file and copy and paste following xml code:

<?xml version="1.0" encoding="UTF-8"?>
<widget name="googlesearch" icon="google" section="search">
    <title>Google Search</title>
    <description>
        <![CDATA[Google Search Widget]]>
    </description>
    <tags>
        <![CDATA[google, search]]>
    </tags>
</widget>

Note that configuration file is not required for development version.

Thats it, we are done with configuration. Now we need to define our goals. First of all lets decide what user interface component we need, these are:

HTML form with input field and button to submit queries
Search result area where returned result will be displayed
Pagination control because returned result can be quite long

Now based on defined requirements lets create widget skeleton and setup it:

(function() {
 
    function GoogleSearch() {
 
        /**
         * create initial configuration
         */
        this.config = {
            name: 'googlesearch',   //widget name
            title: 'Google Search', //widget title
            iconId: 'google',       //icon identifier
            css: true               //tell widget engine that it needs to load widget's CSS file
        };
 
        /**
         * onload event will be triggered after widget completed loding
         * perform user interface setup here
         */
        this.onload = function() {
 
            /**
             * create HTML form with ascribed input elements and result area
             */
            this.setContent(
                '<form method="post" action="" class="google-search-form">' +
                    '<input type="text" name="q" />' +
                    '<input type="button" name="search" value="Search" />' +
                '</form>' +
                '<div class="google-search-results">Nothing to show...</div>'
            );
 
            /**
             * setup Pagination UI component
             */
            var pagination = UDW.Components.Pagination.getComponent(
                {
                    currentPage: 1,            //starting page
                    rowsPerPage: 4,            //number of results per page
                    rowName: 'results',        //name of the collection in the result-set
                    callback: function(rows) { //callback function to process result-set
 
                        var html = [];
			html.push('<ul>');
 
                        for (var i = 0; i < rows.length; i++) {
                            html.push('<div class="google-search-link">');
                            html.push('<a href="' + rows[i].url + '" target="_blank">' + rows[i].title + '</a>');
                            html.push('</div>');
                            html.push('<div class="google-search-content">' + rows[i].content + '</div>');
                            html.push('<div class="google-search-visible-url">' + rows[i].visibleUrl + '</div>');
                        }
 
                        html.push('</ul>');
 
                        //push generated HTML code to search result area
                        $('div.google-search-results', widget.getBody()).html(html.join(''));
 
                    }
                }
            );
 
            //add pagination to the widget's footer section
            this.addToFooter(pagination);
 
        };
 
    };
 
    UDW.registerWidget('googlesearch', GoogleSearch);
 
})();

Now, if you try to load the widget you will see something like this:

Widget's UI is completed, now we can continue to coding widget's search logic. First of all it is necessary to bind callback function to the search button. This goal can be achieved with following code:

$('input[type=button]', widget.getBody()).on('click', function() {});

Code just searches “button” and binds callback function to its “onclick” event. Now we can begin coding of actual search logic:

 
//obtain reference to the widget
var widget = this;
 
//bind function to button's onclick event
$('input[type=button]', widget.getBody()).on('click', function() {
 
    //google search URI	
    var uri = 'http://ajax.googleapis.com/ajax/services/search/web?v=1.0&rsz=large&q={query}';
 
    //build request URI
    uri = uri.replace('{query}', this.form.q.value);
 
    //find result area
    var body = $('div.google-search-results', widget.getBody());
 
    //set pre-loader to the result area
    body.html(widget.getPreloader());
 
    /**
     * use getJSON API method to perform Ajax request
     */
    UDW.proxy.getJSON(
        {
            uri: uri, //uri to be requested
            callback: function(result) { //callback function
                //process response data
                pagination.process(result.responseData);
            }
        }
    );
 
})

As you see from the code above search logic is quite simple. All you need is to use “getJSON” API method with to parameters uri and callback. After request completes callback function is invoked that on other hand invokes Pagination component's “process” method to process returned results.

Example shows how simple and powerful API is. Most of the code is just using predefined API methods. If you completed coding you can see that resulting widget looks something like this:

Complete JavaScript code and CSS required for this widget is shown below:

googlesearch.js

(function() {
 
    function GoogleSearch() {
 
        this.config = {
            name: 'googlesearch',
            title: 'Google Search',
            iconId: 'google',
            css: true
        };
 
        this.onload = function() {
 
            this.setContent(
                '<form method="post" action="" class="google-search-form">' +
                    '<input type="text" name="q" />' +
                    '<input type="button" name="search" value="Search" />' +
                '</form>' +
                '<div class="google-search-results">Nothing to show...</div>'
            );
 
            var pagination = UDW.Components.Pagination.getComponent(
                {
                    currentPage: 1,
                    rowsPerPage: 2,
                    rowName: 'results',
                    callback: function(rows) {
                        var html = [];
                        html.push('<ul>');
                        for (var i = 0; i < rows.length; i++) {
                            html.push('<div class="google-search-link">');
                            html.push('<a href="' + rows[i].url + '" target="_blank">' + rows[i].title + '</a>');
                            html.push('</div>');
                            html.push('<div class="google-search-content">' + rows[i].content + '</div>');
                            html.push('<div class="google-search-visible-url">' + rows[i].visibleUrl + '</div>');
                        }
                        html.push('</ul>');
                        $('div.google-search-results', widget.getBody()).html(html.join(''));
                    }
                }
            );
 
            this.addToFooter(pagination);
 
            var widget = this;
 
            $('input[type=button]', widget.getBody()).on('click', function() {
 
                var uri = 'http://ajax.googleapis.com/ajax/services/search/web?v=1.0&rsz=large&q={query}';
                uri = uri.replace('{query}', this.form.q.value);
 
                var body = $('div.google-search-results', widget.getBody());
                body.html(widget.getPreloader());
 
                UDW.proxy.getJSON(
                    {
                        uri: uri,
                        callback: function(result) {
                            pagination.process(result.responseData);
                        }
                    }
                );
 
            })
 
        };
 
    };
 
    UDW.registerWidget('googlesearch', GoogleSearch);
 
})();

googlesearch.css

form.google-search-form {
    width: 100%;
    text-align: center;
    margin: 4px 0;
}
 
div.google-search-results {
    border: 1px solid #dedede;
    padding: 6px;
    margin: 12px 0 0 0;
}
 
div.google-search-link a {
    color: blue;
}
 
div.google-search-content {
    margin: 2px 0;
}
 
div.google-search-visible-url {
    color: green;
    margin-bottom: 8px;
}

Creating Widget Icon

phpcow — Wed, 19 Nov 2008 17:07:17 -0500

Creating Widget Icon

Maybe you already noticed that all widgets have icons on the upper left corner and most likely you would like to create icons for your widgets. This goal is achieved through little CSS trick that you can use effectively.

If you carefully red previous topics about widget development most likely you noticed that initial configuration parameters contains one parameter named “iconId”:

this.config = {
   name: 'googlesearch',
   title: 'Google Search',
   iconId: 'google'
}

Value of the mentioned parameter is just name of the icon's CSS class name. Widget engine uses this value for generating full CSS class name according to icon class name rules and assigns this value to the HTML elements class attribute.

Icon's class name has following format: wdg-icon-google. It is important to note that “wdg-icon-” prefix is required for all icon classes and the name off full class name is suffixed with unique name of the icon.

For creating your own icons classes you need to use CSS code like this:

.wdg-icon-myiconidentifier {
    background: url(mywidgeticons.png) no-repeat top left;
}

Now if you need to set this icon to your widget you need to do it with following way:

this.config = {
   name: 'googlesearch',
   title: 'Google Search',
   iconId: 'myiconidentifier'
}

Note again that for assigning icon to the widget you just need to use its name.

There is only one restriction with icons, icons need to be created as 16x16 images.

Developer Version

phpcow — Thu, 20 Nov 2008 06:24:34 -0500

Developer Version

For effectively developing widgets developers need to download and install Developer Version of the framework. Developer version is a simplified version of MyWeb's core.

Developers will find all necessary API - s that are required for creating fully functional widgets. Developer version consists of following parts:

Please read documentation carefully before beginning widget development.

System Requirements

To begin widget developments developers need to satisfy minimal system requirements. Read details below:

Any operation system
Apache web server of any version
PHP of minimum version 5.2.3
Latest version of Zend Optimizer
Any editor for coding (Eclipse is a good candidate)
Any modern web browser (FireFox + FireBug is preferred during development)

Installing Developer Version

First of all you need to download developer version of MyWeb: mywebdev.zip. Installation is simple and requires zero configuration. You just need to extract downloaded zip file into your local webserver's root directory.

Note that developer version is intended for development purposes only, thus it will work only on localhost under "mywebdev" folder. Widgets will be accessible through http://localhost/mywebdev/

After installation you will see file structure shown on the picture below:

Thats it, installation and configuration are completed. Now you can begin development of a widget. First of all open “index.html” file(look at the selected file on the picture above). This is entry point where developers can load and test widgets on demand, without any further configuration. Lets look of the file structure:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" type="text/css" href="udw/assets/styles/style.css"/>
    <script type="text/javascript" src="udw/js/udwdev.js"></script>
</head>
<body>
 
 
<!-- target container where widget will be inserted -->
<div id="w1"></div>
 
<script type="text/javascript">
 
loadWidget(
    {
        widget: 'googlesearch', 
        target: 'w1', 
        style: 'white'
    }
);
 
</script>
 
</body>
</html>

This file contains all required script and style includes that are required for loading and running widgets. Only part worth of mentioning is “loadWidget()” JavaScript function that is invoked for loading actual widgets. It requires one parameter with structure shown below:

Key name	Description	Required
widget	Name of the widget to be loaded	Yes
target	ID of the target HTML element where the loaded widget will be inserted	Yes
style	Initial style of the widget. You can choose from white, blue, red, yellow or green	No

For example for loading “helloworld” widget you need to write following code:

loadWidget(
    {
        widget: 'helloworld', 
        target: 'w1', 
        style: 'white'
    }
);

Please note that "loadWidget()" function call must be placed after target HTML element, otherwise behavior of widget loader is not predictable. Also it is important to mention that you don't need to load widget's JavaScript and/or CSS files explicitly. These tasks will be performed by widget loader.

For further information and details on widget development please visit following documents:

Generic Widgets

phpcow — Wed, 19 Nov 2008 10:44:41 -0500

Generic Widgets

There are few Generic Widgets supported by my web personalized start page system. Besides entire Widget API it is possible to use these generic widgets for your own widget enhancements. Currently there are three generic widgets that can be used for ascribed purposes: Feed, Tabbed Feed and Search.

To use one of generic widgets you need to write simple code as follows:

(function() {
 
    function MyTabbedNewsWidget() {        
 
        /**
         * Inherit from Tabbed Feed Widget
         */
        this.base = UDW.widgets['__tabbedfeed__'];
        this.base();
 
        //rest of code here
 
    };
 
    UDW.registerWidget('mytabbednewswidget', MyTabbedNewsWidget);
 
})();

Example with Tabbed Feed Widget

Tabbed Feed widget is a powerful widget that allows to quickly and effectively build any type of news feed widgets. Most of news sites provide RSS Feed channels that can be used by third parties. Instead of using one RSS channel per widget we decided to build generic widget that could be able to handle multiple RSS channels from single or multiple sources.

For example consider CNN's RSS channels page, there are dozens of links to different RSS feeds. Using Tabbed Feed Widget it is possible to manage all of these channels at one time.

Let's look closer to these RSS feeds links:

Only deference among these links are keywords uniquely identifying channels(in this case: world, africa and americas). In most cases all RSS Feed providers use same generalized approach. These commonality gives us opportunity to use URI only once, only thing we need is to use placeholder for keyword that identifies particular channel.

In this particular case the URI template will look something like this: http:/ /rss.cnn.com/rss/edition_{tag}.rss

Based on these details we can easily implement fully functional widgets providing just necessary configuration parameters. Look at the code below:

(function() {
 
    function CBSNews() {
 
        /**
         * Inherit from tabbed feed widget
         */
        this.base = UDW.widgets['__tabbedfeed__'];
        this.base();
 
        /**
         * setup initial configuration
         */
        this.config = {
            name: 'cbsnews',
            iconId: 'cbsnews',
            title: UDW.str('CBS News'),
            content: ''
        };
 
        this.onload = function() {
 
            /**
             * Set tags and label mappings
             */
            this.setTagMap({
                'Top Stories': 'CBSNewsMain',
                'U.S.': 'CBSNewsNational',
                'World': 'CBSNewsWorld',
                'Politics': 'CBSNewsPolitics',
                'Sci-Tech': 'CBSNewsSciTech',
                'Health': 'CBSNewsHealth',
                'Entertainment': 'CBSNewsEntertainment',
                'Business': 'CBSNewsBusiness',
                'CBS News Video': 'CBSNewsVideo',
                'CBS Evening News': 'CBSNewsEveningNews',
                '48 Hours': 'CBSNews48Hours',
                '60 Minutes': 'CBSNews60Minutes',
                'Strange News': 'CbsNewsApStrange',
                'PC Answer' : 'CBSNewsPCAnswer'
            });
 
            /**
             * Set initial tags to be displayed after load
             */
            this.setInitialTags(['Top Stories', 'Entertainment', 'Strange News', 'Business']);
 
            /**
             * Set URI pattern to be used for generating feed URIs
             */
            this.setFeedURI('http://feeds.cbsnews.com/{tag}');
 
            /**
             * Set logo of the widget
             */
            this.setLogo('cbsnews', 'cbsnews.gif', 'CBS News');
 
            /**
             * Render configured widget
             */
            this.render();
 
        };
 
    };
 
    UDW.registerWidget('cbsnews', CBSNews);
 
})();

Shown code will produce following widget:

If you carefully read the code it must be clear already how fast it is possible to create widget for desired RSS feed providers. But lets look closer at API methods provided by tabbed feed widget.

Below are listed all supported API methods:

Method	Description	Example
widget.setTagMap(map)	Sets initial configuration for desired RSS channels, in the form of key/value map	this.setTagMap({ 'Top Stories': 'CBSNewsMain', 'U.S.': 'CBSNewsNational', 'World': 'CBSNewsWorld' });
this.setInitialTags(tags)	Set desired labels array to be displayed first	this.setInitialTags([ 'Top Stories', 'Entertainment', 'Strange News', 'Business' ]);
this.setFeedURI(uriPattern)	Set URI pattern for particular RSS channel provider	this.setFeedURI('http://feeds.cbsnews.com/{tag}');
this.setLogo(widgetName, logo, altText)	Sets logo image for the widget.	this.setLogo('cbsnews', 'cbsnews.gif', 'CBS News');
this.render()	Renders pre-configured widget	this.render()

Example with Search Widget

As far as most well known search engines opened their search providing search results in various formats(e.g RSS or Atom feed) it became possible to build custom search widgets. Like with tabbed feeds sometimes it is better to combine these search engines into one single widget. Examples of these type of widgets could be found among already implemented PHPCow widgets(Web Search, News Search, Blog Search, Video Search). But of course these already implemented widgets are not complete as far as there are much more search result providers in the globe. For these purposes we implemented Generic Search Widget that will help you to build your own search widgets, grouping various search engine service providers into the single implementation.

Usage of this widget has a lot in common with previously described tabbed feed widget, but it is much more simpler. All you need is to add as many search engines to the widget instance as you like.

Code shown below is complete implementation of News Search widget:

(function() {
 
    function NewsSearch() {
 
        /**
         * Inherit form Search Widget
         */
        this.base = UDW.widgets['__searchwidget__'];
        this.base();
 
        /**
         * Set initial configuration
         */
        this.config = {
            name: 'newssearch',
            iconId: 'newssearch',
            title: UDW.str('News Search'),
            content: ''
        };
 
        this.onload = function() {
 
            this.setTitle(this.getValue('title') || 'Universal News Search');
 
            /**
             * This and following methods with same name will register search engines
             */ 
            this.addEngine('google', {
                label: 'Google',
                uri: 'http://news.google.com/news?hl=en&q={query}&ie=UTF-8&output=rss', 
                active: true
            });                
            this.addEngine('yahoo', {
                label: 'Yahoo',
                uri: 'http://news.search.yahoo.com/news/rss?p={query}&ei=UTF-8'
            });
            this.addEngine('live', {
                label: 'Live',
                uri: 'http://search.live.com/news/results.aspx?q={query}&format=rss'
            });
            this.addEngine('ask', {
                label: 'Ask.com',
                uri:   'http://news.ask.com/newsrss?q={query}&o=0&l=dir'
            });
 
            /**
             * Render pre-configured widget
             */
            this.render();
 
        };
 
    }
 
    UDW.registerWidget('newssearch', NewsSearch);
 
})();

Shown code will produce following widget:

There are only two API methods provided by Search widget that are listed below:

Method	Description	Example
this.addEngine(engineName, params)	Adds search engine to the search engine map. The firs parameter is key that uniquely identifies search engine. The second parameter provides label for search engine and URI pattern with {query} placeholder that will be replaced with provided search keyword	this.addEngine('live', { label: 'Live', uri: 'http://example.com/news?q={query}&alt=rss' });
this.render()	Renders pre-configured widget	this.render()

Hello World Widget

phpcow — Wed, 19 Nov 2008 10:42:38 -0500

Hello World Widget

For creating real working widget it is required two files, these files are:

helloworld.js - actual widget implementation
config.xml - configuration descriptor of the widget

Under the “udw” folder create new folder and name it “helloworld”. Under the newly created folder create two files as listed above. After performing these steps you will get structure shown on the picture:

First of all we need to write widget's implementation code. Open helloworld.js file and copy and paste code shown below:

(function() {
 
    /**
     * Define widget class
     */
    function HelloWorld() {
 
        /**
         * set initial configuration
         */
        this.config = {
            name: 'helloworld',
            title: 'Hello World Widget'
        };
 
        /** 
         * disable refresh button because there is nothing to refresh
         */
        this.disableRefresh = true;
 
        this.onload = function() {
            //set content
            this.setContent('<p>Hello World!</p>');
        };
 
    }
 
    //register widget
    UDW.registerWidget('helloworld', HelloWorld);
 
})();

Now open “index.html” file under “mywebdev” folder and replace widget loading script with following code:

loadWidget(
    {
        widget: 'helloworld', 
        target: 'w1', 
        style: 'white'
    }
);

After saving file open following URL: http://localhost/mywebdev

Following section is only necessary for deploying widget in dashboard environment.

After implementing widget, we need to specify configuration details. Open config.xml file and copy and paste following configuration code:

<?xml version="1.0" encoding="UTF-8"?>
<widget name="helloworld" icon="default" section="basic">
    <title>Hellow World</title>
    <description>
        <![CDATA[This is my first widget]]>
    </description>
    <tags>
        <![CDATA[hello, world]]>
    </tags>
</widget>

Thats it! Implementation of fully functional widget is completed. Now it is necessary to activate newly created widget through control panel. After activation navigate to the section specified in the config.xml file(in this case see “Basic Widgets” section) and add widget to the dashboard. Result is shown on the picture:

This is really simple example, but it clearly shows how easy is widget development process. With similar success you can develop widgets of any complexity. There are no limitations, only limitation is particular developer's skills and fantasy.

We hope that this example will be perfect jump-start for further development widgets of your own.

JavaScript API - CodeQ

phpcow — Wed, 19 Nov 2008 11:53:48 -0500

JavaScript API - CodeQ

As far as widgets are completely implemented using JavaScript programming language, developers often need to do a lot of work manipulating DOM elements. Because it is critical to keep widgets as small as possible due to eliminating widgets load time it would be useful to have JavaScript framework that eliminates unnecessary DOM elements manipulation to minimum.

There were few really great JavaScript frameworks, but PHPCow developers choose to go their way and implemented small but effective framework named CodeQ.

Framework consists of three major parts - Selector Engine, DOM Manipulation and CSS Manipulation. CodeQ has lot in common with perfect jQuery framework, but it is simpler and smaller, if you are familiar with jQuery than you need to just learn few differences.

Selector Engine

Selector engine supports most of the frequently used CSS selectors. For example:

$('#my-element-id > ul li > div.my-class').css('border', '3px solid green');

Shown simple example is quite descriptive for people familiar with CSS selectors. Shown example uses CSS selector that contains ID, Tag and Class selectors. Developers can build quite complicated queries for retrieving DOM elements.

It is possible to pass several selectors at one time, and engine will return results for all selectors. Developer needs to pass selectors separated by commas:

$('div.class-name, #el-id > p, ul li > a').css('border', '3px solid green');

Selector method supports context parameter as well, rather than forcing engine to traverse whole document it is possible to pass context object as second parameter eliminating time for searching desired elements:

var el = someDomElement;
$('a em', el).css('border', '3px solid green');

DOM Manipulation

CSS Manipulation

For manipulating with DOM element's styles, engine provides one method that has double behavior. For example following example will retrieve all <p> tags from the widget and changes borders of found elements:

$('#widget-id p').css('border', '3px solid blue');

Sometimes it is necessary to change several styles for found element, following example shows this technique:

$('#my-element-id > ul li > div.my-class').css(
    {
        border: '3px solid green',
        mariginTop: '6px',
        backgroundColor: '#dedede'
    }
);

As you can see it is possible to pass single JavaScript object to the same method. Besides “css()” method engine supports methods for element's class attribute manipulation:

Method	Description	Example
$('#widget').setClass(className)	Sets new css class	$('#widget').setClass('my-class')
$('#widget').removeClass(className)	Removes css class	$('#widget').removeClass('my-class')
$('#widget').addClass(className)	Adds css class to already existing class(es)	$('#widget').addClass('my-class')

Overriding Widget Styles

phpcow — Wed, 19 Nov 2008 14:49:05 -0500

Overriding Widget Styles

Often it is necessary to override predefined CSS styles of the widget. Styles are defined globally and are part of the dashboard theme, but thanks to widget structure it is possible to override most of the parts of the widget CSS styles.

Returning to the image that shows general structure of the widget(see picture below) it will became clear that there are just few segments that are important:

Parts of our interest are Widget Title, Widget Body and Widget Footer. There are three appropriate CSS classes that allow accessing these parts. To access mentioned parts of the widget following CSS selectors will be used:

For Widget Header - div.widget-header
For Widget Title - div.widget-title
For Widget Body - div.widget-content-wrapper
For Widget Content - div.widget-content
For Widget Footer - div.widget-footer

But, as far as there is no mechanism to uniquely identify widgets with permanent ID so that it could be usable in the widget's style-sheet few little tricks are required for achieving this goal.

For setting custom styles open already built “HelloWorld” widget's folder and add new CSS file with the name “helloworld.css” to it.

Now we need to define CSS class that will distinguish HelloWorld widget from other widgets, “helloworld” will be perfecto choice for this example. Now open newly created CSS file and copy and paste following CSS code:

div.helloworld div.widget-header {
    background: #333;
}
 
div.helloworld div.widget-title {
    color: #fff;
}
 
div.helloworld div.widget-content-wrapper {
    margin: 0;
    background-color: #999;
}
 
div.helloworld div.widget-content p {
    padding: 8px;
    text-align: center;
    color: #333;
    font-size: 2em;
}
 
div.helloworld div.widget-footer {
    background-color: #666;
    padding: 8px;
}
 
div.helloworld div.widget-footer p {
    color: #fff;
    font-weight: bold;
    text-align: center;
}

Now open “helloworld.js” file and replace “this.onload” method with following JavaScript code:

this.onload = function() {
 
    //add "helloworld" class name to the widget instance        
    $(this).addClass('helloworld');
 
    //set initial content    	
    this.setContent('<p>Hello World!</p>');
 
    //add some HTML content to the widget's footer
    this.addToFooter('<p>Testing Footer Style</p>');
 
};

Thats it, after refreshing widget page you will see result shown on the picture below:

Storing Widget Data

phpcow — Wed, 19 Nov 2008 14:15:48 -0500

Storing Widget Data

Sometimes preferences are not enough for managing widget's state. There are types of widgets that require storing more complex data structures than built-in preferences system can handle.

For this purposes there are special type of methods defined by widget specification that are intended for working with such complex cases.

These methods are:

Method	Description
widget.setData(data)	Accepts parameter of Array or Object type. Complexity of passed parameter is not restricted
widget.getData()	Returns Array or Object that is associated with widgets previous state

Examples of widgets that need to store complex data with it's state are for example Address Book, Bookmarks or Stock Quotes. Data required with these widgets is created and managed by user thus support for storing and retrieving user data is critical.

Note that data stored by noted API methods could be serialized as JSON string, passing an invalid type of object will cause problems. For more information please see JSON specification.

Example of using these methods could be as simple as shown in the code below:

this.onload = function() {
 
   //retrieve previously saved data
   var data = this.getData();
 
   //if data object is not null print data
   if (data) {
      for (var i in data) {
         this.addContent(data.title); 
      }
   } else {
 
      //create data object
      data = {
         title: 'Phone List',
         phones: [
            1235123123,
            0870700709,
            9697690900,
            9769769699
         ]
      };
 
      //store data associated with widget
      this.setData(data);
 
      //save the widget's state
      this.save();
 
   }
 
}

Shown example tries to retrieve previously saved data and if there is no data object associated with widget's current state it creates new data object and saves widget state. This way you can work as complex data structures as required by your widget.

Ajax API

phpcow — Wed, 19 Nov 2008 10:43:59 -0500

Ajax API

As shown in the widget API document there are four major methods that can be used for preforming Ajax calls. These methods are:

Ajax Methods

Method Name	Description
UDW.proxy.getText(params)	Returns result as plain text
UDW.proxy.getFeed(params)	Returns feed object or error object
UDW.proxy.getXML(params)	Returns result as XML document
UDW.proxy.getJSON(params)	Returns result as JSON object

Every method requires exact one parameter that is specified as JavaScript object. See example of using parameter:

UDW.proxy.getFeed({
    uri: 'http://rss.cnn.com/rss/edition_world.rss',
    callback: function(response) {
        //process response
    }
});

As far as Ajax calls are asynchronous it is impossible to handle response returned by invoked method immediately, thus it is required to pass callback function to the Ajax method. After request completes passed callback function is invoked with only one argument.

Type of the argument passed to the callback method depends on the invoked method. As shown above there are four methods for each particular request type.

UDW.proxy.getText

As we can see this method returns plain text after request completion. With this method it is possible to retrieve any text from any specified URI.

UDW.proxy.getText({
    uri: 'http://domain.com/document.txt',
    callback: function(response) {
        if (response) {
            widget.setContent(response);
        }
    }
});

UDW.proxy.getFeed

This method is special case. Invoking this method will return JSON object that is standardized form of feeds. Currently only RSS, Media RSS and Atom feeds of any versions are supported. Server side feed processor analyzes requested feed and builds standardized JSON object that is passed to the callback function later.

This is really useful part of the API. Instead of dealing with different types of XML documents widget authors can work with standardized JSON object. Among other advantages it is worth to note that working with JSON is significantly faster rather then parsing XML documents with DOM methods.

UDW.proxy.getText({
    uri: 'http://domain.com/rssfeed.xml',
    callback: function(feed) {
        if (feed) {
            var body = [];
            body.push('Feed title: ' + feed.title);
            body.push('Number of items: ' + feed.items.length);
            widget.setContent(body.join('<br />');
        }
    }
});

UDW.proxy.getXML

This method return XML object. This is very powerful method for working with any type of XML document.

UDW.proxy.getText({
    uri: 'http://domain.com/rssfeed.xml',
    callback: function(response) {
        if (response) {
            var doc = response.documentElement;
            var body = [];
            body.push('Feed title: ' + doc.getElementsByTagName('title')[0].nodeValue);
            body.push('Number of items: ' + doc.getElementsByTagName('item').lenght);
            widget.setContent(body.join('<br />');
        }
    }
});

UDW.proxy.getJSON

This method is intended to only work with JSON responses. Method receives and parses JSON text and passes prepared object to the callback function.

Suppose that we need to handle JSON document with following structure:

{
    "title": "This is document title",
    "description": "This is document description"
}

UDW.proxy.getText({
    uri: 'http://domain.com/jsondocument.php',
    callback: function(response) {
        if (response) {
            var body = [];
            body.push('Title: ' + response.title);
            body.push('Description: ' + response.description);
            widget.setContent(body.join('<br />');
        }
    }
});

Widget Anatomy

phpcow — Wed, 26 Nov 2008 08:11:38 -0500

Widget Anatomy

Anatomy of a widget is quite simple. Every widget consist of two required components: widget JavaScript file and configuration xml file. Other stuff such as CSS files, images or flash are not required and depend on particular widget implementation.

Widgets are segmented into four major parts. These parts are shown on the picture below:

As you can see from the picture above, anatomy of a widget is quite simple and shown parts(title, preferences, body and footer) can be easily managed through comprehensive Widget API.

Widget JavaScript Code

As widget's structure itself, code required for widget is quite simple as well. In its simples form widget could be expressed as simple as shown in the code snippet below:

(function() {
 
    /**
     * Widget class. Widget is being implemented like general javascript function 
     * Function doesn't require any additional parameters.
     * Instance of the widget is instantiated by Widget Engine
     */
    function MyWidget() {
 
        /**
         * Widget's initial configuration parameters.
         * Every widget must supply initial configuration parameters.
         * Parameters object has simple key/value structure
         */
        this.config = {
            name: 'mywidget',          //Name of the widget.
            iconId: 'mywidget',        //CSS class name of the widget icon
            title: 'This Is MyWidget', //Title of the widget
            content: ''                //Initial content of the widget, can be empty
        };
 
        /**
         * Widget API method that is called by Widget Engine after widget completes loading
         */ 
        this.onload = function() {
 
            /**
             * Widget API method, requires exactly one parameter,
             * parameter can be a DOM element or a String object.
             * Passed parameter will be rendered as a widget body.
             * 
             * @param Mixed DOM element or String Object
             */  
            this.setContent("This is My First Widget");
 
        }
 
    };
 
    /**
     * Add widget into the global registry
     * This step is mandatory, otherwise widget wouldn't be usable.
     * Note that the name of a widget and the name of a widget class can be different
     * 
     * @param String name of the widget
     * @param Function reference to actual widget
     */
    UDW.registerWidget('mywidget', MyWidget); 
 
})();

Widget Preferences

It is natural that widgets need some kind of preferences system. Customization feature is one of the useful for end users. Thus it is not surprise that our implementation supports powerful and comfortable preferences management system.

As you already seen from the above image of the widget, preferences are managed through simple UI. There are several types of preferences and they could be managed through JavaScript code as follows:

(function() {
 
    function MyWidget() {
 
        this.preferences = [
            {
                name: 'first_name',
                type: 'text',
                label: 'First Name',
                value: null
            },
            {
                name: 'married',
                type: 'checkbox',
                label: 'Married',
                checked: true,
                value: 1
            },
            {
                name: 'language',
                type: 'hidden',
                value: 'en'
            },
            {
                name: 'sex',
                type: 'list',
                label: 'Sex',
                list: ['male', 'female']
            },
            {
                name: 'range',
                type: 'range',
                label: 'Range of Numbers',
                start: 5,
                end: 100,
                step: 10
            }
        ];
 
    };
 
    //other parts of code are omited
 
})();

Shown example of preferences will produce UI with text box, checkbox, hidden and two drop-down fields. Example is self explanatory but supported types with descriptions are listed below:

Type	Attributes	Description	Example
text	name, type, label, value	Creates text element.	{ name: 'first_name', type: 'text', label: 'First Name', value: null }
checkbox	name, type, label, value, checked	Creates checkbox element. “checked” attribute's value can be specified as true or false	{ name: 'married', type: 'checkbox', label: 'Married', checked: true, value: 1 }
hidden	name, type, value	Creates hidden element	{ name: 'language', type: 'hidden', value: 'en' }
list	name, type, label, list, value	Creates drop-down list. If the value specified is equals to one of the elements listed in “list” attribute, this value will be selected	{ name: 'sex', type: 'list', label: 'Sex', list: ['male', 'female'], value: 'female' }
range	name, type, label, start, end, step, value	Creates drop-down list. start, end and step attributes are required. Shown example will produce drop-down list with options: 20, 40, 60, 80, 100 where option with value 40 will be selected	{ name: 'range', type: 'range', label: 'Range of Numbers', start: 20, end: 100, step: 10, value: 40 }

Shown table completely describes all supported preference types and their usage examples. Also note that for single widget you can use as many of supported preference types as you like.

For further manipulation of preferences and its values there are two API methods that you can access through particular widget instance. See table below:

Method Name	Description
widget.setValue(name, value)	Set specified value to preference specified as name
widget.getValue(name)	Returns value for specified “name” preference

It is important to note that, initial preference values are only set while first instantiation of the widget. All changed preference values are stored within widget state and later are used by the widget engine to instantiate widget according to these newly defined values.

Widget Configuration

Configuration XML file for shown widget is very simple as you can see from the XML code shown below:

<?xml version="1.0" encoding="UTF-8"?>
<widget name="mywidget" icon="mywidget" section="basic">
    <title>MyWidget</title>
    <description>
        <![CDATA[This is my very first widget]]>
    </description>
    <tags>
        <![CDATA[mywidget]]>
    </tags>
</widget>

Tags of configuration XML file and tag attributes are quite self explanatory. These are minimal tags and attributes required for widget final deployment. There are additional non required tags that are described in grater details in dedicated section.

Widget API

phpcow — Wed, 19 Nov 2008 10:43:27 -0500

Widget API

Widget Events

Method Name	Description
widget.onload()	Handled when widget completes load
widget.onPreferencesSave()	Handled when users hit preferences save button

Content Manipulation Methods

Method Name	Description
widget.setTitle(title)	Sets title of the widget.
widget.getTitle()	Returns current title of the widget
widget.setContent(content)	Sets content to the widget body. Specified parameter can be a String object or a DOM element. This methods replaces already existing content
widget.addContent(content)	Parameter can be as String as DOM element. Appends new content to already existing content
widget.getContent()	Returns HTML code of the widget body
widget.getBody()	Returns widget body as a DOM element
widget.setToFooter(content)	Sets content to the widget footer. Specified parameter can be a String object or a DOM element. This methods replaces already existing content
widget.addToFooter(content)	Parameter can be as String as DOM element. Appends new content to already existing content

Widget Preferences Methods

Method Name	Description
widget.setValue(name, value)	Set specified value to preference specified as name
widget.getValue(name)	Returns value for specified “name” preference

Widget Style Methods

Method Name	Description
widget.setStyle(styleName)	Sets style for current widget. Styles can be specified as: white, red, green, blue and yellow
widget.getStyle()	Returns name of the current style

Ajax Methods

Method Name	Description
UDW.proxy.getFeed(params)	Returns feed object or error object
UDW.proxy.getText(params)	Returns result as plain text
UDW.proxy.getXML(params)	Returns result as XML document
UDW.proxy.getJSON(params)	Returns result as JSON object

Widget Components

phpcow — Thu, 20 Nov 2008 02:30:05 -0500

Widget Components

There are two UI components that are used frequently for building widgets. These two components are Tab Menu and Pagination. Both of the components are used in all of the news and search widgets.

Tab Menu

Tab Menu is frequently used for splitting widget's content into separate tabs. Tab Menu component has few API methods that allows developers to easily manage as whole tab menu control as its separate tabs.

Example Tab Menu looks something like this:

First of all it is necessary to obtain tab menu object as shown in code below:

/**
 * Instantiate tab menu component
 */
var tabMenu = new UDW.Components.Tab();

For adding new tabs into the tab menu you need to use addTab method:

/**
 * @param String tabId unique identifier of the tab
 * @param Object javascript object specifying addition parameters
 */
tabMenu.addTab(
  'tabId',
  {
    label: 'First Tab',
    content: '<p>This is first tab</p>',
    active: true,
    callback: function(tabItem) {
        //rest of code here
    } 
  }
);

Shown method accepts two parameters tabId and parameters object. Structure of the parameters object is shown in the table below:

Parameter	Description	Required
label	Label for the tab item	Yes
content	Content for the tab item	No
active	Whether tab item is active(selected) or no. Defaults to false	No
callback	JavaScript function to be called after tab item is selected.	No

There is one more additional useful attribute that due to its complexity is not listed in the table and requires additional explanation.

Every tab item added to the tab menu can contain children items. Example of child items can be found in the news widgets. To add sub items(children) to the tab menu item you need to specify them as shown below:

tabMenu.addTab(
  'tabId',
  {
    label: 'First Tab',
    content: '<p>This is first tab</p>',
    active: true,
    callback: function(tabItem) {
        //rest of code here
    },
    subItems: {
        items: {
            'att':     UDW.str('Attention - Monthly'),
            'avgStay': UDW.str('Average Stay - Monthly'),
            'ppv':     UDW.str('Pages/Visit - Monthly')
        },
        callback: function(event, childItem) {
            //rest of code here
        }
    }
  }
);

As shown in the example sub items are passed as key/value pairs. Also additional callback parameter can be passed that is handled after sub item is clicked.

Other API methods that is supported by tab menu components are shown in table:

Method	Description
tabMenu.getActiveTab()	Returns currently selected tab menu item
tabMenu.getItemCount()	Returns count of tab menu items
tabMenu.removeActiveTab()	Removes currently selected tab menu item
tabMenu.getTabs()	Returns array of all tab menu items

TabItem object

Internally all tab menu items are of type TabItem object that has several useful API methods. These methods are extremely useful while working with tab items and give developers additional flexibility. These API methods are listed in table below:

Method	Description
tabItem.isActive()	Returns true or false depending on the current state of the tabItem object
tabItem.getLabel()	Returns label of the tabItem object
tabItem.setLabel(label)	Sets label to the tabItem object
tabItem.setContent(content)	Sets content to the current tab. Parameter can be specified as String or DOM element
tabItem.getContent()	Returns innerHTML of the tab
tabItem.getPage()	Returns DOM element of the tab's content area

Pagination Component

Pagination component is very useful UI component that potentially can be used for working with any type of content that requires splitting due to its large size. Implementation of component allows to easily navigate through content.

Example Pagination looks something like this:

Working with pagination component is bit complicated, but shown example and following explanations will clarify all details:

 
//obtain widget reference for later use
var widget = this;
 
/**
 * Instantiate Pagination component
 */
var pagination = UDW.Components.Pagination.getComponent(
    {
        currentPage: 1, //Specify current page to be selected
        rowsPerPage: 2, //Specify number of records to be shown on each page
        rowName: 'stories', //Specify collection name to be processed
        callback: function(rows) { //Specify callback function to be invoked for processing selected rows
            var htm = [];
            for (var i = 0; i < rows.length; i++) {
                htm.push('<p>' + rows[i].title + '</p>');
            }
            widget.setContent(htm.join(''));
        }
    }
);
 
/**
 * Add Pagination component to the widget's footer section
 */
widget.setToFooter(pagination);
 
/**
 * This is example result-set used for this example
 * collection contains objects collection named "stories"
 * which will be processed by pagination component
 */
var result = {
    stories: [
      {title: 'Story 1'},
      {title: 'Story 2'},
      {title: 'Story 3'},
      {title: 'Story 4'},
      {title: 'Story 5'},
      {title: 'Story 6'}
    ] 
};
 
/**
 * pass result-set to pagination component's process method
 */
pagination.process(result);

For testing this code just copy and paste it into the “this.onload” method of the HelloWorld widget and you will immediately see the result.

Working with Widget Preferences

phpcow — Wed, 19 Nov 2008 14:34:43 -0500

Working with Widget Preferences

Widget Preference Management is built-in capability of widgets. There are special API methods that allow developers to easily work with preferences.

There are two API methods for working with preferences. These methods are:

Method Name	Description
widget.setValue(name, value)	Set specified value to preference specified as name
widget.getValue(name)	Returns value for specified “name” preference

Besides shown two API methods there is one event associated with preferences:

Event	Description
widget.onPreferencesSave()	Handled when users hit preferences save button

Let's enhance previously created Google Search widget with preferences. For this open “googlesearch.js” widget file and add preference settings to it:

(function() {
 
    function GoogleSearch() {
 
        this.preferences = [
            {
                type: 'text',
                name: 'title',
                label: 'Title',
                value: ''
            }
        ];
 
        //rest of code here
 
    };
 
    UDW.registerWidget('googlesearch', GoogleSearch);
 
})();

Thats it preference with name “title” is created. If you reload the widget you will find that hovering it's title will show “Edit” link, clicking this link will show widget's preferences. See on the picture below:

Now it's time to do something with this preferences. First of all lets add “onPreferencesSave()” event handler method to the widget's code:

(function() {
 
    function GoogleSearch() {
 
        this.preferences = [
            {
                type: 'text',
                name: 'title',
                label: 'Title',
                value: ''
            }
        ];
 
        this.onPreferencesSave = function() {
            //try to retrieve title or use default
            var title = this.getValue('title') || 'Google Search';
            //set title to the widget
            this.setTitle(title);
        }
 
 
        //rest of code here
 
    };
 
    UDW.registerWidget('googlesearch', GoogleSearch);
 
})();

Shown “onPreferencesSave()” method will be handled when user hits “Save” button. Logic of the method is quite simple, it just tries to retrieve value of the “title” field and later assigns it to the widget's title.

Most of the time working with widget preferences is as simple as was shown in the current example.

PHPCow Documentation

Feed Management

Language Tools

Local Content

MySql Tools

System Logs

User Management

Widget Management

Advanced Widget Example

Creating Widget Icon

Developer Version

Generic Widgets

Hello World Widget

JavaScript API - CodeQ

Overriding Widget Styles

Storing Widget Data

Ajax API

Widget Anatomy

Widget API

Widget Components

Working with Widget Preferences

The Control Panel

MyWeb - PHPCow Personalized Start Page

Widget Development