quasicms/doc/DesignNotes

%
snapshot: Thu Jul 30 2008
As of this snapshot, Quasi is still in a very early stage - this release is functional in some basic
facilities and totally unfinished in others, it is provided mostly as a preview and to give
those who are curious a look at the general architecture.

 That said, you can make a website with it - but if you don't know what you are doing, don't. There
has been very little attention given to security issues and although it may be fine there is no
guarantee that it isn't full of holes. It is also likely to be a bit buggy. However, Quasi is designed
first to be a developer's system; I have put quite a lot of effort into attempting to design a framework
that is easy to work with, extensible and robust. It is also based on a toolkit (QCodo) that supports
very rapid application development so if you are a web developer you may find it quite useful even
as it is now.

 Customization that you want to have independant from the core release can be done in a directory
called "local/" in the same directory as "core/" -  it should mirror the structure of "core/"; Quasi will
look there for stylesheets. assets, modules and the autoloader will look there for classes in files
named with the convention <classname>.class.php. Stylesheets will cascade from core through
contrib to local, class will be loaded in reverse falling back on core.

 Code generation happens in "generated/", ORM subclasses are in [core|contrib|local]/orm and
metacontrols in  [core|contrib|local]/meta_controls. The subclasses will be created if they do not
exist but not overwritten, generated classes WILL be overwritten during generation. You can
add to the database and code-generate and move your local subclasses to "local/orm" and Quasi
will find them as needed. The base classes will always be under generated/[orm|meta_controls].

 Panel and form drafts also go under generated/ - and generated/panels contains a mildy altered
index page that serves as "admin/" until Quasi gets a "real" administrative UI. You can put a symlink
in the root directory for convenience or surf to <quasiroot>/generated/panels/ to use the admin UI.

 There are a couple of changes to QCodo's default set up that are needed to get things running - they
are minor and detailed in the README.txt.

 If you are interested in helping, find quasicms at sourceforge.net and have a look around - there are
and will be many things to do and many ways to help. Bug reports are welcome.

 Have fun!
--erik
 
%

 The following is a casual treatment of some parts of the Quasi architecture - it is both unfinished and
incomplete. Much more information is available in the comments of the classes in the CMS
engine and the various modules and of course, if you really want to learn about it, "Read the source, Luke..".

<CMS Engine>
 Briefly, the engine runs off a single controller script: index.php and its template. This is an
instance of class IndexPage which extends QForm. All requests are processed by this form.

  The form inspects the Request URL and determines the Page name from the first part after
the script name. It then loads a corresponding Page object and passes it to a new PageView.
The PageView knows already which general blocks (divs) are active and it loads all ContentBlocks
associated with the basic default areas, creating new ContentBlockViews for each and rendering
them in order in the template. ContentBlocks go on to do the same for ContentItemViews,
MenuViews (which in turn load MenuItems) and Modules.

  The difference between a ContentItem (or Menu/MenuItem) and a Module is that a Module
is active - that is, it does more than passively present data from the database. Any display
that requires processing to display or recieves input that calls functions is a Module. These
are created by writing a module class and placing in the modules subdirectory - it must be
named following the convention of the other modules in this directory. Then enter it in the
database with the class name and assign it to a ContentBlock - both things done through
the admin interface. You can then go on to have the Module class include other classes,
perform actions, create new panels, dialogs, input, etc. as desired. The final action is to
ensure that the new module is required() at the top of the IndexPage. The engine will load
it into the associated content block.

  ContentItems and Menus are similar without the writing of a class - one simply creates a
new item or menu in the admin interface and enters the desired content. Content may
contain HTML, a WYSIWYG editor is planned. After saving the content or menu, it is
assigned to a ContentBlock. Easy, huh? ;)

  Menu items are the same process but they are assigned to a Menu.

  ContentBlocks are assigned to a page and given a location on the Page: Header, RightPanel
CenterPanel, LeftPanel or Footer - or one of the ExtraDivs. This is the default, however, it
is trivial to change this by editting PageView and its template and entering other names
in the block_location_type table in the database - there is no interface for this as yet (and
remember to run the code generator after this!).

  The administration interface is, er, basic at the moment - it lives in drafts/dashboard; those
of you familiar with QCodo will know what it consists of which is the generated access to
the ORM objects from the database schema. Much of the logic of  Quasi is in the database
schema so this is not trivial, but it is as yet an area needing a layer of abstraction to be more
user friendly. For now, you get the "power user" interface ..

</CMS Engine>

What follows are general notes about the architecture of the modules, lists, views and other
misc features in the CMS.

<Account Management>
AccountManagerModule:
  The Account page has a module that parses the PageParameters to determine which Account module
to load. Eg. for Addresses/ it will acivate the AccountAddressesModule. This module in turn contains
an instance of AccountAddressEditPanel and AccountAddressListPanel which it will manage. For a
parameter like Addresses/2 it will go directly to the edit panel for that address but signalling the sub
module. By default, the sub modules will show a list page if given no parameters. Each sub-module is
a Page request, the actions within each of these are ajax calls.

  The default Account modules managed by the AccountManagerModule are:
    - AccountAddressesModule : addresses  viewing and management
    - AccountOrdersModule : orders viewing and management
    - AccountSettingsModule: contains the following
        - AccountInfoModule : to change email address, avatar or personal name.
        - AccountPasswordModule : change password and username
        - AccountProfileModule : public profile information

    
</Account Management>


 <Ecommerce>
 
    Objects:
        - Order
        - Product
        - Shopping cart
        - Payment method
        - Shipping method 
        
    Actors:
        - Customer
        - Second party payment processor
        - Shipping party
        - Employees
    
    Events:
        - Browse products
            initially this means the user is looking at their designs in the account section
            the designs have an "add to cart" button possibly with a qty field next to it.
            * do we offer this on the line item list or only individual item displays?
        - Select products
            customer triggers an "add to cart" action, parameters are design id and qty
            * if no cart exists, create cart and insert into database. (???) or save as object with session or
               account id ..
            * add items to association table for the cart (shopping_cart_items)
              > if it is a pcb_design, select design from pcb_designs
                - if design.product_id == Null, create a product, set design.product_id;
                  else simply add to association table
        - check out process         
            - Select payment method
            - Select Shipping method
            - Validate payment
            - Record transaction

Architecture:
    Orders, Products, Customers. etc. are all ORM objects and the data is managed in the
    database. These are dealt with in other parts of the documentation.

    There are two main parts of the interactive part of the ecommerce extension: the shopping cart and the
checkout process. The third part is passive display of products in lists or individually, ie. browsing.

        ************************
    Shopping cart: (Module/View)
    The shopping cart is implemented as a module that is similar to the Login Module, it has a small content
block view which is visible if a the viewer is logged in, and a page for viewing and modifying the cart contents.
The contents are displayed in short form in the module and in detail on the ShoppingCart page. The shopping
cart page is configured in the database to have the ShoppingCartView as the primary module in the main block
of the page (usually CenterPanel). The items in the ShoppingCartView and the ShoppingCartMiniView are linked
to product views. The ShoppingCartView is displayed when a user clicks on the "View Cart"
button in the mini view. This is actually implemented as a redirect to the ShoppingCart page where the
ShoppingCartView is the central module.

        ************************
    CheckOut: (Module - to be implemented, similar to Account Manager but with only two panels)
    The checkout process occurs on a page. It contains a central management module: CheckOut. This manages the
Items display, the Address selection, the Payment module and the Shipping module.

    There are two panels involved CheckOutEditModule and CheckOutReviewModule, The first is for displaying
the list of items, shipping and billing addresses and a selection of shipping methods. All of these may be modified
on this panel.

    On completion of selections of address, shipping method, etc, the CheckOutReviewModule is shown  where
one can review the details of the order, select payment option and complete the purchase, or return to modify
the details on the previous panel. These are not actual page loads, but two separate panels connected to the main
Checkout Module which is the central module of the CheckOut page.

    Basic Logic:
        CheckOut module loads:
            * CheckOutEditModule - panel for stage 1, containing item list, addresses w/editting and shipping
              method selection
                This loads:
                    - CheckOutItemListModule - modifiable list of items
                    - AddressViews - shipping and billing, with button to edit each. clicking the edit button hides
                        the main panel and shows an AddressEditPanel
                    - Radiolist for shipping options

            * CheckOutReviewModule - panel for stage 2, display of item list, totals, addresses, and selected
              shipping method followed by payment method selection at the bottom and a "Finish" button.
                This loads:
                    - passive display of items, totals, addresses and shipping method selected
                    - PaymentModule
                        gets a list of methods, creates PaymentMethodViews for each with an action
                        associated that will trigger the appropriate PaymentAction ..

            *CheckOutConfirmationModule - merely confirms the order after payment
    
    The Payment and Shipping modules manage the loading and placement of PaymentMethods and
ShippingMethods (respectively). They also serve as the interface to the data obtained my the active or selected
method.

    The ShippingModule gets a list of active modules from the shipping_method table. For each, it gets a
RateCalculator appropriate to the method from a "factory" method in the ShippingMethod class. Then it creates a
radio button for the method and pushes it onto an array of radio buttons that are rendered in the template. Each
button has an action to reset the SelectedMethod property in the ShippingModule.

  The PaymentModule is slightly more complex. PaymentMethod is also an ORM class from the payment_method
table, and it also provides a factory method to return a PaymentAction based on the service provider and the
service type (like ShippingModule). However, rather than rendering these directly (as the requirements for each
differ), PaymentModule creates  a PaymentAction for each method. This will be a subclass of
PaymentActionBase for the method, eg AuthorizeNetAction, or PayPalIPNAction.  The PaymentAction
is also subclassed for the provider and service in a similar way and the naming convention is the same.

 PaymentModule - controller block view

    creates:
                
        PaymentMethod - ORM model

        creates:
            PaymentAction - collect information and/or connect to provider to perform actual transaction
             |_
             |  \PayPalWPSAction 
             |_
             |  \AuthorizeNetAction
             |_
                 \etc ..
                 

Basic Workflow:

    1. In PaymentModule
        1.1 a list of active PaymentMethods is obtained from the database
        1.2 an array of QRadioButtons is created, each has the PaymentMethod->Id as an action parameter
        1.3 fields for credit card input are created. These are rendered below the payment options
        1.4. PaymentAction for the method is created by PaymentModule::btn_Purchase_Click
               when the user clicks "Purchase" based on the class_name field in payment_methods
                - PaymentAction initilizes some defaults and other values are set according to the
                  method's requirements - this is configuration data and the PaymentAction is responsible
                  for knowing what to set.
                - PaymentAction->PreProcess is called
                - PaymentAction->Process is called
                - PaymentAction->PostProcess is called

PaymentActions:
    PayPal Express Checkout
     This is non-standard due to the requirements from PayPal - the PaymentActionView offers this as an option on the
     review panel which will set the method and there is a "Check Out with PayPal" button at the bottom of the Edit
     panel as well. Clicking the button will set the selected payment method _and_ trigger the PaymentAction while
     selecting the option will only set the payment method, leaving the action to be triggered by the "Pay" button on
     the review Panel.

        ************************
    Browsing Products:
    Product Display (ListModule)
    ProductDisplayModule extends the ListModuleBase in the same manner as the Account address module - it
manages an ajax controlled set of panels for showing a list of products or a single product. The module
parses the page parameters (derived from the URL, see the notes above for the Account manager module),

        ************************
     Order history:
    Order viewing is handled as a ListModule in the Account Manager module - see  the Address manager module
above and Product display.
 
    =========================================
 </Ecommerce>
        
 <Lost Password>
  The LostPasswordModule is displayed on the Page "LostPassword", it performs the following actions:
    1. Prompts the user for either username or email associated with the account.
    2. Generates a new random password for the account
        The user must input either the email for the account or the username
    3. Sets the temporary password in the account and sets the flag onetime_password to true.
    4. Emails the password to the user

  The user can then use this to log in - the LoginModule checks the onetime_password flag; if set it will redirect the
  user to the account password settings module. The following are the possible state changes:
     
    on signup
        set onetime_password = false
        set valid_password = true.

    on lost password module resets password,
        set onetime_password = true
        set valid_password = true

    on login
         if  valid_password == false
         then
            show error page with link to "forgot password"
         if onetime_password == true
         then
            redirect to AccountHome/Settings/Password
            set valid_password = false
            
    on user resets password,
        set onetime_password = false
        set valid_password = true

 
 </Lost Password>