Plugins & Parsers

this page describes how to use two advanced brightauthor\ connected and {{brightauthor classic}} features custom autorun plugins and parser scripts these instructions assume a certain level of familiarity with brightscript docid\ r7xc0 ze4u0br662li2sj this is not a comprehensive guide to writing custom scripts for brightauthor\ connected or brightauthor classic; it is meant to provide a general outline and best practices for writing those scripts plugins plugins allow you to add script extensions to a standard presentation autorun for example, you can use plugins to change variable values, extract information from a txt , csv , xml , or json file to display it onscreen, change the contents of a playlist, or change how the presentation responds to external input plugins have two primary benefits over custom autoruns they can be easily inserted into multiple presentations, including newer and older versions of the same presentation they are not dependent on a certain autorun or firmware version, greatly reducing the complexity involved in updating custom brightscript deployments autorun plugins brightauthor\ connected to designate one or more custom plugins in brightauthor\ connected if you are a content cloud user, upload your plugin to the server through the content upload (see content docid\ gpjwf1lnjhau eqzjmfuq ) if you are a bsn control user, skip directly to step 2 to add a plugin to the presentation attach it to your presentation (see presentation settings docid\ a6ali6u szxhuansk6t3 ) if needed, refer to plugin message event docid\ j999admh wdx3xwbbkz0n to trigger state changes brightauthor classic brightauthor classic versions that are older than 3 7 do not support plugins screenshot 2024 06 07 at 10 29 53 am png to designate one or more custom plugins in brightauthor classic navigate to file > presentation properties > autorun select the add script plugin button give the plugin a name (which must be the same as the \<plugin name> described in the initialization function below) select browse to pick a brs file and select ok once you load the plugin, it can interact with the presentation using plugin message events or send plugin message commands see the brightsign github page https //github com/brightsign/brightauthor plugins for brightauthor\ connected / brightauthor classic plugin examples plugin structure plug in scripts must include an initialization function in the form of \<plugin name> initialize() actions that take a lot of time should not be done in the initialization routine, because actions in the routine are synchronous instead, start a timer that will be caught by the plugin event handler soon after the routine runs, and execute the longer code segment there for example, instead of unzipping a file in the initialization routine, do it through the plugin event handler with a timer started in the routine the initialization function is passed three parameters msgport as object uservariables as object o as object this is the bsp associative array from the autorun it is required for the initialization function to return an associative array to process events, the plugin script must provide a processevent() function that is a member of the associative array returned by the initialization function described above the processevent() function is passed a single event object the function then returns a boolean indicating whether or not the autorun should continue processing the event object the function will return true if it handles the event and the standard autorun should not continue processing the event the associative array that defines the object must also include an objectname entry that defines the name of the object the following is an example of a script plugin file named pizza brs brightscript function pizza initialize(msgport as object, uservariables as object, bsp as object) print "pizza initialize entry" print "type of msgport is ";type(msgport) print "type of uservariables is ";type(uservariables) pizzabuilder = newpizzabuilder(msgport, uservariables, bsp as object) return pizzabuilder end function function newpizzabuilder(msgport as object, uservariables as object, bsp as object) pizzabuilder = { } pizzabuilder msgport = msgport pizzabuilder bsp = bsp&#x9; pizzabuilder uservariables = uservariables pizzabuilder objectname = "pizzabuilder object" pizzabuilder processevent = pizza processevent return pizzabuilder end function function pizza processevent(event as object) print "pizza processevent entry" print "type of m is ";type(m) print "type of event is ";type(event) ' swallows timer events telling the autorun not to process them if type(event)= "rotimerevent" then return true else return false endif end function receive a plugin message the following example code shows how to write a script that receives a commands docid\ lg8ilydnib0pl8tvxtkbo command from the autorun this code listens for a message sent to the plugin named “pizza” and then prints the message this example uses debug output instead of print statements print statements only show up in the serial console, while debug statements show up in the system log brightscript function pizza processevent(event as object) m bsp diagnostics printdebug("@@ pizza processevent entry") m bsp diagnostics printdebug("@@ type of m is " +type(m)) m bsp diagnostics printdebug("@@ type of event is " +type(event)) if type(event) = "roassociativearray" then if type(event\["eventtype"]) = "rostring" if event\["eventtype"] = "send plugin message" then if lcase(event\["pluginname"]) = "pizza" then 'the plugin name is case sensitive' pluginmessage$ = event\["pluginmessage"] m bsp diagnostics printdebug("@@ received pluginmessage " + pluginmessage$) return true endif endif endif endif return false end function send a plugin message the following example code shows how to write a script that sends a message string to trigger a plugin message docid\ afdht43lrah0tfu6hh tf event brightscript print "pizza processevent entry" print "type of m is ";type(m) print "type of event is ";type(event) if type(event) = "rotimer" then pluginmessagecmd = createobject("roassociativearray") pluginmessagecmd\["eventtype"] = "event plugin message" pluginmessagecmd\["pluginname"] = "pizza" pluginmessagecmd\["pluginmessage"] = "toppings" m msgport postmessage(pluginmessagecmd) return true endif return false end function parsers parsers can perform many of the same custom functions as plugins (for example, extracting information from a txt , csv , xml , or json file to display it onscreen or changing the contents of a playlist); however, rather than being triggered by a command or being associated with an event, parsers are associated with a downloaded data feed or a file on the microsd card this means that any function that is triggered by an event must be written as a plugin, not a parser a parser does not need to work exclusively with the data in the feed associated with it once the parser starts running, you can use it to delete a file on the storage, send a udp command, or download another feed or file you can find examples of brightauthor classic parsers on the brightsign github page https //github com/brightsign/brightauthor parser scripts rss converter converts a standard rss feed into the same format as a bsn live text feed, allowing you to display rss feed items by index number in a live text state live text title and description allows you to display both the title and description of an rss item in a live text state parser scripts rss parser scripts allow you to manipulate data sets from incoming rss feeds you can create rss parser scripts for a wide array of system and presentation functions you can designate a parser for an rss feed in brightauthor\ connected ( presentation settings docid\ a6ali6u szxhuansk6t3 ) or in brightauthor classic ( data feeds docid 7jvbwpivjox6kkzvuyeg3 ) important the parser file must have a brs extension the following parameters can be used with an rss parser subroutine xmlfilename$ the name of the xml file this value is provided by the presentation autorun itemsbyindex an array of the descriptions the script should fill in this array if the live text object is using the “item index” to display items from this feed itemsbytitle an associative array of titles, descriptions the script should fill in this array if a live text object is using the “item title” to display items from this feed uservariables an associative array of current user variables (which are provided by the autorun) this is provided in case you want to analyze or modify the user variables the following piece of example code can be used to parse rss text xml = createobject("roxmlelement") if not xml parse(readasciifile(xmlfilename$)) then print "xml read failed" else if type(xml channel item) = "roxmllist" then index% = 0 for each itemxml in xml channel item itemsbyindex push(stri(index%) + " " + itemxml description gettext()) index% = index% + 1 next endif endif end sub parser scripts mrss you can use a script to parse non mrss feeds and provide the data in a format that can be used by media rss feeds docid\ nwu8g3cx7osnce 82u6ec in brightauthor\ connected or brightauthor classic to designate a parser for an mrss feed in brightauthor\ connected, go to presentation settings docid\ a6ali6u szxhuansk6t3 to designate a parser for an mrss feed in brightauthor classic, go to data feeds docid 7jvbwpivjox6kkzvuyeg3 important the parser file must have a brs extension the following parameters can be used with an mrss parser subroutine filename$ the name of the feed file to be parsed this value is provided by the presentation autorun items an array of associative arrays representing mrss items to be played by media rss feed states this array is empty upon entry to the parser subroutine and should be filled by the script when the parser subroutine exits, the autorun will supply the data in the array to media rss feed states for playback see the item array specification section below for a list of associative array parameters metadata an associative array containing optional metadata items pertaining to the entire playlist/feed items array specification the parser script should add associative arrays to the items array–each associative array represents a single media item to be played back the order of items in the array specifies the order of playback each associative array consists of one or more key value pairs all values must be strings–including numerical values the following table outlines accepted key value pairs key value example notes url a download url for the file brightsign biz/images/myfeedpic1 jpg required – the item will be ignored if this value is not present medium video | image | audio | document "video" suggested – if the medium and type values are not present, the medium value will default to "image" type video/ , audio/ , image/ , text/html, application/widget "video/ " suggested – if the medium and type values are not present, the type value will default to "image/ " duration the display duration in seconds "30" optional – this value applies to images only, and has no effect on other media types if not specified, this value defaults to "15" title the value for the mrss title field "myfeedpic1" optional description the value for the mrss description field "$5 99" optional size the size of the file in bytes "942061" optional guid a unique value for the file "ab05caf" optional – when this value changes, the player will re download the file mrsscustomfields an associative array of arbitrary key value pairs {key1 "custom field a", key2 "custom field b"} optional – use this associative array to include custom mrss fields metadata specification the metadata object is an empty associative array when the parser subroutine is entered this associative array can accept optional key value pairs that represent properties for the entire feed all values must be strings–including numerical values the following table outlines accepted key value pairs key value example notes title a title for the feed "myfeed1" ttl the time to live in minutes "5" this value represents how long the feed will be stored (whether it's utilized by the presentation or not) before being refreshed the user will also set an update interval when adding the data feeds docid 7jvbwpivjox6kkzvuyeg3 to the brightauthor classic presentation; if the ttl value is specified, the presentation will use the lesser of the two values to determine the refresh frequency