The date format used in the dates returned can be changed dynamically through the plug-in parameters, as it will be shown later.

By definition, all FileMaker plug-ins, return their results as text. Filemaker text fields, has a size limit of 64K. To avoid overflows or nasty overflow messages to your users, SuperPopCal has a memory management function which dynamically calculates the range of years that could be returned safely to Filemaker, and adjusts the end calendar (right side calendar) to display only those years.

Even more, if you provide a prefix or a suffix to append to the returned range, the memory management function will prevent memory overflows by calculating the size of the result with the prefix and/or suffix included, providing a safe way to give your users a calendar without the risk of overflow or without the need to display an overflow message which will make the user to select a new, but still uncertain, smaller range without the knowledge if this new range will fit into the 64K field limit.

All DataFilter multi-key generation functions allow to concatenate to each of the dates in the series a prefix and a suffix to create more complex keys.

This kind of complex keys, allow further filtering of your data within the already filtered range of dates.

The GetDateRange function takes several parameters after the function name. These parameters are represented in the examples above by the variable "parameter". The configuration of these parameters will be viewed later in the section "DataFilter Studio".

If the users selects in the left calendar 1/1/2002 and in the right calendar 1/7/2002, the returned result will be:

It is important to point that the date format of the dates in the series can be changed dynamically with the plug-in parameters, giving the oportunity to return the dates as mm/dd/yyyy, dd/mm/yyyy or yyyy/mm/dd with any date separator to create dates like:

If a prefix and/or a suffix are added, the returned result would be:

GetDateNumRange Function

This function displays a dual calendar for date range selection. The calendar provides an easy and appealing way to pick the start and end dates and returns a serie of consecutive dates between the two dates selected.

The dates returned by this function are converted to the Filemaker internal number equivalent. Filemaker stores dates as sequential numbers, being January 1 st. 0001 the number 1 and December 31st. 3000 the number 1,095,727.

By definition, all FileMaker plug-ins return their results as text. Filemaker text fields, has a size limit of 64K. To avoid overflows or nasty overflow messages to your users, SuperPopCal has a memory management function which dynamically calculates the range of years that would be safely returned to Filemaker, and adjusts the end date calendar to display only those years.

The reason to use date number equivalents instead of regular dates, is that the number equivalents are smaller and more dates will fit into the 64K limit. The memory management function will calculate the size of the result for the date numbers.

Even more, if you provide a prefix or a suffix to append to the returned range, the memory management function will prevent memory overflows by calculating the size of the result with the prefix and/or suffix included, providing a safe way to give your users a calendar without the risk of overflow or without the need to display an overflow message which will make the user to select a new, but still uncertain, smaller range without the knowledge if this new range will fit into the 64K field limit.

All DataFilter multi-key generation functions allow to concatenate to each date in the series a prefix and a suffix to create more complex keys.

This kind of complex keys, allow further filtering of your data within the already filtered range of dates.

The GetDateNumRange function takes several parameters after the function name. These parameters are represented in the examples above and below by the variable "parameter". The configuration of these parameters will be viewed later in the section "DataFilter Studio".

If the user selects on the left side 12 -April-2001 and on the right side 17-April-2001, ther result would be:

With a prefix and a suffix:

GetSmartRange Function

This function displays a dual calendar for date range selection. The calendar provides an easy and appealing way to pick the start and end dates and returns a series of dates, which according to the SMART ranges technique, will cover the dates between the two dates selected.

The SMART ranges technique, besides creating a specific range of dates according with its statements, it also uses the number equivalents for the dates in FM. As we said above, Filemaker stores dates as sequential numbers, being January 1 st. 0001 the number 1 and December 31st. 3000 the number 1,095,727.

The SMART ranges technique is a brilliant invention created by Mikhail Endoshin. Further analysis and examples can be encountered on his site: www.onegasoft.com.

Briefly, the SMART ranges technique selects larger ranges of dates, using smaller series of dates, which allows the use of almost any date range, without the risk of overflowing the 64K limit of the Filemaker text fields.

As result, the calendars displayed by DataFilter have an open (1925-2050) range of years without any restriction. In the same way, the calendars allow the setting of different display dates for each calendar, as the Memory Management function is not used in the calendars.

In the same way as before, if you provide a prefix and/or a suffix to append to the returned range, they both will be concatenated to the begining and to the end of each date returned by function respectively.

The GetSmartRange function takes several parameters after the function name. These parameters are represented in the example above with the variable "parameter". The configuration of these parameters will be viewed later in the section "DataFilter Studio".

If the user selects 2 -April-2001 on the left side and 17-April-2001, on the right side their result would be:

As you can notice, only seven numbers are used to create a compound key which will select on a related field (with some modifications) 16 days being a significant number saving. The SMART ranges theory will be explained further below.

With a prefix and a suffix:

GetSmartNumRange Function

This function generates the range between a start and end numbers up to 9 digits according to the smart ranges technique.

The SMART ranges technique is a brilliant invention created by Mikhail Endoshin. Further analysis and examples can be encountered on his site: www.onegasoft.com.

This function is very useful to create multi-keys to select ranges of numbers (like amounts in invoices, order numbers, etc.) because its capability to deal with numbers with up to 9 digits.

Also, as Filemaker stores dates as sequential numbers, being January 1 st. 0001 number 1 (one digit) and December 31st. 3000 number 1,095,727, (seven digits), any range of dates can be created as well.

The SMART ranges technique selects a large range of numbers, using a smaller series of numbers, which allows the use of any number range, up to nine digits, without the risk of overflow the 64K limit of the Filemaker text fields.

In the same way as in previous functions, if you provide a prefix and/or a suffix to append to the returned range, they both will be concatenated to the begining and to the end of each number returned by the function respectively.

The GetSmartNumRange function takes several parameters after the function name. These parameters are represented in the example above by the variable "parameter". The configuration of these parameters will be viewed later in the section "DataFilter Studio".

Although most of the DataFilter functions are used with the FileMaker function "SetField", the GetSmartNumRange function can also be used in a calculation field, allowing a continuos calculation of the multi-key range for any start and end numbers given.

This is possible because the GetSmartNumRange function does not generate a Graphical Interface (GUI).

If you pass StartNum=730577 and EndNum=730592, you will get :

This numbers happen to be the dates 2-April-2001 and 17-April-2001 converted to numbers.

In the same way, StartNum=1000 and EndNum=10000 can be passed to generate a range that will filter (for example) invoices with amounts included in such range.

With a prefix and a suffix:

DateSelection Function

This function displays a calendar for date selection. The calendar provides an easy and appealing way to pick or find a date and returns the date selected by the user to be processed by your code.

The date format used in the date returned can be changed dynamically through the plug-in parameters, as it will be shown later.

RangeSelection Function

This function displays side to side calendars to select date ranges, avoiding errors produced by wrong date typing and helping the user to have a visual feedback of the dates selected and the scope of the range required.

The function returns the dates selected formatted as a “find range” as used by FileMaker to perform range searches: 1/1/2001…12/12/2001.

The date format of the returned dates can be changed dynamically through the parameters passed to DataFilter. See the configuration file “DataFilter_Studio.fp5” to have an example on how to use it.

Version Function

This function returns the version number of the plug-in. A must function in every Filemaker plug-in, which provides a simply method to check plug availability for validation purposes. It provides a safe way to avoid any problem in your application if someone removes the plug-in from the proper folder.

GetNumRange Function

This function generates traditional Ranges between a start and end numbers without the calendar interface.

The range of numbers created by this function are mainly oriented to be used with date ranges, although this function can be used for any range of numbers. When dealing with amounts or large numbers in general we recommend using the GetSmartNumRange function because its capability to deal with numbers up to 9 digits and the SmartRanges capability to avoid the 64K limit of the text fields.

As we said above, Filemaker stores dates as sequential numbers, being January 1 st. 0001 number 1 and December 31st. 3000 number 1,095,727, therefore any range of dates can be created with this function.

Whatsoever, this function is limited by the 64K size of the FileMaker text fields.

The overflow message is: “Type a smaller range” which can easily be trapped within FileMaker to display to your users the message you like. You only need to include the following Scripts in FileMaker.

If (External("Dafr-GetSmartNumRange", "|StartNum=" & StartNumVariable & "|EndNum="& EndNumVariable) = “Type a smaller range”, ShowMessage...

In the same way as previous functions, if you provide a prefix and/or a suffix to append to the returned range, they both will be concatenated to the begining and to the end of each number returned by the function respectively. Although most of the DataFilter 1.1 functions are used with the FileMaker function “SetField”, GetNumRange function can also be used in a calculation field, allowing a continuos calculation of the multi-key range for any start and end numbers given.

This is possible because the GetNumRange function does not use the Graphical Interface (GUI).

NOTE: Do not use any GUI function in a calculation field.

Examples:

Using the function from a script in FileMaker:

SetField[MyField, External(“Dafr-GetNumRange”, parameter)]
(After the user triggers this script in the way you choose, the result is put into the variable MyField.)

Using the function in a calculation field:

If(IsEmpty(StartNumExample) or IsEmpty(EndNumExample), "",
External("Dafr-GetNumRange", "|StartNum=" & StartNumVariable & "|EndNum=" & EndNumVariable))

In a calculation field, the result is re-calculated immediately when there is any change in the parameters.

If you pass StartNum=730577 and EndNum=730582, you will get :

As you can see the numbers returned are only a sequential range of numbers between the start and end numbers.

The numbers above are the FileMaker number equivalents for the dates from 2-April- 2001 to 7-April-2001.

In the same way, if StartNum=1000 and EndNum=10000 are passed to the function it will create a sequential range of numbers from 1000 to 10000. As before, a prefix and/or a suffix can be added to this function creating ranges like this below:

SmartKey

The SmartKey function will give you the capability to implement SMART Ranges in a couple of minutes instead of hours if you programm them directly within FileMaker.

Even more, with the SmartKey function, you won’t need to get into the complexities of SMART Ranges, you won’t even need to understand how they really work.

According to the SMART Ranges technique, to achieve what we called a “compression of dates” if you need to select numbers from 1357(00) to 1357(99) only the number 1357 will be created to select the whole one hundred numbers, but on the right side of the relationship, to have a relationship match, you need to create a list, separated by returns, for each of the categories that you number belongs to.

For example, if you have a number: 135763 To find such number with SMART Ranges, you need to have the numbers for each of the categories it belongs (tens, hundreds, thousands, etc.).

Therefore you need to have such number in this form:

This means that if a SMART Range is created to select numbers from 1357(00) to 1357(99), as we explained above, only the number 1357 will be created by the SMART Ranges function but on the right side, the SmartKey function will provide all the categories from which this number can make a match.

Example:

External("Dafr-SmartKey", "|StartNum="& Date &"|Suffix=" & Status & "|Prefix=" & Company)

The SmartKey function also simplifies the addition of a Prefix and a Suffix.

Another important feature of the SmartKey function is the capability to automatically create the number of positions of the number passed in the StartNum parameter.

This means if you have and three digit number in StartNum, you will get three digit number function, but if you pass a four digit number you will get four digit numbers.

For example: 0546 Will return:

But if you pass a number like 134567 You will get

This mean that numbers won’t be forced to have seven digits or more, which is vital for the SMART Ranges technique.

VERY IMPORTANT: The SMART Ranges technique works with positions, so you need to have the same number of digits on both sides of the relationship.

Therefore if you are dealing with, let’s say, 7 digits for dates and your right side number is only three digits, you need to stuff some zeroes to make the relationship work.

Fourtunately, the SmartKey function has another parameter SmartSize, which will allow you to set the number of positions that will be used by the SmartKey function.

Example: External("Dafr-SmartKey", "|StartNum=7865|SmartSize=6|Prefix=Yes_”)

Will return:

This parameter is esencial to have smart ranges working because it puts all the records on the same size and if the same SmartSize function is also used with the same parameter on the left side of the relationship in the function GetSmartNumRange, then the matching is guaranteed.

DataFilter Options

DataFilter has a huge range of options which can be easily configured through:

- DataFilter Wizard.
- DataFilter Studio.
- DataFilter Preferences.

Although DataFilter has many options, they are very easy to configure. Either dynamically with FileMaker scripts or statically through the plug-in preferences.

DataFilter options and capabilities are provided to give developers a wider range of options to fulfill the needs of their applications.

Interface - Single & Dual calendars.

DataFilter displays single calendar for date selection and dual calendars for range selection.

Size

DataFilter 1.0 can display the single calendar and the dual calendars in three different sizes: Small, Medium and Large.

Position.

Calendars can be displayed anywhere on the screen.

Kind

DataFilter 1.0 has two different interfaces to navigate in the calendars. Menus or buttons.

Behavior

Calendars can be closed automatically or with confirmation buttons.

First day of the week

Calendars in DataFilter can be displayed showing the monthly calendar with the weeks starting on Sunday or Monday.

Error display

When the user fails to pick a date, you can get an error display or get an error result back so it can be trapped and your own custom message can be created within Filemaker.

Message displayed by DataFilter.

Error returned by DataFilter.

Languages

DataFilter 1.0 can show calendars with months in seven different languages:

Date Format

DataFilter can return picked date in three different formats with any date separator (slash, dot, underscore, hypen, etc.).

Formats and date separators can be changed dynamically in your code, allowing you to use DataFilter in worldwide applications.

Start & End Dates

DataFilter 1.0 allow you to set a date to display the calendars, even more, for the RangeSelection function, you can set a start date and an end date one to display each of the calendars.

Date Separator

You can set any date separator (/ - _ . + : ).

Title

DataFilter allow you to set the calendar window title.