First steps

From CMC for PHP
Jump to: navigation, search

The following will explain typical first steps when you setup a new application.

Extract the framework

Fastest way is to extract a sample or the skeleton.

Then it can be used with the compressed or debug version of the framework.

Edit the php\config.php file at least to define:

  • the material path (root or a subdirectory). A subdirectory is preferred as it makes a closure for the material part of your project. When a subdirectory is used, the framework automatically will update the internal links to keep them appropriate from the root.

(a /js/link.js will be changed to /material/js/link.js for example)

  • the database connection parameters if you intend to use
  • the name of the default view name (typically index; which will refer to <material path>/index.html)

Integrate existing material

Just copy the material files (html, javascript, images, ...) into the material directory you decided to work with.

Then we progressively will be able to make some pages dynamic. The material directory will be testable without the framework as a 'default' display.

Implement frames for the view

If the frame is static result, derive from cmc\ui\frame; if this is dynamic result, use cmc\ui\dynframe instead.

Reminder: a frame can be bound to a part of the view. However a view is functional without any implemented frames: it will just act as html content. A frame also can implement different views; the widget information will be linked to each view (at session and/or application level)

Bind frame to view

Change the view (the .html file), by defining an identified section like follows:
<anytag data-cmc-id="myframe">
Use that ID in the frame's implementation:
static public function getId() { return 'myframe';}

Implement frame

After this, this part of the view will be handled by the frame, but we have no way to know this is working, has the result is just the same display.


Simple label widget

We need to add now some dynamic items. Let's just add some dynamic span item:

  • Add/modify a tag in our view's section:
<span id="testspan">default span value</span>
  • Add our widget in the frame's widgets
    protected $_widgetdef = array(
...
        'TestSpan' => array(label::factory, 'testspan'),
    );
  • Add some code in our frame:
 public function viewStaticUpdate($view) {
  $this->w('TestSpan')->setHtml('<b>test update...</b>');
 }

Tip when developing: each time the view is modified, the result will be refreshed (cache auto expiration), but not when the php code (in frame or other) is changed. So, best is to 'touch' the view at the same time to see our changes (or clear the whole cache directory to be sure).

Add input fields and button

The basics follows the same principle

  • On the view source, standard HTML items (here a login area):
            <fieldset> 
                <p>Please enter email and password:<br/> 
                    <span> <label>Email:</label> </span>
                        <input type="text" id="s_userid" value=""/><br/> 
                        <span> <label>Password:</label> <input type="password" id="s_password" value=""/> </span><br/> 
                        <input id="login" type="submit" value="Login"/>
                        <span class="text highlight" id="errortext">Error in application. Please contact Technical support...</span> 
                </p> 
            </fieldset>
  • Possible code in the frame:
    protected $_widgetdef = array(
        'bt_login' => array(button::factory, 'login'),
        'in_login' => array(input::factory, 's_userid'),
        'in_passwd' => array(input::factory, 's_password'),
        'errortext' => array(label::factory, 'errortext'),
    );

    public function viewUpdate($view, $sess) {
            $this->w('in_passwd')->setValue('');
            $sess->clearLogin();
            $this->w('errortext')->setCaption('');           
            $this->AddClickEvent('bt_login', array($this, 'btLoginClick'));
    }

    public function checkLogin($view) {
        // get login values
        $user = $this->w('in_login')->getValue();
        $pass = $this->w('in_passwd')->getValue();
        // pass it to our login check function 
        if (!$this->getSession()->checkLogin($user, $pass)) {
            $text = "Incorrect login !";
        } else {
            $text = 'Welcome, ' . $this->getSession()->getLoginName();
            // OK, go to application view            
            $view->setRedirect('/admin/mainAdmin', false);
        }
        // updates status label
        $this->w('errortext')->setCaption($text);     
    }

    // click on login button
    public function btLoginClick($view) {
        $this->checkLogin($view);
    }

Here we see how to bind an 'event' form the button, by the 'AddClickEvent' method. There are several possible solutions for server-side event handling.


Add the frame to the application

When your implementation is ready, you need to include the class in the frame implementation list returned by the application.

require_once 'myframes/mynewframe.php';
[...]
class myApp extends app {
    private $_frameclasses = array(
        myNewFrameClass::className
    );
[...]
    protected function getFrameClasses() {
        return array_merge(parent::getFrameClasses(), $this->_frameclasses);
    }

Note: you can return a fresh frames list, or use the default frame implementation of the framework (recommended: a 'master' frame implementation fixes internal links, handles multilanguage fetures, etc. of all views of the application).

The framework is using classnames in order to instantiate the frame classes on need.

If the frame is not bound tho the view, you will see the original view contents instead. Here is the checklist to solve the issue:

  • ID in the view must cover the corresponding area, using data-cmc-id on view site, and GetId() on frame implementation
  • the frame must be referenced in the application
  • the frame must implement either 'viewStaticUpdate', 'viewInitialUpdate' or 'viewUpdate'
  • if the frame is static, the cache must be cleared or the view source altered after php changes.

Go further

http://cmc.calmarsoft.com/cmcphp/doc/Skeleton_project