Developers Documentation

×

Warning

301 error for file:https://clearos.com/dokuwiki2/lib/exe/css.php?t=dokuwiki&tseed=82873f9c9a1f5784b951644363f20ef8

User Tools

Site Tools


Table of Contents

Old Framework

The following is a brief overview of the old ClearOS 5.x framework. For the documentation on the new framework, go to here.

MVC

This documentation is here for historical purposes only!

Like many software applications built today, the ClearOS 5.1 framework is built using the Model-View-Controller (MVC) design pattern.

  • The API is the Model
  • The webconfig pages are built with a View and Controller

Stepping through a simple example is a good way to get to know the current system.

Model

The software API is a simple concept. If you want to change the configuration or behavior of application X, then the software developer has to go through the specific API provided for application X. For example, the Time class provides an API to manage time on the system. The methods include:

  • GetTime()
  • GetTimeZone()
  • GetTimeZoneList()
  • IsValidTimeZone(timezone)
  • SendSystemToHardware()
  • SetTimeZone(timezone)

You can actually play around with this API on the command line. The api command is used for testing and just playing around on a system. To show a list of available methods:

api Time 

To run a method:

api Time GetTimeZone 

As a whole, the API does not use pass-by-reference and most of the methods are stateless. This design makes it possible to access the API over the network using technologies like REST or SOAP.

Here is the time class source code if you are interested.

View

In ClearOS 5.x, the View and Controller are certainly functional, but lack some nice features provided by modern web application frameworks:

  • Native Ajax support
  • Flexible layout control
  • Leaner code
  • Sanitization

Here is what the date configuration page (the View) looks like in ClearOS 5.1.

https://clearos.com/dokuwiki2/lib/exe/fetch.php?media=omedia:date.png

And the associated source code for this webconfig page is below. As you can see, it's basically standard HTML with some WebXyz function calls. These function calls allow a template designer to control the look and feel. For example, the WebButtonUpdate can be a standard and plain looking web button, or themed using something like Yahoo UI toolkit or the JqueryUI toolkit. By creating this simple function, we have left this design decision up to the theme developer.

    $buttonopts['onclick'] = 'setNtpTime()';
    $buttonopts['type'] = 'button';
 
    WebFormOpen();
    WebTableOpen(WEB_LANG_TIME_CONFIG_TITLE, "100%");
 
    echo "
        <tr>
            <td width='200' class='mytablesubheader' nowrap>" . TIME_LANG_DATE . " / " . TIME_LANG_TIME . "</td>
            <td nowrap>$thedate $thetime</td>
        </tr>
        <tr>
            <td class='mytablesubheader' nowrap>" . TIME_LANG_TIMEZONE . "</td>
            <td nowrap><select name='timezone'>$timezone_select</select></td>
        </tr>
        <tr>
            <td width='200' class='mytablesubheader' nowrap>" . NTPD_LANG_NTP_TIME_SERVER . "</td>
            <td>" . WebDropDownEnabledDisabled("autosync", $ntp_state) . "</td>
        </tr>
        <tr>
            <td class='mytablesubheader'>&nbsp; </td>
            <td>" . 
                WebButtonUpdate("SetTime") . 
                WebButton("onclick", WEB_LANG_AUTOSYNC_NOW, WEBCONFIG_ICON_UPDATE, $buttonopts) . "&nbsp; 
                <span id='result'></span>
            </td>
        </tr>
    ";
 
    WebTableClose("100%");
    WebFormClose();

One important item to point out here – you can see an example of some kludging creeping into the current framework. The “onclick” and “buttonopts” parameters were afterthoughts. These parameters were required to add some Ajax support to the form, but the original framework did not support these options from day one. Instead, an interim workaround was added and it's an example of how things started to get a bit messy.

To populate this date web form, standard calls to the API are performed. Here's the source code to do just that:

    try {
        $timezones = $ntptime->GetTimeZoneList();
        $timezone = $ntptime->GetTimeZone();
        $ntp_state = $ntpd->GetRunningState();
        date_default_timezone_set($timezone);
    } catch (TimezoneNotSetException $e) {
        // Not the end of the world
    } catch (Exception $e) {
        WebDialogWarning($e->GetMessage());
    }
 
    ... snip ...

That's about it for the View. We have a simple web form with some custom ClearOS 5.x template hooks along with standard looking calls to the underlying software API. Now we can take a look at the Controller.

Controller

The Controller basically reads in form data and takes some kind of action using the API. For the date page in webconfig, the controller looks like the following:

$ntptime = new NtpTime();
$ntpd = new Ntpd();
 
try {
    if (isset($_POST['SetTime'])) {
        $ntptime->SetTimeZone($_POST['timezone']);
 
        if ($_POST['autosync']) {
            $ntptime->DeleteAutoSync();
            $ntpd->SetRunningState(true);
            $ntpd->SetBootState(true);
        } else {
            $ntptime->SetAutoSync();
            $ntpd->SetRunningState(false);
            $ntpd->SetBootState(false);
        }
    }
} catch (Exception $e) {
    WebDialogWarning($e->GetMessage());
}
content/en_us/dev_framework_old_framework.txt · Last modified: 2015/09/17 15:19 (external edit)

https://clearos.com/dokuwiki2/lib/exe/indexer.php?id=content%3Aen_us%3Adev_framework_old_framework&1710836885