Search

Survloop Package's File & Folder Layout

Updated October 25, 2019 by Morgan Lesko

This document should help map out the contents of the Survloop package on GitHub.

After months of initial development, this open data engine was migrated to run atop the Laravel framework, which is a Model View Controller (MVC).

 

If you're new to Laravel, this package gets installed here: /root-folder/vendor/rockhopsoft/survloop

rockhopsoft/survloop

  • composer.json: Defines more packages required by Survloop, as well as easier references to some packages.
  • src: Repository's main source code.
    • SurvloopServiceProvider.php: SurvloopServiceProvider manages which package files and folders need to be copied to elsewhere in the system. This mostly just runs after installation, and perhaps of some other code updates.
    • Controllers: Most of the PHP algorithms and logic which process and manipulate data, and call Views to output the proper results.
      • Admin: These PHP classes controll both all admin tools for managing survloop, but also handles routing for Survloop pages and surveys which require any user login.
      • Auth: A few Laravel authorization classes customized by Survloop.
      • Globals: These classes can be easily accessed from both Controllers and Views.
      • Middleware: A few Laravel files overwritten by Survloop.
      • Stats: These classes are used by Survloop to manage the more complicated statistical needs, charts, and graphs.
      • Tree: This is really the core trunk of Survloop, classes which manage the branching trees which generate all surveys, pages, etc.
    • Database: Includes migration and seeder files which Laravel can use to install Survloop.
    • Models: Copies of all the Eloquent Models used by this package, generated by this same Survloop installation.
    • Routes: All of Survloop's routing happens here, passing a url request to the right Controller.
    • Uploads: Contains images and photos in Survloop's default media gallery, most are simply needed for Survloop branding.
    • Views: Includes Blade Templates which are called by controllers, and where most of Survloop's HTML, Javascript, and CSS can be found. Templates for...
      • admin: general Survloop-standard admin interfaces
        • db: admin database design tools
        • tree: admin survey and page design tools
      • auth: user authentication, customizing Laravel's style
      • css: cascading style sheets for the Survloop engine
      • elements: smaller site design or usability elements
      • emails: sending emails via the installation
      • errors: web site error pages
      • forms: generating survey forms and compartmentalized input tools
      • js: javascript which runs lots of user experience for the Survloop engine
      • reports: generating reports, graphs, and geographic maps
  • tests: Holding place to remind me to add as much unit testing as possible and appropriate.

 

rockhopsoft/survloop-libraries

  • src: Third-party code libraries which Survloop incorporates.

 

Structure of Classes & Objects

This section provides a top-level map of the Controllers folder, and how its most influential classes and objects relate to each other.

Some of these long chains of extensions were simply steps toward breaking up long files. I hope to keep splitting out functions into more isolated classes which don't need to load in the main trunks.

I am also of course welcome to migrating to different design patterns when there is time or necessity.

SurvloopController

Routes are largely directed through...

Down the line, I hope to replace AdminDBController and AdminTreeController with admin-only Survloop-generated forms. And all other admin tools.

The Globals object is loaded into $GLOBALS["SL"] and primarily provides lookups and tools to be accessible from both Controllers and Views...

The Tree Trunk is the single largest block of the engine which generates all the surveys and pages for Survloop...

The Stats Engine is hopefully most often called by a tree...

 

Client Packages

A client package running atop the Survloop engine will automatically load client-customized extensions of these classes as well...

  • Client/Client
    extends
    Survloop/Tree/TreeSurvForm
  • Client/ClientAdminMenu
    extends
    Survloop/Admin/AdminMenu
  • Client/ClientAdmin
    extends
    Survloop/Admin/AdminController
  • Client/ClientSearcher
    extends
    Survloop/Searcher

Simplest Example:

rockhopsoft/survlooporg

 

Roadmap for Codebase

Current plans for improving the organization and structures of the codebase...

  • Break off any independent components from being within the Tree Trunk and Globals, which can instead instantiate side-classes when on demand.
  • Start adding unit tests to functions and ideally whole files.
  • Expand Globals from being "focused on one database and tree", to "able to load [caches of] all the database and tree structures needed for a page load.
  • Shift to PageLoadUtils being even more the core trunk of a page load, instead of the Tree Trunk.
  • Further clarify and separate the distinctions and relationships between PageLoadUtils stuff, Globals stuff, Tree Trunk stuff, and Searcher stuff.
  • Adding unit test to as many functions as possible.
  • Adding comments to the remaining functions.
  • Replace all admin tools with forms generated by Survloop. #SelfReplicatingGUI/CMS

 

Updated October 25, 2019

Home
Documentation
On GitHub
An open source project by Morgan Lesko as
Rockhopper Software Designs logo
Survloop.org content is under
Creative Commons
2015-2021