Flexicious 101 - Getting Started with Flexicious

clock July 25, 2010 05:01 by author Flexicious

We have had a few requests to elaborate the process that someone completely new to Flex would follow to get started with Flexicious. (There have been customers who have wanted to switch to Flex, just because the functionality Flexicious offers!)

So first things first – Flexcious is an extension to the base Adobe Flex DataGrid and AdvancedDataGrid components. The corresponding class names are ExtendedDataGrid and ExtendedAdvancedDataGrid. For someone who is completely new to Flex, the first step would be to get familiar with the Adobe DataGrid. Tons of resources on the web can get you started with this. Our favourites are (In no particular order):

http://blog.flexexamples.com/
http://www.adobe.com/devnet/flex/
http://www.adobe.com/devnet/flex/learn/learningpath.html#type=role&role=programmer


Now, usually the starting point for you to use Flexicious is that you have a running project, and are faimilar with the <mx:DataGrid> and <mx:AdvancedDataGrid> syntax. May be your project has a few screens and some of them display data using the Adobe Grids. You want to replace the Adobe Grids with the Flexicious Extensions. Please note, since we are extensions to the Adobe grid, all of the base functionality that these controls offer will continue to work as is.

When you get the trial sample or purchase Flexicious, you get a zip file of the sample project. You can import this project, and run it, and see all of the Flexicious functionality in action. (In Flex 4, if you get an error saying unable to generate html wrapper, just right click and click on it it and click recreate html templates) This project contains sample MXML and Action Script files, and most importantly, the Flexicious swc file. There should be 2 swc files in samples/libs folder. One of them is the AlivePDF swc, and the other one is the Flexicious swc file. You can look around the files in the sample project, and get familiar with the functionality in it.


Now when you are ready to integrate Flexicious into your project, the first thing you want to do is to pick up the Flexicious swc file (from our sample project), and drop it into the libs folder of your Flex project. Next step is to start working with the individual screens where you want to change the Adobe Grids to the Flexicious extensions. Let’s assume you have a grid with the following markup:

<mx:DataGrid … >
<mx:columns>
<mx:DataGridColumn …/>
<mx:DataGridColumn …/>
</ mx:columns>
</mx:DataGrid >

All you need to do, is to replace <mx:DataGrid> with <grids:ExtendedDataGrid> and <mx:DataGridColumn> with <columns:ExtendedDataGridColumn>. Please note, as you start typing the words ExtendedDataGrid, hit control-space and the “grids” name space will be automatically imported for you. Once you have done this, compile the app, and you will have your first Flexicious enabled Grid. Now, the next step is to enable the Flexicious functionality. You may follow these steps one by one depending on which functionality you need.

   1. Filters: If you need filters, right after the <grids:ExtendedDataGrid, type in enableFilters=”true”. This creates the Filter row on top of the grid. You can then control individual filter attributes, by specifying them on each of the <columns:ExtendedDataGridColumn>. Review the list of available filter attributes and their documentation here:
    http://www.flexicious.com/resources/docs/com/flexicious/grids/columns/ExtendedDataGridColumn.html

   2. Footers: Exactly like the above, enableFooter on the grid, and footer specific attributes on the columns:
   http://www.flexicious.com/resources/docs/com/flexicious/grids/columns/ExtendedDataGridColumn.html

   3. Paging: To enable paging, you need to first set enablePaging=true. By default, you will get a simple pager bar. Our demo actually demonstrates the ability to plug-in your own pager, for which you can use pagerRenderer=”the fully qualified name of the pager”. Please see our sample code for details.
  
   4. Print: First set enablePrint=true. Second, simply drop a button on the canvas, and in the click handler of the button, call PrintController.instance().print(your_grid_id). Example:
              PrintController.instance().print(this.grid)

   5. Export: First set enableExport=true. Second, simply drop a button on the canvas, and in the click handler of the button, call ExportController.instance().export(your_grid_id). Example:
              ExportController.instance().export(this.grid)

   6. PDF Export: To enable PDF export, you will need to follow the following steps:
         1. Ensure the AlivePDF.swc exists in your libs folder
         2. Copy all the files in the com/sample/examples/support/print folder in the sample download into your project. Based on the folder in which you copy these in, you will have to change the namespaces in these files.
         3. Now, drop a button on the control where you want the pdf to launch from. In the click event handler for this button, call the PrintController, and pass in MyPrintOptions: PrintController.instance().print(this.grid,MyPrintOptions.create())
         4. Please note, what you are doing here is customizing the built in functionality of the PRINT to instead of printing to the printer, print to an in-memory pdf that AlivePDF helps you generate. So, you could use this exact same mechanism to customize your print appearance, by modifying the My*.mxml files in this folder.

   7.  Preference Persistence:
         1. Ensure the enablePreferencePersistence flag is set to true on the grid.
         2. Copy the following files from the com\sample\examples\support\gridSettings in the sample download to your project. Since these are just two mxml files, there is no need to change any namespaces.
         3. Now, drop two buttons on the canvas, one for Changing the preferences, and another for Saving them.
         4. In the button for Changing preferences, add code to open up the settings popup as shown below:
              <mx:Button label=”Preferences” click="var popup:SettingsPopup=new SettingsPopup();UIUtils.addPopUp(popup, your_grid_id as DisplayObject);popup.grid=your_grid_id;"/>
         5. In the button for Saving Preferences, add code to open up the save popup as shown below:
              <mx:Button label=”Save Preferences” click="var popup:SaveSettingsPopup=new SaveSettingsPopup();UIUtils.addPopUp(popup,_grid as DisplayObject);popup.grid=_grid;"/>
         6. If you receive compile errors indicating any of the above classes are missing place your cursor next to the name of the class and hit ctrl-space. This will automatically include the import statement required for the class.

 

Finally, there are a couple more blog posts, that are a must read:

http://blog.flexicious.com/post/Excel-Word-and-Html-Export-and-the-Echo-URL.aspx
http://blog.flexicious.com/post/Handy-Flexicious-methods.aspx

 

Please note, these are the steps you would follow to get started with the basics of Flexicious. As you start working with the API, there are lots of advanced scenarios that Flexicious is capable of handling, but they require a little additional configuration. We have a tremendous amount of material available that can help, please reach out to us!

 

 



The Anatomy of a Filter Control

clock July 5, 2010 01:52 by author Flexicious

We have had a few requests to explain in detail the process for creating a new Fitler Control.

First, a little background. Filter Controls are objects that show up in the Filter Row for the Flexicious Classic and Advanced DataGrid controls. There are seven built in Filter Controls as follows:

  • TextInput
  • TriStateCheckBox
  • ComboBox
  • MultiSelectComboBox
  • DateComboBox
  • NumericRangeBox
  • NumericTextInput

 

That said, Flexicious exposes, a robust mechanism in which you can create and plugin your own filter controls. We actually provide an example of this, in the SalaryRangeSlider.mxml. There are a few steps involved in creating a filter control.

Step1: Choose the appropriate IFilterControl Interface OR extend an existing FilterControl.
Filter Controls in most cases, need to implement a derivative of the IFilterControl interface (See the end of this article if none of the below interfaces apply to your scenario). This gives you the following options:

  • IDateComboBox
  • IDynamicFilterControl
  • IRangeFilterControl
  • ISelectedBitFilterControl
  • ISelectFilterControl
  • ITextFilterControl
  • ITriStateCheckBoxFilterControl

Now consider what you wish you filter control to behave like. Are you going to be executing Text based search? Then your best best is ITextFilterControl (Or extending TextInput). Are you performing Date Range Searches? Then you want the IRangeFilterControl. Do you need complete control over the FilterExpression that gets generated? Then you need the Dynamic Filter Control. Do you need even more control and have a requirement to build in custom logic in your filter control? Then you can use the ICustomMatchFilterControl (which is new to Flexicious 1.5). Our sample code includes examples for each of these. For the purpose of this entry, since we are discussing the SalaryRangeSlider, we need to search a range of Salaries for our list of employees, so we pick the IRangeSlider to implement, and extend the HSlider component that is available with the Flex SDK. This is accomplished using the following line of code at the opening of the markup:

<mx:HSlider .... implements="com.flexicious.controls.interfaces.filters.IRangeFilterControl"  .... />

Step 2:
Now, there are a bunch of properties and methods that the IFilterControl comes along with. Most of these, are already implemented for you, all you have to is to include the FilterInclude.as file that is provided to you in the sample download. This is accomplished using the following line of code (Your path may be different on basis of where you have placed the FilterInclude.as file):

 <mx:Script source="../../includes/FilterInclude.as" />

Step 3:

Dispatch the appropriate event: The Flexicious DataGrid is setup so that the filter control should dispatch an event (which is configurable) that the datagrid listens for, and when this event is dispatched, a filter is run. By default, this event is the "change" event. For controls that implement IDelayedChange, it is the delayed change event. So, this is something you need to keep in mind while implementing your own filter control. The change event being dispatched by default will trigger the filter. You can control this via setting the filterTriggerEvent on the column, if you want a specific event to trigger the filter. In our scenario, we dont need to worry about this, because we are extending a slider. This control already dispatches a change event when the user changes the value of the slider thumb.

Step 4:

Implement the Filter Interface methods: There are a few methods that we need to implement based on which filter interface we are implementing: In this scenario, since we are implementing IRangeFilterControl, we need to provide searchRangeStart and searchRangeEnd. This is then used by the filter logic to build a BETWEEN expression. If either searchRangeEnd or searchRangeStart is empty, the entire filter expression for this control is ignored. The other important methods are: setValue, getValue and clear. These methods are called by our API, when we rebuild the filter row in response to a refresh of the layout. So we call getValue, store it temporarily, destroy the filter component, create a new one, and then call setValue with the previously persisted filter Value. It is the responsibility of the filter control, to restore its state, from information it we give it in setFilterValue (which it gave us in getFilterValue). For sample implementation, look at the Salary Range Slider,

public function getValue():Object
public function setValue(val:Object):void
public function clear ():void

Step 5:

Using the Filter Control : Once we have a filter control implemented, its just a matter of setting its name (along with the package) in the filterRenderer property of the ExtendedDataGridColumn or ExtendedAdvancedDataGridColumn.
<columns:ExtendedDataGridColumn  .... filterRenderer="com.sample.examples.support.SalaryRangeSlider"..../>

All of that said, there may be scenarios where you need to massage the value of the filter before processing it, or you may need to apply your own filtering logic to the filter control. There are ways to do this:

1) Implement IConverterControl: This interface is used, when you need to process the value of the item being compared. For example. A database sends down date columns as Strings. You have a DateComboBox as a filter. By default, the filter mechanism will try to compare two dates against a string. To combat this situation, you implement IConverterControl, and in the convert method, convert the string to a Date. We do this in the sample, look at MyDateComboBox.as (The code is commented, but its there).

2) Implement ICustomMatchFilterControl : This is new to Flexicious 1.5, but basically lets you completely encapsulate the logic for performing a filter. Please note, only use a FilterControl that implements this interface in filterPageSortMode=client.

 One more caveat:

Flexicious 1.5 will have focus and tab enabled filter controls. This means that if your filter class does not implement IFocusManagerComponent, you will need to do it manually, otherwise we'll just tab over you. If it is a container control that encapsulates a IFocusManagerComponent control, then you will need to set focus contained control when you receieve focus. See DynamicFilterControl.mxml, where we implement the following methods:
public override function setActualSize(w:Number, h:Number)
public override function setFocus()
public override function drawFocus(isFocused:Boolean)

 As always, unique requirements often demand unique resolutions, so please feel free to reach out with your questions, we're happy to help!



Whats coming....

clock July 5, 2010 00:39 by author Flexicious

We just had a feature packed release for Flexicious 1.4, and we're already looking at what's coming for Flexicious 1.5... for those of you who cant wait, we'll have a beta at the end of this month (may be even sooner), but here is a partial list of what's coming. BTW, these are things that you, our customers and prospects have asked for. We're listening, so please feel free to make suggestions!

Enhancement: Added enablePrint and enableExport properties which can be used in binding the CustomPagerControl.
Enhancement: Added enableLocalFilePersistence property to ExportOptions, to leverage local file persistence of Flash Player 10
Enhancement: Added code to MyPreviewRenderer.mxml to demonstrate how to persist PDF locally
Enhancement: Added tab and arrow key support to Filter rows
Enhancement: Added a method, setFilterFocus to set focus on any filter field
Enhancement: Added a method, setFocusOnNextFocusableFilterControl to set focus on the first focusable filter field in the filter list
Enhancement: Added styling support for filters: New style properties filterBorderColor,footerBorderColor,filterBorderThickness,footerBorderThickness,filterBorderSides,footerBorderSides Added.    Enhancement: Added a new Filter Control: NumericTextInput to restrict input to numeric characters
Enhancement: Added the "Does Not Contain" filter criteria
Existing clients will need to get the following files when you get the latest swc (either from the updated sample that we send you or via view->source on the demo):

  DynamicFilterControl.mxml (Focus support, needed only if you are using dynamic filters)

->Fix: Address export issues for hierarchical XML data
->Fix: Addressed the sortCompareFunction issue
->Fix: FilterPageSortChange did not have the cause on sort
->Fix: Addressed the bug where selecting Custom on the date combobox caused duplicate filter events