support/doc/client/code.md

   1 # Client code documentation
   2
   3 The client is a HTML/CSS/JavaScript web application (single page application -> SPA) developed with [TypeScript](https://www.typescriptlang.org/)/[Angular 2](https://angular.io/).
   4
   5
   6 ## Technologies
   7
   8   * [TypeScript](https://www.typescriptlang.org/) -> Language
   9   * [Angular 2](https://angular.io) -> JavaScript framework
  10   * [SASS](http://sass-lang.com/) -> CSS framework
  11   * [Webpack 2](https://webpack.github.io/docs/) -> Source builder (compile TypeScript, SASS files, bundle them...)
  12   * [Bootstrap](http://getbootstrap.com/) -> CSS framework
  13   * [WebTorrent](https://webtorrent.io/) -> JavaScript library to make P2P in the browser
  14   * [VideoJS](http://videojs.com/) -> JavaScript player framework
  15
  16
  17 ## Files
  18
  19 The client files are in the `client` directory. The Webpack 2 configurations files are in `client/config` and the source files in `client/src`.
  20 The client modules description are in the [client/package.json](https://github.com/Chocobozzz/PeerTube/blob/master/client/package.json). There are many modules that are used to compile the web application in development or production mode.
  21 Here is the description of the useful `client` files directory:
  22
  23     tslint.json   -> TypeScript linter rules
  24     tsconfig.json -> TypeScript configuration for the compilation
  25     .bootstraprc  -> Bootstrap configuration file (which module we need)
  26     config        -> Webpack configuration files
  27     src
  28     |__ app          -> TypeScript files for Angular 2 application
  29     |__ assets       -> static files (images...)
  30     |__ sass         -> SASS files that are global for the application
  31     |__ standalone   -> files outside the Angular application (embed HTML page...)
  32     |__ index.html   -> root HTML file for our Angular 2 application
  33     |__ main.ts      -> Main TypeScript file that boostraps our Angular 2 application
  34     |__ polyfills.ts -> Polyfills imports (ES 2015...)
  35     |__ vendor.ts    -> Vendor imports (Angular, Bootstrap...)
  36
  37 Details of the Angular 2 application file structure. It tries to follow [the official Angular 2 styleguide](https://angular.io/docs/ts/latest/guide/style-guide.html).
  38
  39     app
  40     |__ account                      -> Account components (password change...)
  41     |__ admin                        -> Admin components (friends, users...)
  42     |__ core                         -> Core components/services
  43     |__ login                        -> Login component
  44     |__ shared                       -> Shared components/services (search component, REST services...)
  45     |__ videos                       -> Video components (list, watch, upload...)
  46     |__ app.component.{html,scss,ts} -> Main application component
  47     |__ app.module.ts                -> Angular 2 root module that imports all submodules we need
  48
  49 ## Conventions
  50
  51 Uses [TSLint](https://palantir.github.io/tslint/) for TypeScript linting and [Angular 2 styleguide](https://angular.io/docs/ts/latest/guide/style-guide.html).
  52
  53 ## Developing
  54
  55   * Install [the dependencies](https://github.com/Chocobozzz/PeerTube#dependencies)
  56   * Run `npm install` at the root directory to install all the dependencies
  57   * Run MongoDB
  58   * Run `npm run dev` to compile the client and automatically run the server. Then the server will watch and compile the client files automatically. You just need to refresh the browser to see your modifications.
  59
  60 In a Angular 2 application, we create components that we put together. Each component is defined by an HTML structure, a TypeScript file and optionnaly a SASS file.
  61 If you are not familiar with Angular 2 I recommend you to read the [quickstart guide](https://angular.io/docs/ts/latest/quickstart.html).
  62
  63 ## Components tree
  64
  65 ![Components tree](https://github.com/Chocobozzz/PeerTube/blob/master/support/doc/client/components-tree.png)
  66
  67 ## Newcomers
  68
  69 The main client component is `app.component.ts`. You can begin to look at this file. Then you could navigate in the different submodules to see how components are built.