yourminis Developers > AS2 Learning Center > Advanced Tutorial
Welcome to the Advance Tutorial. In this lesson you'll learn about every feature the yourminis API has to offer. You can download the source code for this example here.
Requirements
Steps 1. Create a New Document
The first step in this tutorial is to open Adobe Flash 8. Once the Flash IDE is open, create a new "Flash Document".
2. Initialize an Instance of The API Object
The constructor for the yourminis API class takes the following five optional parameters:
In this example, and this holds true in just about all cases, we'll leave the first two parameters alone and play with the last three. Enter the following line of code in the Actions panel:
This line will create a widget that has a width of 300 pixels, a height of 250 pixels, and a red default color. If you press the "Test this mini!" your widget should look like the image on the left. Width, height, and background color are all managed by the yourminis API so you don't have to manage them yourself. When a user changes the width, height, and color of your widget the new values are automatically stored and used again the next time the user views that widget.
3. Logging
Probably the most helpful API function is the ability to log messages to the debug console. To log a message to the debug console type something like this:
4. Resize Events
The yourminis API allows you to specify a function to get called when the widget is resized. This is useful for handling the layout of your content once the widget is resized. There are two ways to set the onResize function. You can either set the function directly like this:
Add a new TextField to the stage at x = 0 and enter the text, "Hello, World!". Set the text to be centered and change the instanceName to "myText". In our resize function, well center the text in the mini. Well also test out the logging functionality.
5. Creating The Drop Down Menu An essential part of every yourminis widget is the drop down menu. The drop down menu is rebuilt every time you click on the drop down button. This allows for a lot of flexibility when it comes to displaying pertinent information in the drop down menu. When the drop down button is pressed, the onDropDownLoaded event is fired. It's in this function that you should put the code to build your drop down menu.
In order to create a drop down menu item you will need to call the addDropDownItem function which takes the following parameters:
In this example we'll create a drop down menu to change the size of the widget which also incorporates another yourminis API function, setSize which takes the following parameters:
The first block of code sets up the delegate for the onDropDownLoaded event in the exact same way we did it for the onResize event. The second block of code is where the actual menu is generated. The last block is the callback for the menu items which handles the resizing of the widget using the data object from the menu item. If you press the "Test this mini!", and then click on the drop down button, your widget should look like the image on the left. Selecting one of the menu items should resize the widget to the appropriate size.
6. Locking
Widgets on the yourminis platform can be locked. Locking widgets is useful when you want to preserve the layout of a public page and prevent people from changing any of the settings. In this example, you'll remove the ability to change the widget size from the dropdown menu when the widget is locked.
The first thing that we did was create a variable to store the current lock state of the widget. Then we set up the delegate for the onToggleMiniLock event. This function updates the variable that stores the value for the lock state. Lastly we modified the function for our dropdown menu to only add the menu items if the widget is unlocked.
7. Minimal View The minimal view for a widget removes all of the chrome. In this example we'll add a yourminis logo to the widget and have it only display when the widget is not in the minimal view.
Add this logo to the stage at around x = 4 and y = 1. Convert it to a MovieClip and set the instanceName to "logo". Next add the following code:
8. Color Changes When a user changes the color of the widget using the color picker, an onChooseColor event is fired. In this example we'll change the color of the "Hello, World!" text to lighter tint of the color that was chosen. The code for the getTintedColor is included with the source code of the example.
9. Disable Resizing
Although this is not included in this example, it is possible to disable the ability for a user to resize your widget using the following code:
10. Web Proxies Also not included in this example is the use of the proxy functions since they're not really needed until the widget is uploaded to the yourminis website.
Because of Flash security restrictions, data not located on the same domain as the swf file must be proxyed to be accessed. For this reason we've created two methods to handle the proxying for you.
The first function, getWebProxyUrl, takes the url of the site you want to load and converts it to a url that uses our proxy service. The second function, getRssProxyUrl, does essentially the same thing; however, we will cache these feeds for a short period of time to improve speed and efficiency.
The following is an example of how to use the getRssProxyUrl method:
11. Getting and Setting Data Getting and setting data is very simple to do and only requires one step for each action. To save data use the setSetting function.
The getSetting function takes the two following parameters:
To retrieve data from the server use the getSetting function. The getSetting takes the two following parameters:
Conclusion That concludes the Advanced Tutorial. We've covered all of the features of the yourminis API. At this point you should be able to create just about any widget you can imagine. If you have any questions or comments, use the Discussion feature of this group.
Requirements
- Adobe Flash 8
- yourminis API mxp (If you don't have this installed yet, follow the steps found here)
Steps 1. Create a New Document
The first step in this tutorial is to open Adobe Flash 8. Once the Flash IDE is open, create a new "Flash Document".
2. Initialize an Instance of The API Object
The constructor for the yourminis API class takes the following five optional parameters:
- Listener - A reference to the MovieClip to which you wish class events to be broadcast. Defaults to the _root of your swf.
- apiListener - A reference to the MovieClip that contains your mini. Defaults to the _parent of your swf.
- initWidth - The default width of the mini. Defaults to 240 pixels
- initHeight - The default height of the mini. Defaults to 200 pixels
- initColor - The default theme color of the mini. Defaults to black (0x000000)
In this example, and this holds true in just about all cases, we'll leave the first two parameters alone and play with the last three. Enter the following line of code in the Actions panel:
var ym_api:yourminisAPI = new yourminisAPI( this, _parent, 300, 250, 0x780900 );
This line will create a widget that has a width of 300 pixels, a height of 250 pixels, and a red default color. If you press the "Test this mini!" your widget should look like the image on the left. Width, height, and background color are all managed by the yourminis API so you don't have to manage them yourself. When a user changes the width, height, and color of your widget the new values are automatically stored and used again the next time the user views that widget.3. Logging
Probably the most helpful API function is the ability to log messages to the debug console. To log a message to the debug console type something like this:
ym_api.log( "prefix", "value");
4. Resize Events
The yourminis API allows you to specify a function to get called when the widget is resized. This is useful for handling the layout of your content once the widget is resized. There are two ways to set the onResize function. You can either set the function directly like this:
ym_api.onResize = function( w:Number, h:Number) { ... };
or you can set use a function delegate like this:
ym_api.onResize = mx.utils.Delegate.create(this,doResize );
We suggest you use the second method because it allows you to name your function whatever you want and also it helps avoid many scoping issues.Add a new TextField to the stage at x = 0 and enter the text, "Hello, World!". Set the text to be centered and change the instanceName to "myText". In our resize function, well center the text in the mini. Well also test out the logging functionality.
function doResize( w:Number, h:Number ):Void {
ym_api.log( "doResize", "w: " + w + " h: " + h );
myText._width = w;
myText._y = ( h+25 - myText._height)/2;
}
The first thing that happens in this function is that the new width and height are outputted to the debug console. Next we set the width of the TextField to the width of the widget. This takes care of horizontal alignment. Then we set the y value to take care of the vertical alignment. The reason we added 25 to the height was to account for the widget header which, coincidently, is 25 pixels tall.ym_api.log( "doResize", "w: " + w + " h: " + h );
myText._width = w;
myText._y = ( h+25 - myText._height)/2;
}
5. Creating The Drop Down Menu An essential part of every yourminis widget is the drop down menu. The drop down menu is rebuilt every time you click on the drop down button. This allows for a lot of flexibility when it comes to displaying pertinent information in the drop down menu. When the drop down button is pressed, the onDropDownLoaded event is fired. It's in this function that you should put the code to build your drop down menu.
In order to create a drop down menu item you will need to call the addDropDownItem function which takes the following parameters:
- Label - The text to be displayed in the dropdown item.
- Data (optional) - an object to be passed to the callback function.
- Callback (optional) - a function that gets called when the dropdown item is selected. The function will be passed the data stored in the item's data object as a parameter.
- SecondaryIndex (optional) - the menu item to which this item is added as a second level menu (first index of menu is 0).
In this example we'll create a drop down menu to change the size of the widget which also incorporates another yourminis API function, setSize which takes the following parameters:
- Width - the new width of the widget
- Height -he new height of the widget
ym_api.onDropDownLoaded = mx.utils.Delegate.create( this, doDropDownLoaded );
function doDropDownLoaded():Void {
ym_api.log( "doDropDownLoaded", "" );
ym_api.addDropDownItem( "Resize" );
ym_api.addDropDownItem( "230x80", {w:230,h:80}, changeSize, 0 );
ym_api.addDropDownItem( "400x250", {w:400,h:250}, changeSize, 0 );
}
ym_api.log( "doDropDownLoaded", "" );
ym_api.addDropDownItem( "Resize" );
ym_api.addDropDownItem( "230x80", {w:230,h:80}, changeSize, 0 );
ym_api.addDropDownItem( "400x250", {w:400,h:250}, changeSize, 0 );
}
function changeSize( theData:Object ):Void {
ym_api.setSize( theData.w, theData.h );
}
ym_api.setSize( theData.w, theData.h );
}
The first block of code sets up the delegate for the onDropDownLoaded event in the exact same way we did it for the onResize event. The second block of code is where the actual menu is generated. The last block is the callback for the menu items which handles the resizing of the widget using the data object from the menu item. If you press the "Test this mini!", and then click on the drop down button, your widget should look like the image on the left. Selecting one of the menu items should resize the widget to the appropriate size.6. Locking
Widgets on the yourminis platform can be locked. Locking widgets is useful when you want to preserve the layout of a public page and prevent people from changing any of the settings. In this example, you'll remove the ability to change the widget size from the dropdown menu when the widget is locked.
var isWidgetLocked:Boolean = false;
ym_api.onToggleMiniLock = mx.utils.Delegate.create( this, doMiniLock );
function doMiniLock( isUnlocked:Boolean ):Void {
ym_api.log( "doMiniLock", "isUnlocked: " + isUnlocked );
isWidgetLocked = !isUnlocked;
}
ym_api.log( "doMiniLock", "isUnlocked: " + isUnlocked );
isWidgetLocked = !isUnlocked;
}
function doDropDownLoaded():Void {
if(!isWidgetLocked) {
ym_api.log( "doDropDownLoaded", "" );
ym_api.addDropDownItem( "Resize" );
ym_api.addDropDownItem( "230x80", {w:230,h:80}, changeSize, 0 );
ym_api.addDropDownItem( "400x250", {w:400,h:250}, changeSize, 0 );
}
}
7. Minimal View The minimal view for a widget removes all of the chrome. In this example we'll add a yourminis logo to the widget and have it only display when the widget is not in the minimal view.
Add this logo to the stage at around x = 4 and y = 1. Convert it to a MovieClip and set the instanceName to "logo". Next add the following code:
ym_api.onViewChange = mx.utils.Delegate.create( this, doViewChange );
function doViewChange( isFullView:Boolean ):Void {
ym_api.log( "doViewChange", "isFullView: " + isFullView );
logo._visible = isFullView;
}
As usual, we set up the delegate for the onViewChange event. This event passes a boolean flag for the full view. The flag is true when the widget is in full view and false when the widget is in minimal view. In our function we set the _visibility for the logo MovieClip to the value of that flag so that it's hidden when the widget is in minimal view. If you press the "Test this mini!", click on the color picker button, and then click the minimal view checkbox, the logo should disappear. If you uncheck the minimal view checkbox, the logo should reappear.ym_api.log( "doViewChange", "isFullView: " + isFullView );
logo._visible = isFullView;
}
8. Color Changes When a user changes the color of the widget using the color picker, an onChooseColor event is fired. In this example we'll change the color of the "Hello, World!" text to lighter tint of the color that was chosen. The code for the getTintedColor is included with the source code of the example.
ym_api.onChooseColor = mx.utils.Delegate.create( this, doChangeColor );
function doChangeColor( color:Number ):Void {
ym_api.log( "doChangeColor", "color: " + color );
myText.textColor = getTintedColor( color, 150 );
}
ym_api.log( "doChangeColor", "color: " + color );
myText.textColor = getTintedColor( color, 150 );
}
9. Disable Resizing
Although this is not included in this example, it is possible to disable the ability for a user to resize your widget using the following code:
ym_api.disableStrech();
Once that function is called, the user will no longer be able to resize the widget.10. Web Proxies Also not included in this example is the use of the proxy functions since they're not really needed until the widget is uploaded to the yourminis website.
Because of Flash security restrictions, data not located on the same domain as the swf file must be proxyed to be accessed. For this reason we've created two methods to handle the proxying for you.
The first function, getWebProxyUrl, takes the url of the site you want to load and converts it to a url that uses our proxy service. The second function, getRssProxyUrl, does essentially the same thing; however, we will cache these feeds for a short period of time to improve speed and efficiency.
The following is an example of how to use the getRssProxyUrl method:
var url:String = "http://digg.com/rss/index.xml"
var proxyUrl = ym_api.getRssProxyUrl( url );
var xml:LoadVars = new LoadVars();
xml.onData = function( data:String ) {
ym_api.log( "data", data );
}
xml.load( proxyUrl );
11. Getting and Setting Data Getting and setting data is very simple to do and only requires one step for each action. To save data use the setSetting function.
The getSetting function takes the two following parameters:
- settingName - The name of the setting to be stored on the server.
- Value - Value to be stored on the server and associated with the settingName for this individual instance of the mini.
To retrieve data from the server use the getSetting function. The getSetting takes the two following parameters:
- settingName - The name of the setting stored on the server.
- defaultValue - If the setting is not stored on the server already, the value of this object will be returned.
var myValue:String = ym_api.getSetting( "myName", "John" );
ym_api.log( "myName", myValue ); // displays "John" (assuming the value has not yet been set previously)
ym_api.setSetting( "myNumber" , 123 );
var myNumber:Number = Number( ym_api.getSetting( "myNumber", "1" ) );
ym_api.log( "myNumber", myNumber ); //displays 123... note value is cast from a String to a Number
Conclusion That concludes the Advanced Tutorial. We've covered all of the features of the yourminis API. At this point you should be able to create just about any widget you can imagine. If you have any questions or comments, use the Discussion feature of this group.
Next Steps
Learn how to build an RSS widget in 16 lines of code with the RSS Widget Example.