← Back to branch summary

~jstys-z/helioviewer.org/webApp

« back to all changes in this revision

Viewing changes to api/src/Module/JHelioviewer.php

  • Committer: Jeff Stys
  • Date: 2014-03-27 14:58:12 UTC
  • Revision ID: jstys@sesda3.com-20140327145812-w6zfy2rd8nrexvm6
Overhaul of API Documentation, Sidebar Toggle, Movie Player Dialog updates, Bug Fixes.

Overhaul of API documentation:
+  API documentation now lives at its own URL:  api/docs/v1/
+  API documentation has been separated from the API execution code to prevent documentation changes from interrupting live API requests.
+  API descriptions have been movied to verion-specific XML file(s), freeing it from the shackles of HTML and CSS markup.
+  Invalid API requests now display the documentation for the requested API action on the error page.

Hiding of News/Video sidebar
+ Added an icon button to the bottom of the Viewport to toggle the right-hand sidebar.
+ Modified the behavior of the fullscreen toggle to be compatible with the show/hide sidebar feature.
+ Added a keyboard shortcut, 's' to toggle the sidebar.

Miscellaneous Changes:
+  HV_API_URL is now used to prevent occassionaly problematic relative URLs.
+  For compatability reasons, an unexpected API parameter no longer results in an Exception.  Instead, such parameters are explicitely unset.
+  Minor cosmetic changes to the movie player dialog.
+  Replaced AddThis with standard Twitter and Facebook buttons.
+  Added footer link to Helioviewer twitter account.

Bug Fixes:
+  Fixed a bug with the database query in getMovieInformation() that was preventing the LEFT JOIN from properly returning a result when the joined table (movieFormats) did not have any associated rows.  A problem with the WHERE clause was eliminating the benefits of the LEFT JOIN.
+  Fixed a variable name typo associated with the mount wilson class event labels of NOAA SWPC Observer active regions.
+  Fixed a bug that was causing embedded Wordpress widgets to make an external API request to the HEK HER API when it wasn't necessary.

Apache Configuration Changes:
+  Need to add mod_rewrite rule to support version-specific API URIs (in use now by the API documentation).
      RewriteRule ^/api/(v[0-9\.]+)/([0-9a-zA-Z]*)/  /api/index.php?action=$2  [QSA,L]

Show diffs side-by-side

added added

removed removed

Lines of Context:
api/src/Module/JHelioviewer.php
438
438
 
439
439
        return true;
440
440
    }
441
 
 
442
 
    /**
443
 
     * Print the JHelioviewer module's documentation header
444
 
     *
445
 
     * @return void
446
 
     */
447
 
    public static function printDocHeader() {
448
 
?>
449
 
            <li>
450
 
                <a href="index.php#JPEG2000API">JPEG 2000</a>
451
 
                <ul>
452
 
                    <li><a href="index.php#getJP2Image">Retrieving a JPEG 2000 Image</a></li>
453
 
                    <li><a href="index.php#getJPX">Creating a JPX Movie</a></li>
454
 
                </ul>
455
 
            </li>
456
 
<?php
457
 
    }
458
 
 
459
 
    /**
460
 
     * Print JHelioviewer module documentation
461
 
     *
462
 
     * @return void
463
 
     */
464
 
    public static function printDoc() {
465
 
?>
466
 
        <!-- JPEG 2000 API -->
467
 
        <div id="JPEG2000API">
468
 
            <h1>JPEG 2000 API:</h1>
469
 
            <p>Helioviewer's JPEG 2000 API's enable access to the raw JPEG
470
 
            2000 images used to generate the tiles seen on the site, as well
471
 
            as real-time generation of JPEG 2000 Image Series (JPX).</p>
472
 
            <ol style="list-style-type: upper-latin;">
473
 
                <!-- JPEG 2000 Image API -->
474
 
                <li>
475
 
                <div id="getJP2Image">JP2 Images:
476
 
                <p>Returns a single JPEG 2000 (JP2) image. If an image is not
477
 
                available for the date request the closest available image is
478
 
                returned.</p>
479
 
 
480
 
                <br />
481
 
 
482
 
                <div class="summary-box"><span
483
 
                    style="text-decoration: underline;">Usage:</span><br />
484
 
                <br />
485
 
 
486
 
                <?php echo HV_API_ROOT_URL; ?>?action=getJP2Image<br />
487
 
                <br />
488
 
 
489
 
                Supported Parameters:<br />
490
 
                <br />
491
 
 
492
 
                <table class="param-list" cellspacing="10">
493
 
                    <tbody valign="top">
494
 
                        <tr>
495
 
                            <td width="25%"><b>observatory</b></td>
496
 
                            <td width="35%"><i>String</i></td>
497
 
                            <td>Observatory</td>
498
 
                        </tr>
499
 
                        <tr>
500
 
                            <td><b>instrument</b></td>
501
 
                            <td><i>String</i></td>
502
 
                            <td>Instrument</td>
503
 
                        </tr>
504
 
                        <tr>
505
 
                            <td><b>detector</b></td>
506
 
                            <td><i>String</i></td>
507
 
                            <td>Detector</td>
508
 
                        </tr>
509
 
                        <tr>
510
 
                            <td><b>measurement</b></td>
511
 
                            <td><i>String</i></td>
512
 
                            <td>Measurement</td>
513
 
                        </tr>
514
 
                        <tr>
515
 
                            <td><b>date</b></td>
516
 
                            <td><i>ISO 8601 UTC Date</i></td>
517
 
                            <td>Observation date and time</td>
518
 
                        </tr>
519
 
                        <tr>
520
 
                            <td><b>sourceId</b></td>
521
 
                            <td><i>Integer</i></td>
522
 
                            <td><i>[Optional]</i> The image source ID (can be
523
 
                            used in place of observatory, instrument, detector
524
 
                            and measurement parameters).</td>
525
 
                        </tr>
526
 
                        <tr>
527
 
                            <td><b>jpip</b></td>
528
 
                            <td><i>Boolean</i></td>
529
 
                            <td><i>[Optional]</i> Returns a JPIP URI instead
530
 
                            of an actual image.</td>
531
 
                        </tr>
532
 
                    </tbody>
533
 
                </table>
534
 
 
535
 
                <br />
536
 
 
537
 
                <span class="example-header">Examples:</span>
538
 
                <span class="example-url">
539
 
                <a href="<?php echo HV_API_ROOT_URL; ?>?action=getJP2Image&amp;observatory=SOHO&amp;instrument=EIT&amp;detector=EIT&amp;measurement=171&amp;date=2003-10-05T00:00:00Z">
540
 
                <?php echo HV_API_ROOT_URL; ?>?action=getJP2Image&observatory=SOHO&instrument=EIT&detector=EIT&measurement=171&date=2003-10-05T00:00:00Z
541
 
                </a>
542
 
                </span><br />
543
 
                <span class="example-url">
544
 
                <a href="<?php echo HV_API_ROOT_URL; ?>?action=getJP2Image&amp;observatory=SOHO&amp;instrument=LASCO&amp;detector=C2&amp;measurement=white-light&amp;date=2003-10-05T00:00:00Z&amp;jpip=true">
545
 
                <?php echo HV_API_ROOT_URL; ?>?action=getJP2Image&observatory=SOHO&instrument=LASCO&detector=C2&measurement=white-light&date=2003-10-05T00:00:00Z&jpip=true
546
 
                </a>
547
 
                </span>
548
 
                </div>
549
 
                </div>
550
 
                </li>
551
 
 
552
 
                <br />
553
 
 
554
 
                <!-- JPX API -->
555
 
                <li>
556
 
                <div id="getJPX">JPX API
557
 
                <p>Returns a JPEG 2000 Image Series (JPX) file. The movie
558
 
                frames are chosen by matching the closest image available at
559
 
                each step within the specified range of dates.</p>
560
 
 
561
 
                <br />
562
 
 
563
 
                <div class="summary-box"><span style="text-decoration: underline;">Usage:</span><br />
564
 
 
565
 
                <br />
566
 
 
567
 
                <?php echo HV_API_ROOT_URL; ?>?action=getJPX<br />
568
 
                <br />
569
 
 
570
 
                Supported Parameters:<br />
571
 
                <br />
572
 
 
573
 
                <table class="param-list" cellspacing="10">
574
 
                    <tbody valign="top">
575
 
                        <tr>
576
 
                            <td width="20%"><b>observatory</b></td>
577
 
                            <td width="20%"><i>String</i></td>
578
 
                            <td>Observatory</td>
579
 
                        </tr>
580
 
                        <tr>
581
 
                            <td><b>instrument</b></td>
582
 
                            <td><i>String</i></td>
583
 
                            <td>Instrument</td>
584
 
                        </tr>
585
 
                        <tr>
586
 
                            <td><b>detector</b></td>
587
 
                            <td><i>String</i></td>
588
 
                            <td>Detector</td>
589
 
                        </tr>
590
 
                        <tr>
591
 
                            <td><b>measurement</b></td>
592
 
                            <td><i>String</i></td>
593
 
                            <td>Measurement</td>
594
 
                        </tr>
595
 
                        <tr>
596
 
                            <td><b>startTime</b></td>
597
 
                            <td><i>ISO 8601 UTC Date</i></td>
598
 
                            <td>Movie start time</td>
599
 
                        </tr>
600
 
                        <tr>
601
 
                            <td><b>endTime</b></td>
602
 
                            <td><i>ISO 8601 UTC Date</i></td>
603
 
                            <td>Movie end time</td>
604
 
                        </tr>
605
 
                        <tr>
606
 
                            <td><b>cadence</b></td>
607
 
                            <td><i>Integer</i></td>
608
 
                            <td><i>[Optional]</i> The desired amount of time
609
 
                            between each movie-frame, in seconds. If no
610
 
                            cadence is specified, the server will attempt to
611
 
                            select an optimal cadence.</td>
612
 
                        </tr>
613
 
                        <tr>
614
 
                            <td><b>sourceId</b></td>
615
 
                            <td><i>Integer</i></td>
616
 
                            <td><i>[Optional]</i> The image source ID (can be
617
 
                            used in place of observatory, instrument, detector
618
 
                            and measurement parameters).</td>
619
 
                        </tr>
620
 
                        <tr>
621
 
                            <td><b>verbose</b></td>
622
 
                            <td><i>Boolean</i></td>
623
 
                            <td><i>[Optional]</i> In addition to the JPX file
624
 
                            URI, timestamps for each frame in the resulting
625
 
                            movie and any warning messages generated are
626
 
                            included in a JSON response.</td>
627
 
                        </tr>
628
 
                        <tr>
629
 
                            <td><b>jpip</b></td>
630
 
                            <td><i>Boolean</i></td>
631
 
                            <td><i>[Optional]</i> Returns a JPIP URI instead
632
 
                            of an actual movie.</td>
633
 
                        </tr>
634
 
                        <tr>
635
 
                            <td><b>linked</b></td>
636
 
                            <td><i>Boolean</i></td>
637
 
                            <td><i>[Optional]</i> Returns a linked JPX file
638
 
                            containing image pointers instead of data for each
639
 
                            individual frame in the series. Currently, only
640
 
                            JPX image series support this feature.</td>
641
 
                        </tr>
642
 
                    </tbody>
643
 
                </table>
644
 
 
645
 
                <br />
646
 
                Result:<br />
647
 
                <br />
648
 
                The default action is to simply return the requested JPX file.
649
 
                If additional information is needed, for example, then a JSON
650
 
                result will be returned with the file URI plus any additional
651
 
                parameters requested.
652
 
                <br /><br />
653
 
 
654
 
                <!-- Return parameter description -->
655
 
                <table class="param-list" cellspacing="10">
656
 
                    <tbody valign="top">
657
 
                        <tr>
658
 
                            <td width="20%"><b>uri</b></td>
659
 
                            <td width="20%"><i>String</i></td>
660
 
                            <td><i>[Optional]</i> Location of the requested
661
 
                            file.</td>
662
 
                        </tr>
663
 
                        <tr>
664
 
                            <td><b>frames</b></td>
665
 
                            <td><i>List</i></td>
666
 
                            <td><i>[Optional]</i> List of timestamps.</td>
667
 
                        </tr>
668
 
                        <tr>
669
 
                            <td><b>error</b></td>
670
 
                            <td><i>String</i></td>
671
 
                            <td><i>[Optional]</i> Any fatal error messages
672
 
                            generated during the request</td>
673
 
                        </tr>
674
 
                        <tr>
675
 
                            <td><b>warning</b></td>
676
 
                            <td><i>String</i></td>
677
 
                            <td><i>[Optional]</i> Any non-fatal warning
678
 
                            messages generated during the request</td>
679
 
                        </tr>
680
 
                    </tbody>
681
 
                </table>
682
 
 
683
 
                <br />
684
 
 
685
 
                <span class="example-header">Examples:</span>
686
 
                <span class="example-url">
687
 
                <a href="<?php echo HV_API_ROOT_URL; ?>?action=getJPX&amp;observatory=SOHO&amp;instrument=EIT&amp;detector=EIT&amp;measurement=171&amp;startTime=2003-10-05T00:00:00Z&amp;endTime=2003-10-20T00:00:00Z">
688
 
                    <?php echo HV_API_ROOT_URL; ?>?action=getJPX&observatory=SOHO&instrument=EIT&detector=EIT&measurement=171&startTime=2003-10-05T00:00:00Z&endTime=2003-10-20T00:00:00Z
689
 
                </a>
690
 
                </span><br />
691
 
                <span class="example-url">
692
 
                <a href="<?php HV_API_ROOT_URL; ?>?action=getJPX&amp;observatory=SOHO&amp;instrument=MDI&amp;detector=MDI&amp;measurement=magnetogram&amp;startTime=2003-10-05T00:00:00Z&amp;endTime=2003-10-20T00:00:00Z&amp;cadence=3600&amp;linked=true&amp;jpip=true">
693
 
                    <?php echo HV_API_ROOT_URL; ?>?action=getJPX&observatory=SOHO&instrument=MDI&detector=MDI&measurement=magnetogram&startTime=2003-10-05T00:00:00Z&endTime=2003-10-20T00:00:00Z&cadence=3600&linked=true&jpip=true
694
 
                </a>
695
 
                </span></div>
696
 
                </div>
697
 
 
698
 
                <br />
699
 
 
700
 
                <!-- getJPX API Notes -->
701
 
                <div class="summary-box" style="background-color: #E3EFFF;">
702
 
                <span style="text-decoration: underline;">Notes:</span>
703
 
 
704
 
                <br /><br />
705
 
 
706
 
                <ul>
707
 
                    <li>
708
 
                    <p>If no cadence is specified Helioviewer.org attempts to
709
 
                    choose an optimal cadence for the requested range and data
710
 
                    source.</p>
711
 
                    </li>
712
 
                </ul>
713
 
                </div>
714
 
 
715
 
                <br />
716
 
<?php
717
 
    }
718
441
}
719
442
?>
 
 
b'\\ No newline at end of file'