Difference between revisions of "Media Center expression language-NEW"

From JRiverWiki
Jump to: navigation, search
Line 21: Line 21:
 
* Theatre View
 
* Theatre View
 
* The links manager (''Use expressions to format the URLs for your links'')
 
* The links manager (''Use expressions to format the URLs for your links'')
 +
 +
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.
  
 
====Fields====
 
====Fields====
Line 32: Line 34:
 
===If(...): Outputs different values depending on the value of the first parameter.===
 
===If(...): Outputs different values depending on the value of the first parameter.===
  
{| style="width: 100%" border="1"
+
{| style="width: 100%" align="top" border="1"
 
! scope="col" style="background: #3CB371; color: black" width=100 | Function  
 
! scope="col" style="background: #3CB371; color: black" width=100 | Function  
 
! scope="col" style="background: #3CB371; color: black" width=400 | Description
 
! scope="col" style="background: #3CB371; color: black" width=400 | Description
! scope="col" style="background: #3CB371; color: black" | Construction
+
! scope="col" style="background: #3CB371; color: black" width=400 | Construction
! scope="col" style="background: #3CB371; color: black" | Examples
+
! scope="col" style="background: #3CB371; color: black" width=400 | Examples
 
|-
 
|-
 +
|- valign="top"
 
! scope="row" style="background: #A8E4A0; color: black" | If()
 
! scope="row" style="background: #A8E4A0; color: black" | 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. || if(<''expression to test''>,<instructions if positive>,<''instructions if negative''>) || if(isequal([artist],bob dylan),Genius,Mediocre)
+
| 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. || if(<''expression to test''>,<instructions if positive>,<''instructions if negative''>) || '''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.''
 +
 
 +
'''if(isequal([artist],bob dylan,1),Genius,if(isequal([album],Joshua Tree,8),Great Album,Mediocre))'''
 +
 
 +
''Here, we have two nested "If" functions. First we ask if the artist is Bob Dylan, if the result is positive, write "Genius". If the artist is not Dylan, we then ask if the album is "Joshua Tree", if yes, write "Great Album", and if no, write mediocre''
 +
|}
 +
 
 +
On it's own, "If()" is rather boring and not a lot of use. When used in conjunction with other functions, however, it becomes very powerful indeed. In the two examples above, the numbers 1 and 8 have been used. These are comparison mode switches used by the IsEqual function. There are 8 different compare modes in total, all of which are detailed below. Note how the second example ends with two closing parenthesis, one for each "If" function.
 +
 
 +
===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.
 +
 
 +
{| style="width: 100%" align="top" border="1"
 +
! scope="col" style="background: #3CB371; color: black" width=100 | Function
 +
! scope="col" style="background: #3CB371; color: black" width=400 | Description
 +
! scope="col" style="background: #3CB371; color: black" width=400 | Construction
 +
! scope="col" style="background: #3CB371; color: black" width=400 | Examples
 +
|-
 +
|- valign="top"
 +
! scope="row" style="background: #A8E4A0; color: black" | IsEqual()
 +
| - || - ||
 +
|-
 +
|- valign="top"
 +
! scope="row" style="background: #A8E4A0; color: black" | IsEmpty()
 +
| Cell B || Cell C || Cell D
 +
|-
 +
|- valign="top"
 +
! scope="row" style="background: #A8E4A0; color: black" | IsRange()
 +
| Cell B || Cell C || Cell D
 +
|-
 +
|- valign="top"
 +
! scope="row" style="background: #A8E4A0; color: black" | IsMissing()
 +
| Cell B || Cell C || Cell D
 +
|-
 +
|- valign="top"
 +
! scope="row" style="background: #A8E4A0; color: black" | IsRemovable()
 +
| Cell B || Cell C || Cell D
 +
|-
 +
|- valign="top"
 +
! scope="row" style="background: #A8E4A0; color: black" | IsInPlayingNow()
 +
| Cell B || Cell C || Cell D
 
|-
 
|-
! scope="row" | ==test==
+
|- valign="top"
| Cell B
+
! scope="row" style="background: #A8E4A0; color: black" | IsPlaying()
| Cell C
+
| Cell B || Cell C || Cell D
| Cell D
 
 
|}
 
|}

Revision as of 17:46, 14 August 2010

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. 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.

Expressions can be used in many places within MEDIA CENTER, for varying reasons. Places that you might consider using expressions include:

  • The player information bar
  • The image playback caption
  • The "Rename, Move or Copy Files" tool
  • The tag window
  • Panes (aka categories)
  • List columns
  • Thumbnail text
  • The search field
  • The library field manager (Create expression based library fields)
  • Theatre View
  • The links manager (Use expressions to format the URLs for your links)

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.

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. After the field name, a comma can be placed followed by a 0 or 1 for whether the field should get 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.

All of this should become more clear if you study the examples offered below.

Functions

If(...): Outputs different values depending on the value of the first parameter.

Function Description Construction Examples
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. if(<expression to test>,<instructions if positive>,<instructions if negative>) 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.

if(isequal([artist],bob dylan,1),Genius,if(isequal([album],Joshua Tree,8),Great Album,Mediocre))

Here, we have two nested "If" functions. First we ask if the artist is Bob Dylan, if the result is positive, write "Genius". If the artist is not Dylan, we then ask if the album is "Joshua Tree", if yes, write "Great Album", and if no, write mediocre

On it's own, "If()" is rather boring and not a lot of use. When used in conjunction with other functions, however, it becomes very powerful indeed. In the two examples above, the numbers 1 and 8 have been used. These are comparison mode switches used by the IsEqual function. There are 8 different compare modes in total, all of which are detailed below. Note how the second example ends with two closing parenthesis, one for each "If" function.

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.

Function Description Construction Examples
IsEqual() - -
IsEmpty() Cell B Cell C Cell D
IsRange() Cell B Cell C Cell D
IsMissing() Cell B Cell C Cell D
IsRemovable() Cell B Cell C Cell D
IsInPlayingNow() Cell B Cell C Cell D
IsPlaying() Cell B Cell C Cell D