-
229 |
230 |
98 | CorMVC is a jQuery-powered Model-View-Controller (MVC) framework that 99 | can aide in the development of single-page jQuery applications. It evolved out of 100 | my recent presentation, 101 | Building Single-Page Applications Using jQuery And ColdFusion, 102 | and will continue to evolve as I think more deeply about this type of application 103 | architecture. 104 |
105 | 106 |107 | CorMVC stands for: 108 | Client-Only-Required 109 | Model-View-Controller, 110 | and is my laboratory experiment in application architecture held completely 111 | seperate from server-side technologies. 112 |
113 | 114 |119 | Building frameworks in jQuery (or any other language for that matter) is 120 | very new to me; I don't claim to be any good at it. In fact, when I started 121 | looking into jQuery-based frameworks, I had no intention of creating my own. 122 | As I started to do my research, however, I quickly encountered two major problems 123 | with what was avilable: 124 |
125 | 126 |138 | I didn't even know how to begin learning. So, rather than wade through what was 139 | available, I decided to try and create something from scratch. What I came up with 140 | is corMVC. The philosophies that I put into the corMVC framework 141 | are those that were hopefully a remedy to the problems I encoutered above: 142 |
143 | 144 |166 | While I want to keep the corMVC framework as small as possible, I am sure that as I begin 167 | to more fully understand the various needs of single-page applications, the framework 168 | will have to evolve as necessary. In the end though, I want the corMVC framework to be 169 | an aide and not a constraint- affording the programmer the freedom to pile their 170 | own jQuery magic on top of this foundation. 171 |
172 | 173 |178 | When dealing with Javascript and "progressive enhancement enthusiast," someone always asks 179 | how this should work / degrade if the end user does not have Javascript enabled. 180 | While this might be a contentious answer, if your target user does not have Javascript 181 | enabled, then I don't think they should be using a single-page application. That's like 182 | asking how a user should navigate a FLEX application if they don't have Flash installed; 183 | it doesn't make sense. I'm not talking about building "pamphlet" sites here - 184 | I'm talking about building complex, user-experience-oriented applications. 185 |
186 | 187 | 188 |207 | The contacts section is meant to demonstrate more complex interactions that 208 | involve the application's service layer (part of the Model) and potentially 209 | (thought not required in this demo) communication with the server. 210 |
211 | 212 | 213 |289 | Please fill out the contact information below. 290 |
291 | 292 | 339 | 340 | 341 |360 | This is the documentation page. 361 |
362 | 363 |364 | Coming soon.... 365 |
366 | 367 | 368 |380 | This is the resources page. 381 |
382 | 383 |384 | Coming soon.... 385 |
386 | 387 | 388 |400 | Sorry, but the page you requested could not be found. 401 |
402 | 403 |404 | Try going back to the home page. 405 |
406 | 407 | 408 |" + value.toString() + "
" ); 343 | } 344 | ); 345 | 346 | } 347 | }; 348 | 349 | 350 | // I normalize a hash value for comparison. 351 | Application.prototype.normalizeHash = function( hash ){ 352 | // Strip off front hash and slashses as well as trailing slash. This will 353 | // convert hash values like "#/section/" into "section". 354 | return( 355 | hash.replace( new RegExp( "^[#/]+|/$", "g" ), "" ) 356 | ); 357 | }; 358 | 359 | 360 | // I normalize a JSON response from an AJAX call. This is because some languages 361 | // (such as ColdFusion) are not case sensitive and do not have proper casing 362 | // on their JSON translations. I will lowercase all keys. 363 | Application.prototype.normalizeJSON = function( object ){ 364 | var self = this; 365 | 366 | // Check to see if this is an object that can be normalized. 367 | if ( 368 | (typeof( object ) == "boolean") || 369 | (typeof( object ) == "string") || 370 | (typeof( object ) == "number") || 371 | $.isFunction( object ) 372 | ){ 373 | 374 | // This is a non-object, just return it's value. 375 | return( object ); 376 | } 377 | 378 | // Check to see if this is an array. 379 | if ($.isArray( object )){ 380 | 381 | // Create an array into which the normalized data will be stored. 382 | var normalizedObject = []; 383 | 384 | // Loop over the array value and moralize it's value. 385 | $.each( 386 | object, 387 | function( index, value ){ 388 | normalizedObject[ index ] = self.normalizeJSON( value ); 389 | } 390 | ); 391 | 392 | } else { 393 | 394 | // Create an object into which the normalized data will be stored. 395 | var normalizedObject = {}; 396 | 397 | // Loop over the object key and moralize it's key and value. 398 | $.each( 399 | object, 400 | function( key, value ){ 401 | normalizedObject[ key.toLowerCase() ] = self.normalizeJSON( value ); 402 | } 403 | ); 404 | 405 | } 406 | 407 | // Return the normalized object. 408 | return( normalizedObject ); 409 | }; 410 | 411 | 412 | // I handle the location changes. 413 | Application.prototype.onLocationChange = function( locationChangeEvent ){ 414 | var self = this; 415 | 416 | // I am used to determine if the application should continue routing the request. 417 | // Depending on the return value of a given event handler, the current routing 418 | // can be cancelled. 419 | var keepRouting = true; 420 | 421 | // I am used to determine if a route was found for the given even. If not, a 422 | // 404 - page not found route will be executed. 423 | var routeFound = false; 424 | 425 | // Turn off monitoring while we route the location. We are doing this 426 | // to allow the application time to process the route without being 427 | // interupted. This will prevent someone clicking rappidly around the 428 | // application from causing unexpected effects. 429 | this.stopLocationMonitor(); 430 | 431 | // Iterate over the route mappings. 432 | $.each( 433 | this.routeMappings, 434 | function( index, mapping ){ 435 | var matches = null; 436 | 437 | // Check to see if routing has been cancelled. 438 | if (!keepRouting){ 439 | return; 440 | } 441 | 442 | // Define the default event context. 443 | var eventContext = { 444 | application: self, 445 | fromLocation: locationChangeEvent.fromLocation, 446 | toLocation: locationChangeEvent.toLocation, 447 | parameters: $.extend( {}, locationChangeEvent.parameters ) 448 | }; 449 | 450 | // Get the matches from the location (if the route mapping does 451 | // not match, this will return null) and check to see if this route 452 | // mapping applies to the current location (if no matches are returned, 453 | // matches array will be null). 454 | if (matches = locationChangeEvent.toLocation.match( mapping.test )){ 455 | 456 | // The route mapping will handle this location change. Now, we 457 | // need to prepare the event context and invoke the route handler. 458 | 459 | // Remove the first array (the entire location match). This is 460 | // irrelevant information. What we want are the captured groups 461 | // which will be in the subsequent indices. 462 | matches.shift(); 463 | 464 | // Map the captured group matches to the ordered parameters defined 465 | // in the route mapping. 466 | $.each( 467 | matches, 468 | function( index, value ){ 469 | eventContext.parameters[ mapping.parameters[ index ] ] = value; 470 | } 471 | ); 472 | 473 | // Check to see if this controller has a pre-handler. 474 | if (mapping.controller.preHandler){ 475 | // Execute the pre-handler. 476 | mapping.controller.preHandler( eventContext ); 477 | } 478 | 479 | // Execute the handler in the context of the controller. Even though the 480 | // event parameteres are getting passed as part of the event context, I 481 | // am going to pass them through as part of the argument collection for 482 | // conveinence in the handler's method signature. 483 | var result = mapping.handler.apply( 484 | mapping.controller, 485 | [ eventContext ].concat( matches ) 486 | ); 487 | 488 | // Check to see if this controller has a post-handler. 489 | if (mapping.controller.postHandler){ 490 | // Execute the post-handler. 491 | mapping.controller.postHandler( eventContext ); 492 | } 493 | 494 | // Check the controller handler's result value to see if we need to stop 495 | // routing. If the controller returns false, we are going to stop routing. 496 | if ( 497 | (typeof( result ) == "boolean") && 498 | !result 499 | ){ 500 | // Cancel routing. 501 | keepRouting = false; 502 | } 503 | 504 | // Flag that a route was found. 505 | routeFound = true; 506 | } 507 | } 508 | ); 509 | 510 | // Turn monitoring back on now that the routing has completed. 511 | this.startLocationMonitor(); 512 | 513 | // Check to see if a route was found. If not, then we need to trigger a 404 event. 514 | if (!routeFound){ 515 | 516 | // Trigger a 404 location. 517 | // NOTE: This will currently break the ability to use the back button on the 518 | // browser (since it will keep trying to relocate to the 404 on back). Will need 519 | // to rethink the way this is handled later. 520 | this.relocateTo( "404" ); 521 | 522 | } 523 | }; 524 | 525 | 526 | // I create a proxy for the callback so that given callback executes in the 527 | // context of the application object, overriding any context provided by the 528 | // calling context. 529 | Application.prototype.proxyCallback = function( callback ){ 530 | var self = this; 531 | 532 | // Return a proxy that will apply the callback in the THIS context. 533 | return( 534 | function(){ 535 | return( callback.apply( self, arguments ) ); 536 | } 537 | ); 538 | } 539 | 540 | 541 | // I relocate the application to the given location. You can also pass through 542 | // a hash of any additional parameters that you wanted added to the location 543 | // event that gets triggers. 544 | Application.prototype.relocateTo = function( newLocation, parameters ){ 545 | this.setLocation( newLocation, parameters ); 546 | }; 547 | 548 | 549 | // I start the application. 550 | Application.prototype.run = function(){ 551 | // Initialize the model. 552 | this.initModels(); 553 | 554 | // Initialize the views. 555 | this.initViews(); 556 | 557 | // Initialize the controllers. 558 | this.initControllers(); 559 | 560 | // Initialize the location monitor. 561 | this.initLocationMonitor(); 562 | 563 | // Turn on location monitor. 564 | this.startLocationMonitor(); 565 | 566 | // Flag that the application is running. 567 | this.isRunning = true; 568 | }; 569 | 570 | 571 | // I set the location of the application. I don't do anything explicitly - 572 | // I let the location monitoring handle this change implicitly. You can also 573 | // pass through additional parameters that will be added to the location event 574 | // that gets triggered. 575 | Application.prototype.setLocation = function( location, parameters ){ 576 | // Clearn the location. 577 | location = this.normalizeHash( location ); 578 | 579 | // Create variables to hold the new and old hashes. 580 | var oldLocation = this.currentLocation; 581 | var newLocation = location; 582 | 583 | // Store the new location. 584 | this.currentLocation = location; 585 | 586 | // Make sure the hash is the same as the location (this way, we don't 587 | // get circular logic as the monitor keeps pinging the hash). 588 | window.location.hash = ("#/" + location ); 589 | 590 | // The location has changed - trigger the change event on the application 591 | // object so that anyone monitoring it can react. 592 | $( this ).trigger({ 593 | type: "locationchange", 594 | fromLocation: oldLocation, 595 | toLocation: newLocation, 596 | parameters: parameters 597 | }); 598 | }; 599 | 600 | 601 | // I turn on the location monitoring. 602 | Application.prototype.startLocationMonitor = function(){ 603 | var self = this; 604 | 605 | // Create the interval function. 606 | this.locationMonitorInterval = setInterval( 607 | function(){ 608 | self.checkLocationForChange(); 609 | }, 610 | this.locationMonitorDelay 611 | ); 612 | }; 613 | 614 | 615 | // I turn off the location monitoring. 616 | Application.prototype.stopLocationMonitor = function(){ 617 | clearInterval( this.locationMonitorInterval ); 618 | }; 619 | 620 | 621 | // ----------------------------------------------------------------------- // 622 | // ----------------------------------------------------------------------- // 623 | 624 | 625 | // I am the prototype for the application controllers. This is so they 626 | // can leverage some binding magic without the overhead of the implimentation. 627 | Application.prototype.Controller = function(){ 628 | // ... 629 | }; 630 | 631 | 632 | // I am the prototype for the Controller prototype. 633 | Application.prototype.Controller.prototype = { 634 | 635 | // I route the given pseudo location to the given controller method. 636 | route: function( path, handler ){ 637 | // Strip of any trailing and leading slashes. 638 | path = application.normalizeHash( path ); 639 | 640 | // We will need to extract the parameters into an array - these will be used 641 | // to create the event object when the location changes get routed. 642 | var parameters = []; 643 | 644 | // Extract the parameters and replace with capturing groups at the same 645 | // time (such that when the pattern is tested, we can map the captured 646 | // groups to the ordered paramters above. 647 | var pattern = path.replace( 648 | new RegExp( "(/):([^/]+)", "gi" ), 649 | function( $0, $1, $2 ){ 650 | // Add the named parameter. 651 | parameters.push( $2 ); 652 | 653 | // Replace with a capturing group. This captured group will be used 654 | // to create a named parameter if this route gets matched. 655 | return( $1 + "([^/]+)" ); 656 | } 657 | ); 658 | 659 | // Now that we have our parameters and our test pattern, we can create our 660 | // route mapping (which will be used by the application to match location 661 | // changes to controllers). 662 | application.routeMappings.push({ 663 | controller: this, 664 | parameters: parameters, 665 | test: new RegExp( ("^" + pattern + "$"), "i" ), 666 | handler : handler 667 | }); 668 | } 669 | 670 | }; 671 | 672 | 673 | // ----------------------------------------------------------------------- // 674 | // ----------------------------------------------------------------------- // 675 | 676 | 677 | // Create a new instance of the application and store it in the window. 678 | window.application = new Application(); 679 | 680 | // When the DOM is ready, run the application. 681 | $(function(){ 682 | window.application.run(); 683 | }); 684 | 685 | // Return a new application instance. 686 | return( window.application ); 687 | 688 | })( jQuery ); 689 | --------------------------------------------------------------------------------