Expression Language
Using this page
The 'Contents' box above contains a list of available functions roughly grouped by usage scenario, and each function name gives a fair indication of what it might do. Each of the group headers contain some basic information pertinent to the functions inside the group. Click on a function or function group header in the Contents box to be taken directly to more information about it on the page. At the bottom right of each section there is a "Back to top" link which will take you back up to the Contents box allowing you to quickly get to where on the page you would like to go next.
Some of the function descriptions reference other functions to help illustrate their usage. Where this happens, a link to the referenced function is provided if needed. The browser's "Back" button will then return you to the previous place you were at on the page.
The page contains some references that link to external pages. Such links can be identified by the little square icon that follows them, like this--->. These links will not load in new tabs or windows, so, if you would like to keep this page open in your browser, right click on these links and choose to open them in a new tab or window.
Overview
The J. River Media Core database engine supports Excel-style functions for use in view schemes, searches, displayed columns, and tag editing.
An expression is a mixture of text, fields, and functions. A function allows special operations to be performed. Functions are all listed with a name followed by an opening and closing parenthesis. When building expressions, the instructions you wish to pass to the function are placed inside these parenthesis, with multiple instructions separated by commas. When your expression is evaluated, any spaces entered after a comma are ignored. This allows you to compose complex expressions on multiple lines, making it easier to keep track of where you are in your expression. Occasionally, you will find that you want a space, or parenthesis character to be treated literally as part of your instructions, rather than expression syntax, and in these cases, the character is "escaped" by using a preceding forward slash. Examples using this escaping can be seen here and here. As you progress with your expression building, you will begin nesting multiple functions into a single expression; always remember that a completed expression must contain a matching number of opening and closing parenthesis in order to work reliably.
The functions available to us range from highly functional, with a broad range of applicable uses, through specialised, limited use functions that only appeal to a select group of users, to seemingly redundant functions and obscure functions that MEDIA CENTER uses internally. The functions below are listed with those with the broadest appeal at the top, and the more obscure at the bottom.
Any given expression can only work on any given single file. It is not possible to compare a field in one file with a field in another file.
Batch file operations are possible, and when used in a list, even a grouped list, an expression will be applied to each individual file in turn, not as a group.
A slightly extended overview is also available elsewhere in this wiki, titled Database Expressions, and another page attempts to demonstrate MEDIA CENTER mimicking the "AND", "OR" and "XOR" database searches.
When, Where and How to use expressions
The use of expressions in MEDIA CENTER can be broken into three distinct categories:
- Tag or filename editing. (Data is physically altered by the expression)
- Filtering a list of files using a search rule. (No data is altered)
- Change how existing data is displayed. (No data is altered)
The implementation of the expression differs between each of these three categories, differences which are outlined below.
Tag or filename editing
Expressions can be used to simplify the batch editing of file tags, or if required, physical filenames too. It is important to remember that when using expressions in this way, file tags are physically altered, and if the expression is applied to a "filename" field, then the physical name or path of the file will be changed on the hard drive.
Expression functions that are typically used for these kind of tasks are grouped together in the list of functions. The grouping is provided as a rough guide only, as any function that gets the job done can be used.
When using expressions for this kind of task, the expression is either entered into the tag window, or by using inline editing in the file list, and a preceding "=" sign must be inserted to instruct the tagging engine to invoke the expression evaluator, rather than apply the expression as physical tag data. The following screen pictures will help to illustrate using expressions in this way:
 Pressing "Enter" copies the Date data into the caption field |
 Just like that! |
Next, using the [filename (name)] field and expressions to directly edit the file name on the hard disk:
 Pressing "Enter" renames and renumbers the selected files |
 Just like that! |
Worth noting that any mistakes made using expressions in this way can be undone by pressing Ctrl+Z
Filtering a list of files using a search rule
Expressions can be used as search filters, and in order to do so, the expression must be entered into the search field using the following format:
[=EXPRESSION]=1 or [=EXPRESSION]=0
All files that match the expression will return "1" and all that don't match, return "0". Decide which is required and use "1" or "0" accordingly.
Remember that the search field appears in many places throughout MEDIA CENTER, places that include:
- The search field itself (in the top right corner of the program)
- A view scheme search list
- "Edit Files To Show" area of the Customize View dialogue
- Play Radio Files
- The last.fm submission filter
- The links manager
and this method of expression application can be used in all of them.
An example of an expression formatted for use in the search field would be: [=isequal(formatdate([date imported,0],MM//yyyy),formatdate(now(),MM//yyyy),1)]=1 Which will list all files that have been imported this month.
Change how existing data is displayed
As well as the search field detailed above, expressions can also be used in many other places within MEDIA CENTER. Places that you might consider using expressions include:
- The player information bar (right click the information bar, choose "Customize")
- The image playback caption
- The "Rename, Move or Copy Files" tool
- Panes (aka categories)
- List columns (right click a column header and choose "Add expression column" from the menu)
- Thumbnail text
- The library field manager (Create expression based library fields)
- Theatre View
- The links manager (Use expressions to format the URLs for your links)
To give usage examples for all of these locations is beyond the scope of this page, so a few tips should suffice to get those interested up and running.
- For photos and videos, thumbnail text can be extremely useful, with the slight drawback that space there is a bit on the limited side. Using expressions here can be very productive indeed, for example, by using expressions, it is possible to instruct MEDIA CENTER to only display selected data if it actually exists, effectively getting rid of any of those "unknown ..." entries in the list.
- Expressions can be used in link properties (accessed via the link manager) so that a link will only be displayed if certain criteria are met, helping to keep the links bar uncluttered, populated with just those links that pertain to the current file list or selection. This topic contains a couple of interesting "Link Manager" tips that some might find useful.
- Some users choose to keep media files stored on drives, or in paths, dependent upon media type. The "Base path", "Directory" and "Filename" fields in the "Rename, Move or Copy Files" all accept expressions, offering the user powerful control over how the tool deals with files, dependent upon how they are tagged.
- Expressions can be saved as library fields in their own right. See Editable expression fields and this "Eureka moment" for a couple of related tips.
Specify data types for expression based fields
Now and again (or always, in the case of "List type" expressions), an expression based pane or library field may not sort correctly, or rather, may not sort as desired. Think about things like months... should they be sorted alphabetically or chronologically? They will sort alphabetically by default, so no problems there, but, if a chronological order is required, then a "Data Type" for the expression must be specified. Data types are set by appending the following string to an expression: &datatype=[DATA TYPE], where DATA TYPE is one of the following five values:
- List: A list of strings, separated by semicolons
- String: Sorts as strings (with smart number handling)
- Number: Sorts values as numbers (decimal or integer)
- Path: Sorts using a smart filename compare style
- Month: Sorts string month names (i.e. January, February, etc.)
The following screen images show these data type instructions in action:
| &DataType=[Month] | &DataType=[List] | |||
|---|---|---|---|---|
 Used in a pane, formatdate([date,0],MMMM) returns the months as requested, but the alphabetic order is a little confusing. |
 Adding the "month" data type, like so, formatdate([date,0],MMMM)&datatype=[month], takes care of the order. |
 No data type has been specified, so the expression results are presented literally, as individual string values. |
 Add the "list" data type to the expression and it is then formatted correctly in the pane. Here, the ListBuild function has been used to create a nested browsing tree. | |
Fields
Any text between brackets [] will be replaced with the corresponding field from your library. As an example, [Artist] would be replaced by Bob Dylan for any Bob Dylan tracks. If the text between brackets doesn't match any known fields, it will be left alone, [My Fake Artist] will be treated literally, square brackets and all. After the field name, a comma can be placed followed by a 0 or 1 to indicate whether the field should be formatted. So, [Duration] and [Duration, 1] will give "4:02" while [Duration, 0] will give "242". This is particularly important when working with the "Format" functions, where most times you will want the evaluator to work with the raw field contents rather than the formatted contents you see in the file list.
Function and field values in expressions are not case-sensitive. Available functions with descriptions and examples are listed below.
Functions
If(...): Ask closed questions and control output dependent upon result.
| If() | This will be the function you will likely use more than any other. It is typically used in conjunction with one or more other functions and allows you to give specific instructions depending upon whether the result is positive (1) or negative (0). The positive instruction is always given first. |
|---|---|
| Construction | if(expression to test,instructions if positive,instructions if negative) |
| Examples | if(isequal([artist],bob dylan,1),Genius,Mediocre) Wherever this expression is applied, be it as an expression column or category, as part of a renaming rule, thumbnail text, if the artist tag is Bob Dylan, MEDIA CENTER will produce Genius, and for all other artists, it will produce Mediocre. The "IsEqual()" function is described in the first table below.
|
Query, Test and Compare using "Is" Functions
All of the functions in this section, when used on their own, will only ever return one of two values, 1 (true) or 0 (false). There is a "FormatBoolean()" function that can be wrapped around these and allows us to specify the output for each case and is discussed in more depth in the Format section. The real power and versatility of these "Is" functions is released when they are wrapped inside the If() function discussed above.
IsEqual(...): Compares two values in one of nine specified modes
| IsEqual() | Compares two values in one of nine specified modes ("exact match", "Is greater than" etc.) and outputs 1 for a positive match and 0 for a negative match. If no compare mode is specified, the compare will default to 0. |
|---|---|
| Construction | isequal(1st value to compare,2nd value to compare,compare mode)
Available Compare Modes:
|
| Examples | isequal([artist],[album],1) If the 'artist' and 'album' values are the same, the output will be 1, otherwise, the output will be 0.
|
IsEmpty(...): Tests to see if a field is empty
| IsEmpty() | Tests any given field for data. If the field is empty, the function returns 1, and if populated, the function returns 0. There are two different test modes available, a "string" test, and a "number" test. This is because as far as MEDIA CENTER is concerned, fields designated as containing numerical values that are populated with the number zero, are empty. If no test mode is specified, the function will default to 0.
Pay particular attention to the third example offered below, as it covers a caveat that comes with this particular function. |
|---|---|
| Construction | isempty([field to test],test mode)
Available test modes:
|
| Examples | isempty([comment],0) If the comment field is empty, this expression will return 1, but if the comment field contains data, the expression will return 0.
|
IsRange(...): Tests a value for inclusion within a given range
| IsRange() | IsRange allows us to test if any given field falls inside any given range of values. If the field falls inside the given range, the function returns 1, and if outside the given range, the function returns 0. |
|---|---|
| Construction | IsRange([Field to Test],Specified-Range)
The range to test for can be letters or numbers, separated by a hyphen, without spaces, lowest value first, highest second. Letters and numbers cannot be mixed, the range can only be one or the other
|
| Examples | isrange([artist],a-c) Abba or Blondie will return 1 (positive), and ZZ Top will return 0 (negative).
|
IsMissing(...): Tests to see if a file exists on the system
| IsMissing() | This function checks to see if a file exists on the system. If the file is missing, the function returns 1 (positive), and if the file is found, the function returns 0 (negative). It is possible to specify a specific file to check for, but if you know that much, it will be quicker to fire up explorer and check yourself. This function comes in handy for checking the integrity of your MEDIA CENTER library as you can use it to produce a list of any files in your library that MEDIA CENTER cannot find. However, be aware that the larger your library, the longer this list will take to produce as MEDIA CENTER will need to physically check each files' existance in turn. |
|---|---|
| Construction | IsMissing(Full Path To File)
If no file path is specified, the function will default to checking the current file. |
| Examples | ismissing() Checks if the current file exists, and returns 1 (positive) if the file does not exist, and 0 (negative) if the file does exist.
|
IsRemovable(...): Tests to see if a file is stored on removable media
| IsRemovable() | Checks to see if a file resides on removable media and if so, returns 1 (positive), and if not, returns 0 (negative). There is not a lot to say about this function, especially since MEDIA CENTER comes equipped with a [Removable] field by default that is automatically populated with 1 for all files in the library that are on removable storage. The function works in exactly the same way as the IsMissing function described above, returning 1 (positive) if the file is on removable storage, and 0 (negative) if not. |
|---|---|
| Construction | IsRemovable(Full Path To File)
If no file path is specified, the function will default to checking the current file. |
| Examples | isremovable() Checks if the current file is on removable storage, and if so, returns 1 (positive), if not, the function returns 0 (negative). |
IsInPlayingNow & IsPlaying(...): Tests to see if a file is in the Playing Now playlist or currently being played
| IsInPlayingNow() | These two functions will be dealt with together as from their names, they are self-explanatory. One checks to see if a file has been added to the playing now list in any zone, and the other checks if a file in a list is currently playing or not, in any zone. With this in mind, their most practical use is as expression columns in a file list. To add an expression column to a list, right click on any existing column header and click on the "Add expression column" option. |
|---|---|
| IsPlaying() | |
| Construction | IsInPlayingNow() Checks the current file, and if in the Playing Now list, returns 1 (positive), and if not, returns 0 (negative).
|
| Examples | if(isinplayingnow(),Selected,Not Selected) As mentioned in the description, the ideal place for these functions is as 'expression columns'. If this example were used in an expression column, then files added to Playing Now will show as "Selected" and all other files would show as "Not Selected". If the idea here is to be able to quickly see which files have been added, this might look a bit 'busy' and defeat the purpose, to which end, it is perfectly acceptable to tell the expression that if a file is not in Playing Now, to output nothing, by simply not giving any instructions for the negative result, like so: if(isinplayingnow(),Selected,). Now, this expression column will only show "Selected" against files that are in Playing Now, leaving all others empty, giving a much easier column to read.
|
Change how existing data is displayed using Format functions
All of these functions (with the exception of FormatBoolean) take raw data from the library and allow us to present that data in a way that we choose. What does "raw data" mean? MEDIA CENTER stores duration information in seconds and converts that information into hours (if needed), minutes and seconds for display in the Duration column in a file list. Likewise, file size information is stored in bytes and is converted into Mb for display in the file list. Dates are stored using a UNIX system (use google if you want to know more about that) which means that the date field could contain 40121.8272916666683159 and MEDIA CENTER will display that as 04/11/2009 19:51 (if that is how your Windows locale setting displays date and time). So there you have it, raw data. The following section gives some idea of what is possible using the raw data and the Format functions. To instruct the expression evaluator to use raw data, a zero is added to the library field, inside the square brackets, like so: [Date Imported,0]
FormatDate(...): Formats a date value in a specified manner
| FormatDate() | As mentioned in the section introduction above, MEDIA CENTER stores date information in a UNIX style, and converts that information into legible date/time information we can understand. By default, MEDIA CENTER presents dates using the system locale settings. This function can be applied to any default library field that contains date information in order to have that information displayed in a non-default format. |
|---|---|
| Construction | formatdate([date field,0],Format,Output if date is empty)
Available format choices:
Flexible formatting is also available: (Note that these are case sensitive)
Output if date is empty: If the date is empty, anything placed here will be output instead. This could be plain text, such as "No Date", or a library field. This value is optional, and if not given, the expression will default to return nothing if the date is empty. |
| Examples | formatdate([last played,0],yyyy//MM//dd,Not Yet) This will return the last played date as year/month/day without the time, and regardless of the system locale setting. If a file has no last played info, the expression will output "Not Yet" instead.
|
FormatNumber(...): Formats a number to a specified number of decimal places
| FormatNumber() | FormatNumber() allows to format any given value to a set number of decimal places. |
|---|---|
| Construction | FormatNumber(Value to format,Number of decimal places,Output if value is zero,Label if value is greater than 1,Label if value equals 1)
Note that even if you are only interested in applying a label for those results that equal 1, you must also indicate the preceding instructions, if only to instruct the evaluator to ignore them, as shown in the examples below. |
| Examples | formatnumber([duration,0],2) This will return the duration of a track, in seconds, shown to two decimal places.
|
PadNumber(...): Adds leading zeros to any given number
| PadNumber() | This function is not a 'Format' function by name, but is by nature, hence its inclusion in this section. PadNumber is a nice, simple function that is used to add leading zeros to any given number value. |
|---|---|
| Construction | PadNumber(Field to pad,Total number of digits required) |
| Examples | padnumber([track #],2) This will add a leading zero to all track numbers between one and nine.
|
FormatDuration(...): Presents a duration of seconds in a reader friendly format
| FormatDuration() | MEDIA CENTER stores duration data in seconds, at up to sixteen decimal places. The value shown in the default "Duration" column in a file list is an internally formatted interpretation of this raw "Duration" data. As MEDIA CENTER automatically applies this formatting for us, there is not a lot of call for this particular function. |
|---|---|
| Construction | FormatDuration(Value to format)
"Value to format" can be either the raw duration data, or a given number of seconds |
| Examples | formatduration([duration,0]) This expression will duplicate the contents of the default [duration] field as shown in a file list
|
FormatFileSize(...): Presents a number of bytes in a reader friendly format
| FormatFilesize() | MEDIA CENTER stores file size data internally in bytes. This function will convert those byte values into reader-friendly values, 3.2 Kb or 10.4 Mb, for example. The function will also accept a byte value directly. |
|---|---|
| Construction | FormatFileSize(Value to format)
"Value to format" can be either the raw [File Size] data or a given number of bytes. |
| Examples | formatfilesize([file size,0]) This expression will duplicate the contents of the default [file size] field as shown in a file list
|
FormatRange(...): Formats a value as a range
| FormatRange() | This function places any given value into its place in any given range. |
|---|---|
| Construction | FormatRange(Value to format,Range size,Mode)
Value to format: This could be a specific word or number, or any library field
|
| Examples | formatrange([artist]) This will return the first letter from the [artist] field. Note that as range size and mode values were not specified, the function defaulted to one and automatic respectively.
Note that this function always starts number ranges from zero, 0-9, 10-19, etc, etc.. If you really need a number grouping that starts from 1, 1-10, 11-20, 21-30,etc. etc., you can use expressions to create a pseudo range. Full details, with a helpful explanation, of "1 based grouping" can be found on this page. |
FormatBoolean(...): Formats a boolean (true / false) value in a specified manner
| FormatBoolean() | This function is wrapped around another function and will return specified strings for true and false values returned by that other function. |
|---|---|
| Construction | FormatBoolean(True/False Test,String to use if true,String to use if false)
|
| Examples | formatboolean(isempty([number plays]),Never Played,Has Been Played) On it's own, the function isempty([number plays]) will return either 1 or 0. When wrapped inside a formatboolean function as shown here, the output for a true result will be "Never Played", and for a false result, the output will be "Has Been Played".
|
Functions for filename and field manipulation
The primary use of the functions in this section is to manipulate the data associated with any given file or files. When used with direct editing in the file list, or in the action window, as decribed here, they offer extremely fast and efficient methods for batch editing the actual tag data associated with multiple files.
Note that when used indirectly, in expression based columns, categories or library fields, the referred fields are not altered in any way, the data is merely presented in the expression field formatted as requested.
Clean(...): Returns a cleaned up version of a filled in template
| Clean() | The official description for this function is simply "Returns a cleaned up version of a filled in template". This function is better explained through demonstration in the examples below. |
|---|---|
| Construction | Clean(template to clean) |
| Examples | Clean([Artist] - [Album] /([Genre]/))
|
FixCase(...): Changes the case of a given string
| FixCase() | This function will output any given text string in one of five specified case modes. |
|---|---|
| Construction | FixCase(String to modify,Case mode to apply) The "String to modify" can be plain text, a library field, or a combination of the two. The five modes available are:
If no case mode is specified, the function will default to using "Title Case". Title case will start each principal word with a capital. More detail regarding title case can be found here |
| Examples | fixcase([album]) This will take the contents of the [album] field and present it with the specified capitalisation. As there is no specified mode here, the function defaults to 0, so, if an album is entered in the library as "Time Out Of Mind", the function will return "Time Out of Mind" (note the lower case "of")
|
Length(...): Returns the number of characters in a string
| Length() | This function returns the number of characters in any given string. |
|---|---|
| Construction | Length(String to count characters from) The "String to count characters from" can be plain text, a library field, or a combination of the two. |
| Examples | length([filename]) This will count the characters in the [filename] field and return the result. Spaces count as characters, so, C:\My File.mp3 would return 14.
|
Left(...): Retrieves a specified number of characters from the left of a value
| Left() | This function retrieves a specified number of characters from the left of any given value. |
|---|---|
| Construction | Left(Value to get characters from,Number of characters to get) "Value to get characters from" can be plain text, a library field, or combination of both. If more characters than exist are requested, all available characters are returned. |
| Examples | left([filename],3) This will return the drive letter, colon and first back-slash from the filename. If asked to show more characters than actually exist, the expression will return the entire value, also, remember that spaces count as characters too. |
Right(...): Retrieves a specified number of characters from the right of a value
| Right() | This function retrieves a specified number of characters from the right of any given value. |
|---|---|
| Construction | Right(Value to get characters from,Number of characters to get) "Value to get characters from" can be plain text, a library field, or combination of both. If more characters than exist are requested, all available characters are returned. |
| Examples | right([filename],3) This will return the last three characters from the filename. If asked to show more characters than actually exist, the expression will return the entire value, also, remember that spaces count as characters too. |
RemoveLeft(...): Trims characters from the start of a value
| RemoveLeft() | The output from this function will remove a specified number of characters from the start of any given value. |
|---|---|
| Construction | RemoveLeft(Value to remove characters from,Number of characters to remove) |
| Examples | removeleft([name],5) This would show the name field, with the first five characters removed. If asked to remove more characters than actually exist, the output will be blank, also, remember that spaces count as characters too.. |
RemoveRight(...): Trims characters from the end of a value
| RemoveRight() | The output from this function will remove a specified number of characters from the end of any given value. |
|---|---|
| Construction | RemoveRight(Value to remove characters from,Number of characters to remove) |
| Examples | removeright([name],5) This would show the name field, with the last five characters removed. If asked to remove more characters than actually exist, the output will be blank, also, remember that spaces count as characters too.. |
Mid(...): Retrieves specified characters from a value.
| Mid() | Mid() retrieves a specified number of characters from a specified starting point in any given string. |
|---|---|
| Construction | Mid(Value to get characters from,Character to start at,Number of characters to get)
|
| Examples | mid(12345) As values for "Character to start at" and "Number of characters to get" have not been specified, they default to 0 and 1 respectively and the function returns the first character in the string, 1.
|
Replace(...): Replace or remove strings from a value.
| Replace() | Quite simply, this function allows to search for a specified string in a specified value, and if found, remove the specified string, or replace it with another. |
|---|---|
| Construction | Replace(Value to check,String to check for,String to replace with)
|
| Examples | replace(My Sample String,S,Replaced ) All instances of upper-case "S" will be replaced by the text "Replaced ", (note the trailing space), resulting in "My Replaced ample Replaced tring"
|
Counter(...): Counts upwards in specified increments
| Counter() | This function can be used to number objects sequentially, from a specified starting point, in specified increments. The counter resets itself to zero after five seconds of inactivity. Counter() can exhibit a touch of wierdness when used in certain situations, which will be covered in the examples, that demonstrate why this one is not really a 'fits all' function. |
|---|---|
| Construction | Counter(Number to start counting from,Increments to count up in)
|
| Examples | counter() This shows the function in its simplest form. The counter will start at one and count upwards in increments of 1.
|
Functions for the manipulation and creation of list type fields
The default MEDIA CENTER library contains many fields that are referred to as "list type" fields. Users are also able to add their own "list type" fields to their libraries. A list type field contains one or more text items seperated by semi-colons. The semi-colons are referred to as the 'delimiter' and when displayed in a view category, text items seperated by semi-colons are displayed in a list of seprately selectable items. The "Keywords" field is a classic example of a list type field, which demonstrates how list type fields allow a single file to be tagged with many different keywords, as opposed to a 'standard' field, such as 'Genre', where a single file can only be tagged with a single genre. The following functions provide the ability to combine or build custom list type fields using the default semi-colon delimiter, or a specified delimiter, count the number of items contained in a given list, or extract a numbered entry from within a list. Two of the functions listed in this section are used to create "list type" data from two or more existing sources and could reasonably be considered to be functions more suited to those who are very familiar with MEDIA CENTER and how it gets its job done. If these functions are used to create a new 'calculated data' library field, they will not function as 'list type' fields unless the field is first created as a "User Data" field, with "List Type" specified. After creating the field in this way, it is possible to go back and edit the field, changing it to "calculated data" and entering an expression to be used. The "Eureka moment" occurred in November 2009.
ListBuild(...): Build a list from a series of values
| ListBuild() | This function provides the ability to create a single list from many different sources and allows a list delimiter to be specified. It has two modes that can be applied and are detailed below. Of these two modes, mode "0" (Combine all values) should be avoided. It has been included for 'function completeness' only, and when used, can produce some very strange results that do not filter as expected. In order for the data generated by this function to be treated as list data, the 'datatype' must be specified as [list]. |
|---|---|
| Construction | ListBuild(Mode,Delimiter,Items,To,Include) Mode: There are two different modes available:
Delimiter: The character used here will be used as a delimiter between each of the specified list items. To be clear, the keywords field uses a semi-colon delimiter by default; if a list is built using keywords and genre, and the specified delimiter is a back slash, it will be used between the keywords and genre fields when joining them, the semi-colons in the keywords field would not be altered. For example, if [keywords] contained "these;are;keywords" and [genre] contained "Rock", and these two were joined using ListBuild with a "\" specified as the delimiter, the resulting data would be "These;are;keywords\Rock". The real beauty and power of this function can be released when expressions are nested into the ListBuild instructions. For example, "listbuild(1,\,replace([keywords],;,\),[genre]" would return the data "These\are\keywords\Rock"
|
| Examples | listbuild(1,;,[keywords],[genre])&datatype=[list] This will return a semi-colon delimited list containing all keywords and genres. If either keyords or genre is empty, they will be ignored, so, the data returned for a file with no keywords, and a genre of "Rock" would be simply "Rock".
|
ListCombine(...): Combines two delimited lists into a single delimited list
| ListCombine() | Unlike the ListBuild function above, which can be used to create a list from any number of varying sources, ListCombine() is used to merge two specified lists into one. In order for the data generated by this function to be treated as list data, the 'datatype' must be specified as [list]. |
|---|---|
| Construction | ListCombine(First list,Second list,Input Delimiter,Output Delimiter) First List and Second List are specified library fields. Input Delimiter: This is the value that will be used to join the two specified lists. The value is optional, and if not specified, the function will default to using a semi-colon. Output Delimiter: This value is also optional. If specified, the function parses the output list (the result of the two lists, joined by the input delimiter) and replaces each occurrence of the input delimiter with the specified output delimiter. |
| Examples | listcombine([people],[places])&datatype=[list] The result here would be a single, semi-colon delimited list containing all the values from the [people] and [places] fields.
|
ListCount(...): Returns the number of items in a delimited list
| ListCount() | ListCount is used to return the number of items that exist in any given field, using any given delimiter. |
|---|---|
| Construction | ListCount([Field to count],Delimiter to use) Field to count: Typically, this will be a list type field, but this is not compulsory. The data in any field can be parsed using any chosen delimiter Delimiter to use: This is optional. If not specified, the function will default to using a semi-colon delimiter. Anything can be specified as a delimiter, from a single character to a whole word or words. |
| Examples | listcount([People]) No delimiter has been specified here, therefore the function will default to using a semi-colon. The result here will match the number of people shown in a properly tagged photo. Note that the function is smart, so, if a file has no [People] tag, the function will return zero (0), and if it has [People] data, but no semi-colon, the function will return one (1).
|
ListItem(...): Returns a specified value from a delimited list
| ListItem() | This function numbers list items starting from zero and returns the value of a specifically numbered item. |
|---|---|
| Construction | ListItem([Field],Number of item to retrieve,Field delimiter to use)
|
| Examples | listitem([filename],0,\) This function will return a file's drive letter plus colon. Note that the same result could be achieved by using left([filename],2), there is no 'right' or 'wrong' with these things, just personal preference, or 'what works for you'. A good rule of thumb is to use the simplest possible way to get to your goal, as less typing is better, and the more simple the expression, the easier it is to follow.
|
Functions that perform specific tasks
The functions in this group, with the possible exception of the math() function, are used to carry out very specific tasks, or for use in very specific areas of MEDIA CENTER.
Now(...): Retrieve and display the system date
| Now() | Now() will return the raw system date. "raw" data is discussed in the Field description, and also in the introduction to the "Format" functions. As MEDIA CENTER's raw date data is illegible, this function needs to be used with the "FormatDate()" function, which allows the current date, and time, if desired, to be presented in many different styles. |
|---|---|
| Construction | Now() |
| Examples | formatdate(now(),date) Returns the current date, without the time, formatted according to the system settings on which the function is running.
|
Math(...): Evaluates a given mathematical formula
| Math() | Math() can perform mathematical functions from the most simple to very complex. On the face of it, this might not appear to be all that useful, after all, Windows ships with Calc.exe does it not? However, where this comes into its own, is that the numbers to be used for the math formula can be derived from expressions nested within the Math() function, and now this particular function gets a little more interesting. |
|---|---|
| Construction | Math(Formula to evaluate) |
| Examples | math(10+4) This will return the answer, 14. Hardly earth shattering, but demonstrates the function working at its simplest level.
|
Hexify(...): Hexifies a string to make it suitable for website usage
| Hexify() | The only place this function is likely to be used is in the "Link Manager". Websites often don't like spaces in their addresses, and punctuation could confuse a site's search engine. Hexify attempts to take care of this by replacing spaces and punctuation with web friendly alternatives. For example, Bob Dylan would become Bob%20Dylan. |
|---|---|
| Construction | Hexify(Value to hexify) |
| Examples | hexify([artist] - [album]) Oasis - (What's The Story) Morning Glory? becomes: Oasis%20-%20%28What%27s%20The%20Story%29%20Morning%20Glory%3F |
CustomData(...): Sequence numbering when renaming files
| CustomData() | The official description for this function goes as follows: "Returns custom data stored in a file array (used primarily for internal uses)." There is no recorded practical use for this function, with the exception of using it with a hash symbol in the library tool called "Rename, Move, & Copy Files...". When used in the directory or filename rules of this tool, this function will number the files in the list from first to last, starting at number one. As long as any desired numbering is to begin at one, this function is a reasonable alternative to combat the wierdness demonstrated by the Counter() function, and could be particularly useful when renaming image files. If the numbering is required to start counting from anywhere other than one, then Counter() will need to be used, taking the wierdness and its work arounds into account. |
|---|---|
| Construction | CustomData(#) |
| Examples | padnumber(customdata(#),4)_Christmas Party 2007 It's important to remember that this function will only work when used as part of the renaming rule for either filename or directory (or both) within the "Rename, Move, & Copy Files..." tool. In this example, imagine 324 photos from the Christmas party of 2007 were selected for renaming, and this expression was entered into the filename field. The resulting filenames would be 0001_Christmas Party 2007.jpg through to 0324_Christmas Party 2007.jpg. Note how the "padnumber()" function has been used to add the leading zeros. |
Tag(...): Returns a physical file tag (rather than looking in the database)
| Tag() | This function originally came into being as a need arose for there to be a way to re-import the exif date information from image files without affecting any other tags. To that end, the function works well, but that's really where it's functionality ends. Success with any other fields has been extremely limited indeed. The main reason for this is because, when using this function to query specific tag data blocks in an image file, the fields referenced by the tag() function must be spelled exactly as they appear in the tag block within the file, and yes, they are case sensitive. It is also extremely important to know that when building a file list that contains a "Tag()" derived column, MEDIA CENTER will be inordinately slower, 1000's of times slower, in building that list than it would be without the "Tag()" column. This is because each and every file in the list must be queried individually for the contents of the specified tag. This particular function is best used using the "inline editing" method outlined in the "When, Where and How to use expressions" section of this page, to pull the desired data into the main library database and then reference the information from the database. |
|---|---|
| Construction | Tag(Field to read from the file) Specific tag data blocks from jpg files can also be referenced: Tag(Tag Block To Query: Field to read from the tag block)
|
| Examples | tag(artist) This will return the artist information from a file if that file contains the artist tag
|
TVInfo(...): Returns television-specific information about a file
| TVInfo() | Used to retieve and display specified televison information for a file. |
|---|---|
| Construction | TVInfo(Information to retrieve)
Information to retrieve: The options available for use here are:
|
| Examples | TVInfo(namedisplay) Click on "Tools > Options > Theater View", then click on "Customize file info panel", then choose "Television Program" from the drop-list at the top. It is then possible to use this function to tailor the information displayed on screen in Theater view when looking at TV programs. Some of the default items already utilise this function offering real world, real time examples of their usage.
|
Note(...): Retrieve information from a note
| Note() | Since build 14.0.111, MEDIA CENTER has shipped with a "Notes" feature. One of the many uses available via notes is the ability to store contact information, and that information can be labelled. Labels are typical contact information labels such as "Home phone", "Work phone", "Email" etc. etc.. This function can retrieve and display the contents of specified labels from a note. |
|---|---|
| Construction | Note(Field Label,Field Type,Occurrance)
|
| Examples | note(phone) note(phone,home) note(phone,home,1) Here are three sample notes expressions. In the image below, they have been used to create expression list columns, with each expression used shown in the column header. The note, with labels on show, is visible on the right hand end of the image. When comparing the note with the data returned by each expression, it should become apparent how each expression is working. |
Redundant Functions?
Taken at face value, all of the functions in this section would appear to be a little on the redundant side, falling neatly into the "a long way for a shortcut" category. MEDIA CENTER could possibly rely on these functions internally, exalting their status to "highly useful" or "essential" even, but as this page is designed for end users, not MEDIA CENTER, end users will find these functions redundant, and they are included here in the name of completeness only.
Field(...): Returns the value of a library field
| Field() | Place the name of any library field inside this function, and it will return the contents of that library field for each file. Entering the field name inside square brackets as normal, without the function, returns the same data. |
|---|---|
| Construction | Field(Field name to retrieve) |
| Examples | field(duration) Returns the formatted duration value for each file. field(duration,0) would return the raw duration data. Simply entering [duration] or [duration,0] returns the same result. |
FilePath(...): Returns the path from a specified filename
| FilePath() | This function will return the file path information from root to parent folder for all files in a list, or for any specified file. MEDIA CENTER has a [Filename (Path)] library field by default, which is probably easier to use or reference than this function. |
|---|---|
| Construction | FilePath(Filename to check)
|
| Examples | filepath(C:\Music\File.mp3) The result here would be... "C:\Music"
|
FileName(...): Returns the name from a specified filename
| FileName() | This function will return the file name information for all files in a list, or for any specified file. MEDIA CENTER has a [Filename (Name)] library field by default, which is probably easier to use or reference than this function. |
|---|---|
| Construction | FileName(Filename to check)
|
| Examples | filepath(C:\Music\File.mp3) The result here would be... "File.mp3"
|
FileVolume(...): Returns the volume name from a specified filename
| FileVolume() | This function will return the volume name information for all files in a list, or for any specified file. MEDIA CENTER has a [Volume Name] library field by default, which is probably easier to use or reference than this function. |
|---|---|
| Construction | FileVolume(Filename to check)
|
| Examples | filevolume(C:\Music\File.mp3) The result here would be... "C:"
|
AlbumKey(...): Returns a unique album key for a file
| AlbumKey() | Testing reveals that this function simply returns an "[album artist (auto)] - [album]" string for each file. If two different albums happen to have the same [album artist (auto)] and [album] data, their respective AlbumKey() will not be unique. |
|---|---|
| Construction | AlbumKey() |
| Examples | AlbumKey() Create a new expression column in a list using this function and the result will be a column populated with the [album artist (auto)] - [album] data for each file. |
AlbumArtist(...): Returns the calculated album artist for a file
| AlbumArtist() | This function simply returns the "[album artist (auto)]" data for each file. |
|---|---|
| Construction | AlbumArtist() |
| Examples | AlbumArtist() Create a new expression column in a list using this function and the result will be a column populated with the [album artist (auto)] data for each file. |
AlbumType(...): Returns the album type for a file
| AlbumType() | This function simply returns the "[album type]" for each file. [album type] is a default MEDIA CENTER library field that informs the user of an album's status in the library, such as "Single artist (complete)" or "Multiple artists (incomplete)" |
|---|---|
| Construction | AlbumType() |
| Examples | AlbumType() Create a new expression column in a list using this function and the result will be a column populated with the [album type] data for each file. The [album type] library field will work just as well, and return the same information. |
Size(...): Returns the size of a file in a media type independent manner
| Size() | Dependent on media type, this function returns the following information:
|
|---|---|
| Construction | Size() |
| Examples | Size() Create a new expression column in a list using this function and the result will be a column populated with media type dependent data for each file as listed in the function description above. |
TrackNumber(...): Returns the track # of a file
| TrackNumber() | This function simply returns the track # of a file. If a file has no track # assigned, the function returns zero. This function has no real use and is actually flagged as "For internal use only", so, not one for end users, and again, only included here for the sake of completeness. |
|---|---|
| Construction | TrackNumber() |
| Examples | TrackNumber() Create a new expression column in a list using this function and the result will be a column populated with the track # information for each file. |
marko 13:20, 7 October 2010 (CDT)