21joint / pg

Parental Guidance

Quick Start

At first please make sure you have Node.js stable installed on your local machine.

You can check NodeJS presence by running node -v in your terminal which can be found on their official website.

1. Have your apache server running using XAMPP or MAMP(OSX).

2. In the terminal run cd /path/to/the/project_root and run npm install

   • After the process is successfully complete, without any errors, you can find out that a node_modules folder is created, which is going to contain all the:

     • dependencies(code which is going to get into production bundles)
     • devDependencies(development only stuff)

3. npm run dev will run a development server on port 2121

   note: our development server is a proxy server, and it has built in middleware, which is needed to handle the API calls from our local http server to https. You can get all the server configuration variables in webpack.dev.config.js

   • once we have the development server running, all the bundled js/css files are available using url:
     

     '/scripts/{module_title}.bundle.js'
     '/styles/{module_title}.bundle.css'
     

     so accordingly we can reference them in our .tpl or Controller.php

4. npm run build is building { js | css } bundles

Whats Included

• Bootstrap 4 (latest) (official website)
• SCSS stylesheets (docs)
• Webpack (latest) (official website)
  • concept
    • entries ( in our case [{module_title}.module.js] )
    • output ( in our case [{module_title}.bundle.js] / [{module_title}.bundle.js] )
    • loaders (using loaders we are able to import everything in our modules)
    • plugins
  • webpack-dev-server
  • webpack-configuration
    • [
         mainWebpackConfigurationFile:   webpack.config.js,
         developmentWebpackConfigurationFile: webpack.config.dev.js
      ]
    • proxy options like apache server (XAMPP/MAMPP) host / port

Moving Around

The socialengine platform has its frontend layer based in the active theme folder.Accordingly we have ./application/themes /current_theme) folder, which has the following structure:

• /modules
• /components
• /services
• /scss (common styles)
• /images
• /fonts

Modules

Modules are

theme_directory
      └──  modules
              └── [module_title]/[module_title].module.js       

[*] all module files need to have extensions like: /[module_title]/[module_title].module.js

• creating new modules

  Another thing, that needs to be mentioned about the modules -
  is that: everytime we create a new modules, we have to add it into the entries
  

Components

theme_directory
      └── components
              └── [component_title]/[component_title].js
              └── [component_title]/[component_stylesheet].scss

Services

theme_directory
      └── services
              └── [service_title]/[service_title].service.js

• services should used/created to interact with the API layer
• Right now we have only one service - api.service.js.
  
• we may need to create some new services, if we find out we need to separate some logic related to the API calls

Advantages

#####development

• better structured code, where even filename is self explanatory
  • a [module] can import any type of assets using appropriate loader:
    • styles (.css , .scss)
    • images (.png, .jpg, .jpeg, .ico, .svg)
    • fonts (.svg, .eot, .woff, .woff2)
    • js | jsx
    • html (though we don't need it right now, as a module)
• all the vendor code always up to date with the best JS package manager - npm
• any package can be installed doing simply npm install package-name and can be updated via npm update (find packages)
• with the latest vendor codes (plugins, libraries like jquery, bootstrap)
• most of our javascript will be out of templates (.tpl files )
• everything related to a [ module ] is imported in its *[ .module.js ]
• ability to import only some parts of vendor code, for every particular module / widget
• ability to use modern javascript - ES6 techniques template literals
• all the vendor code coming from npm (e.g. jquery, bootstrap)
• all API calls organized in particular services
• source code, which is going to be more than scalable
• ability to easily start using any js framework / library (angular 6, react, vuejs), in case we need it in future

#####production(*)

• single (minified) {module_title}.bundle.js file per widget
• single (minified) {module_title}.bundle.css file per widget
• cross browser js code after bablifying