Latest Version: 1.04 | Website
Author: culex

Note: Feel free to read the Onair Module Notes as formatted on my site.

Summary
Onair is a module designed for one or more Radio stations, TV stations, or any organization with a regular schedule to publish their weekly schedule along with playlists. It has one block that will display the current program, host/DJ and related information such as playlists. Overall, an excellent but simple module. Currently, I'm still working to get our playlists stuff working so this doesn't focus on that issue, especially since I don't have examples for the formats. We're looking at scraping XML feeds into a database and working with it that way.

Features:
* Fields: Station, Title, Host, Day, Time (start/end), Description, Plugin, Stream
* Block: Now Playing/Coming Next (jquery/ajax block)

Installation
I've only done a fresh installation, although it was updated to 1.04 (from 1.03) early in my start of the usage. So, I did update it per usual module updating, and it worked fine. Installation is done normally.

Errors, Bugs, Defects
One quick comment related to issues I dealt with. Overall, I think this module would do a lot better if it were to measure time based in seconds from 12:00 midnight of the schedule's timezone. I thought that a lot of the time calculations would have been much easier and that my solutions were a bit of a kludge due to it.

Templates
The onair_index.html template is never used. The main index actually uses the onair_program.html template and defaults to the current day. I needed a page that showed the entire weekly schedule. So, I wrote a function and used the _index template. I'll note, too, that the onair_program.html template has some problems in the code that could result in badly formed HTML.

Edit Schedule Times Not Kept/Shown
When editing an existing schedule entry, it doesn't display the start/stop times as assigned in the database; it always shows 12:00 midnight (0:00) in both 12- or 24-hour format. I fixed this one. My general recommendation would be for the module to store data on a 24-hour format and then convert to the 12-hour format for display as desired. I think this would simplify a lot of code dealing with the times.

To fix, there were a couple of places. In the end, all I needed to do was this "simplification" edit to /admin/index.php lines 172-193 from:
changed to:

This also allows you to remove the onair_XoopsFormTimeUs and onair_XoopsFormTimeEuro functions in includes/classes.php which puts in an ElementTray layer that really isn't needed (and it wasn't work correctly either, and is 2 of the 3 classes in that file).

Alternatively, this below worked, too, (what I did before using the combined code solution above). In admin/index.php, edit lines 177-179 to be:
and lines 187-189 to be:

And for the Add New function to operate correctly, you have to also edit two other locations -- first lines 368-370 to be:and lines 380-382 to be:

Another part of the issue was that the XoopsFormSelect call in the includes/classes.php file weren't used correctly. It is defined thusly:
To fix, change lines 53 and 84 to:


Time Sorting 12-Hour Format
Sorting dates and times doesn't work right using the 12-hour version with am/pm. In the 12-hour preference (as used in the US), the information is written to the database in a text field of HH:MM:SS AP. But when sorting, since it's a text field, 01:00:00 AM comes before 12:00:00 PM, which of course isn't correct. Affects displays both in the user and admin sides. To quickly compensate, I changed the module to use the 24-hour preference and then when modifying the templates (as I always do to every module), changed the display method with Smarty.
Shows to/past Midnight

The module currently doesn't support shows that start before midnight and go beyond midnight. To compensate, enter the show twice, one to midnight (23:59:59) and the other from midnight (0:00) to when it ends.

The module sort of supports shows until midnight, however there is an error. When adding a show, it displays a midnight (00:00:00) end/stop time of 00:00:00. However, then it won't display properly (with the on-air info nor in the now-playing block) in the module because of how the between SQL query operates. So, it really needs an end time of 23:59:59. Fortunately, the edit function takes care of that properly setting the end time of 00:00:00 selected to be 23:59:59. Then it works as advertised.

I thought this would be a simple in admin/post.php, but I didn't find it, so since I have a work-around, it's working fine for me. But it does need to get fixed for the add subroutine.

Enhancement Requests
These enhancement requests and my solutions were reported to the author to use as they see fit, and I'll provide my edits and updates for their use in the next version (hopefully). I think they were additive, but I also wasn't dealing with more than one station at a time which could complicate things, I think, if used. I also reused the Station and Stream fields to be something else since we only had one of each (at least sorta, but it was nice to use the fields without rebuilding the module further). It would be nice, too, to have a set of extra custom fields, maybe 5 or so.

Admin Menu
The Admin Menu needs to stay at the top of the pages and generally the admin area needs to do a better job of telling you where you are.

Now Playing/Coming Up Block and AJAX
The block using jquery (and ajax) worked, but a couple of comments.

One, it had a system load that wasn't really necessary. It only needs to check once in awhile, not 2 http calls every 20 and 30 seconds (5 times/min/browser really adds up in terms of server loading). It should be max once/minute max or something and should instead only check every minute or so around the next schedule change and using ajax to obtain an XML object including ALL of the info in a single call including the system time, the station time, doing the math and only checking again near/close to the expected change.

Second, the jquery call, while to a current version of jquery, interfered with the call made originally in the theme and broke my other scripts and plugins since it loads on top of them. The script call should be done only if necessary (but I've not investigated just how to do that). I just removed the loading of the script in the template.

Also, because of the data, the block display changes sizes depending on the content moving stuff around on the page (but that can be fixed in CSS and templates); it's just that some users might not be capable of dealing with it.

The templates used in the AJAX calls were the file templates because of the way they were called instead of those in the database (you're using a custom set, right; if not you should as it makes it easier to control between updates). To fix, in onair_ajaxassign.php and onair_ajaxassign2.php change line 25 to call the template from the database like this: $tpl->display('db:onair_div1.html');

Therefore, I created a new setup for this block using AJAX and called it backend. It is actually an RSS feed in XML that can be used by anyone including the new code I created for the now playing block. I also wanted to configure the number of upcoming shows and how that is displayed. Also, if you'd like this data to be able to be used via RSS pulls on another system, then an AJAX call is appropriate. The current solution isn't XML- or RSS-based, but the one I created is.

Weekly Schedule At-a-Glance
We needed a weekly schedule to show at a glance. I created a page for this based on the main index that just pulled and displayed more of the schedule, not too hard, really, but took some time getting it to show well.
Overnight Schedule

The module doesn't appear to handle the ability to have a show that spans midnight. Also, the display block doesn't appear to handle that either. Continuing to investigate and figure that out. I'd also like the ability to deal with on-air/streaming aspects so that I can help users understand whether or not they will only get it on the stream and/or on-air. Nor does it allow the ability to go all the way to midnight (latest stop time choice is 23:45), although you can select 0:00. You can add two entries for this and then it works well, to a degree, but it's not clear on the schedule that it continues without putting more info in.

HTML Out of Functional Layer
This module has at least one place where HTML is embedded in the functional code. When working with things like images and linked images, this should be broken up and passed as object data to a Smarty template to allow template designers better control without having to go into the functional layer. It can be done, but it requires smarty regex usually.

Good job, tnx!

Great stuff, thanks Mboyden for taking time to haul over this onair module So much more easy to make work right when someone else than myself looks this over.

Half of these items I would never have caught, simply because ...well I made them and I guess am blind to see the issues

Thanks again for taking the time to look at this. Nice to see people use this module (my very first Xoops Module ever)

I like it .. very nice module

I am a happy user of the Onair and pleasent with this changes.
I hope that Culex will update in the module.

Thanks Culex for create it and mboyden for his Review.

Why not simply using datetime or timestamp for the start and end time?
When both fields are indexed, you can get the shows for one day with:

ghia wrote:Quote:
In short, because it's a weekly schedule where the same event occurs at the same time every day of the week, say 11:30a-1:45p every Tuesday, throughout the 24x7 week timeframe. Instead of entering it as a calendar event 52 times for an entire year, we just enter it once and it repeats each week.

So, your SQL select code upon brief inspection looks fine. But it's how to get the timestamps to be for that particular day because otherwise the select statement won't work. That's the tougher part. Dates and times are a little tricky, although I've got some good php functional code for that stuff that I've gleaned from the web, but it does really want things in gmt timestamps. But, it's a weekly schedule based on a specific timezone, that's why I suggested that stored times should be from 0:00 for the day which becomes fairly simple to convert into a usable timestamp on a weekly basis.

BTW, the SQL code could just as easily be an OR statement instead of a UNION which should be faster that a union of two select statements, but either way, the logic seems sound given the right data to base it on.

You could use for instance the timestamp field type which is the unix date with an arbitrary fixed offset for the start of the week
The days start on offset + daynum* secondsinaday ends on offset + (daynum +1)* secondsinaday (values for 0hours_today and 0hourstomorrow)

AFAIK the MySQL reduces to the use of only one key to make a select. By having a union the first select is made on the starttime index and the second on the endtime index (if needed, guided by adding a use index clause), which limit the recordsets to very manageable and easy retrieveable.
Of course for this (repeated) 1 week shedule, it won't have much effect, but if you need a perputual calendar, with many events and thousands of records over the years, it will be well performing.

Would this be a nicer aproach in the start / stop time ?

Generally, when doing time relative stuff, calculations, etc., I've always found that working with unix timestamps works best because it is the absolute common ground for datetimes and then doing a final display conversion at the very end.

Because of the weekly schedule aspect to this, best would be to use either a Sunday midnight zero-hour for all, as Ghia suggested, or stick with the dayOfWeek and timeStamp, but I'd suggest a timestamp that is seconds from 0:00 of that day. I'm not sure either will be the panacea because of the cyclical nature of a weekly schedule and getting those upcoming events for "next week" as opposed to "next day".

For final timestamping, you can use the XoopsLocal::formatTimestamp code (as you did in some of it) so that the time is in website time (as opposed to server time which may be different, but both are set in the XOOPS settings).

Finally, pass both 12- and 24-hour formatted display into the templates and the config var and let the template decide which to display. There is less lines of code and only one additional executed line of code/event and by passing the other dayOfWeek and timeStamp as well one could actually do calculations and comparisons more easily in the smarty template code.

Some code:
// event is Tuesdays, 11:30 - 13:45
// pull from dB is:
$config = array('timetype' => 1); // 1 means 12-hour am/pm
$event = array('day' => 2, 'start' => 41400, 'end' => 49500);
$timestampToday = strtotime('midnight');
// for each event pulled from the query
$event['startUTC'] = $timestampToday + $event['start'];
$event['stopUTC'] = $timestampToday + $event['stop'];
$event['start12'] = date("h:i:s a",$event['startUTC']);
$event['start24'] = date("H:i:s",$event['startUTC']);
// other calculations, ordering, etc.
// then pass to smarty
$xoopsTpl->assign('config',$config);
$xoopsTpl->assign('event',$event);

<{if $config.timetype == 1}><{$event.start12}><{else}><{$event.start24}><{/if}>

But I then also have the UTC timestamps that could be used in a local display via jscript, and such as well. For that, too, passing the timezone offset of the server as a config variable would help, too. I did that for the backend/xml/rss code I threw at you via email.