Explaining the concepts of PageCarton

Technicalities

Application Controller - controls how PageCarton behaves

index.php

The index.php controller receives all the requests from the user browser and sends it to the Ayoola_Application class run() method to complete the process.

/core/library/Ayoola/Application.php

This is changing to /core/library/PageCarton.php. This continues to process requests from index.php and serves the right file and output to the user. Determines where there the user is requesting a page, a post or an asset. It also checks to determine the correct site data to load in case of a multisite installation. It serves the request accordingly.

Pages

Computes and output html contents. All pages have URLs of format "/page/url". The homepage has URL "/". A page is usally loaded when a user goes to "http://example.com/page/url". Each page has three files:          

• data.json
  (used to be data.xml or data.php). contains data saved about the page. Only used when page want to be edited. Previous data is retrieved here.        
• include.php
  Contains widgets classes to instantiate and parameters. Loads the init() method of all the widgets embedded on the page. This is loaded first and sends the output to the template file. 
• template.phtml
  Contains a structured copy of the appropriate theme to load the contents of the page. Picks data from include.php and runs the view() method of all the widgets embedded on the page.

Location of these files:

{APPLICATION_PATH}/pages/*

Page-related Widgets, Settings and Database Tables are located on

/core/library/Ayoola/Page/*

Posts

Posts are structured data that can be set to have similar attributes and can be categorized. Examples of posts are articles in a blog settings, products in an e-commerce settings, poll, quiz etc. A number of post are defined in a default PageCarton installation but it also comes with the ability for users to define new post types, new categories and post attributes.

Post-related Widgets, Settings and Database Tables are located on

/core/application/modules/Application/Article/*

Each posts have records saved in the post tables /core/application/modules/Application/Article/Table.php. Post must have a unique "article_url" field that is usually deduced by the "article_title" entered by the user of the format "/2019/01/01/sample-article-title.html".

Site Assets

Site assets are images, CSS, JS, fonts and any kind of asset the site may have. The urls usually is of the form "/path/to/file.ext"
        
Location of these files:

{APPLICATION_PATH}/documents/*

Related Widgets, Settings and Database Tables are located on

/core/library/Ayoola/Doc/*

Widgets

A widget is a unit of a coordinated process in PageCarton. It is a means whereby PageCarton transmits a calculated response to the user. With the "$widget->init()" method, a widget runs the logic of the unit. It uses the "$widget->setViewContent( 'HELLO WORLD' )" method within the init process to send output to the user but the user will not see anything until the "$widget->view()" method is "echoed" to the user.

The widget comes with a number of features and options, for example, a widget can output content in different types depending on the set "play mode" parameter. It courrently can output content in the following formats:

• HTML
• XML
• JSON
• ENCRYPTION
  • using OPENSSL
• PHP serialize()

The ability for widgets to communicate in different output types makes it perfect to build standalone applications that can integrate to third-party systems and front-end frameworks. A widget can "hook" to other widgets to provide related extended functionality for the widget. At specific points in a widget process, the registered hooks for the widget is called and runned, exchanging some vital parameters that could be used to affect the individual widget process.

Widgets allow setting of parameters that are like constants to change the behavior of the widget running in a particular instance. Parameters are usually set whenever a widget is instantiated whether in the page layout editor or in the code of another widget that is instantiating it. In the code, parameters are set with the setParameter method. The set parameters will be available by calling the getParameter method. They also can generate data options that are like variables that can help to show dynamic data in view. The data options are usually set in the init() method.

New widgets are classes extending the PageCarton_Widget class. New widgets can be created from the PageCarton Admin Panel but the file cannot be edited from the web browser.

Related Widgets, Settings and Database Tables are located on

/core/library/Ayoola/Object/*

Read More on Widgets

Databases

Databases are where PageCarton stores structured data. PageCarton comes with an integrated Database system that can be used for almost anything. One can also use any other third-party database. New widgets can be created from the PageCarton Admin Panel but the file cannot be edited from the web browser for security reasons.
Read more on Database Tables

Settings

Settings are special database tables that stores related data for quick retrieval and for in-widget operations. Plugins also can come with their own settings. A settings file can also be created from the PageCarton Admin Panel

Read more on Settings Module

What happens when [needs content]

•     PageCarton is being installed?
•     A user requests a PageCarton site
•     A contributor commits a file
•     User upgrades a pagecarton installation

File structures in PageCarton

Application Directories {APPLICATION_DIR}

Types:

• core
  • /pagecarton/core/*
• default site
  • /pagecarton/sites/default/*
• plugins
  • /pagecarton/sites/*/extensions/{plugin_name}/*
• directory multisites
  • /pagecarton/sites/default/{site_directory}/*
• domain multisites
  • /pagecarton/sites/{domain}/*

Possible contents

• library/
  • only core has this
  • contains all the classes PageCarton really needs for a good run
• local_html/
  • contains files that's automatically copied to the site web root
  • only core has this
  • contains
  • index.php
  • web.config (for IIS)
  • .htaccess (for Apache)      
• application/
  • all application directories can have this
  • referred to as {APPLICATION_PATH}
  • can have the follow directories
    • documents/
    • databases/
    • pages/
    • modules_files/
    • {multisite_dirs}/
• extensions/
  • Plugins are installed here
  • can contain it's own contents of {APPLICATION_DIR}

How can the core be edited for collaboration?

Cloning the GIT repository

# start from the web root
cd www

# move a step out of the web root
cd ../

# clone git repo branch you want to work on
git clone -b 1.8.x https://github.com/pagecarton/pagecarton.git

# copy public_html files to the web root
# Use cp -r pagecarton/core/local_html/* www/sample-dir/
# to install to a sub directory
cp -r pagecarton/core/local_html/* www/

# set the right file ownership and permissions
# ideallly, the pagecarton directory should be readable and writable 
# by the user running the web server.
# usually www-data or apache or nginx or daemon
chown -hR www-data:www-data pagecarton

Two ways to update core code

1. Edit the core files directly 
   • Locate the file you want to update within pagecarton/core,
   • change
   • commit and
   • push to git
2. Make your changes in the web browser
   By default, on a fresh installation of PageCarton, whenever you make changes to the website, the core files are not changed. Your changes go to a separate {APPLICATION_DIR} in the /pagecarton/sites/ directory. To run a "core" version of pagecarton on the browser, you need to create a configuration file in the {APPLICATION_DIR} you want to use and name the file "pagecarton.json" (/pagecarton/sites/default/pagecarton.json). Put this json code '{ "ignore_this_directory": true }' (without the single quotes) and save the file. Once you do this, all your changes on the site will go to the "/pagecarton/core" and not "/pagecarton/sites/default". Use the following steps
   1. Properly Install PageCarton
      • Go to localhost/personalize in the browser
        Change localhost to the respective domain name if you are working on a LIVE server like example.com. Use localhost/sample-dir/personalize if you installed in a directory. Use localhost/index.php/personalize if you don't have URL rewriting capabilities on your web server.
      • Create admin user and set other preferences
      • Proceed to the admin panel at localhost/pc-admin
   2. Create a multisite instance where you will update PageCarton
      1. Go to localhost/widgets/PageCarton_MultiSite_List
      2. Create a new site. Name the site directory anything e.g. "core-v"
      3. Preview the new site or go to localhost/core-v/
      4. Create pagecarton configuration file for the new site - pagecarton/sites/default/core-v/pagecarton.json
         # pagecarton/sites/default/core-v/pagecarton.json

         {
             "ignore_this_directory": true
         }

          

      5. Now localhost/core-v/ will load the core as the "site" and any updates on it will go straight to the core. Confirm this by going to localhost/core-v/pc-admin to see all the core pages, and other settings loaded.
      6. Make required changes
      7. Commit Changes on the core
      8. Push changes to GIT

How is Git linked to the update server

Once a commit is made and files pushed to the github, there is a hook on github that sends the updated repo to the update server. It's automated that the users get freshly baked software everytime.

How is Themes integrated with PageCarton? [needs content]

How is Plugins integrated with PageCarton? [needs content]

How is Documents and files saved and retrieved in PageCarton? [needs content]