Home

Angular Boilerplate Documentation

In GitHub, wikis are NOT part of project repositories. They have their own repositories. Anyone cloning the boilerplate repository will NOT get the wiki. This is the wiki repository clone link: https://github.com/Shift3/boilerplate-client-angular.wiki.git

Angular Boilerplate Documentation

Boilerplate Features

Here is a list of features built into the Angular boilerplate.

Return to top

Boilerplate Project Structure

Here is an explanation of the project structure.

Return to top

Development Loop

Here is a recommended development process for a common CRUD use case (let's say we need to add the classic, a Todo feature). For the sake of this example, we are making a new feature module, a routing module to go with it, and list and detail components that are split into the container/presenter pattern. The detail view gets its values through resolvers. Below are steps to do that, along with common considerations that are good to think about.

The order here is a guide, but each developer has their own process.

Services
- Create a service: TodoService. These services ideally match the API controllers or grouping of endpoints for the feature.
- Create methods for endpoints: getAllTodos(), getTodoById(), createTodo(), updateTodo(), deleteTodo().
- Create unit tests for each endpoint method.
- Create models for response types: ITodoDTO.
- Create models for request types: ITodoRequest, TodoRequest.
- Test the endpoint methods.
- Make sure the unit tests are up to date.
Routing
- Create the resolvers and their tests: CreateTodoResolver and UpdateTodoResolver.
- Create any custom guards and their tests if the existing ones aren't sufficient.
Components
- Set up container/presenter logic for the detail and list views.
  - Container - e.g. TodoDetailSmartComponent
    - The container component is in charge of assigning values from their sources (getting values from a resolver or a service), sending values out (passing request payloads to setters), and triggering other UI interactions (navigating to new routes, opening modals, etc).
    - The only HTML template a container should have is the selector reference to the presenter component (its own or a generic shared component).
    - It also doesn't need its own style sheets.
  - Presenter - e.g. TodoDetailPresentationComponent
    - The HTML template lives in the presenter component.
    - Presenter components get values through input bindings, and emit values back to parent components through output bindings.
    - Presenters fire events back up to parent container components, with or without values, depending on the event. They pass messages along, they don't enact behavior.
    - Presenters can have simple presentation-only logic (e.g. having a small boolean method that determines if wording should be singular or plural).
    - Presenters shouldn't know about RxJS and should get the raw data (they will update through the input bindings whenever the parent updates).
  - Detail View
    - Create a dynamic form that will work for both the create and edit views (conditionally render things if necessary).
  - List View
    - Create a list view that retrieves the list and sends it to a table. One of the existing tables might work, or work with modifications. If not, it's possible to create a custom TodoTableComponent.
Set up the module and routing.
- Create the TodoRoutingModule.
- Set up the route(s) for the component. A detail view component might get multiple routes (e.g. TodoDetailComponent might be the component destination for create-todo and edit-todo/:id).
- Connect the resolvers for the detail routes: CreateTodoResolver for create-todo, and UpdateTodoResolver for edit-todo/:id.
- Set up any distinct route-specific guards.
- Create the TodoModule. Add references to SharedModule and TodoRoutingModule.
- Lazy load the TodoModule in the root AppRoutingModule.
- Add any module-level guards to the lazy loaded module in AppRoutingModule.
- Test everything again.
Shared components
- Shared components should live in the SharedModule.
- They should ideally be presentation components (i.e. they are given their data and don't know the implementation details of how it got there).
- They are not usually routed components (i.e. they are bound to another component's template through a selector: <app-foo></app-foo>).

Return to top

General Considerations

Services
- Does the service unpack the server response or transform it some way?
- Should there be side effects? Are there notifications on success? Does the service update state?
- Should there be todo-specific state? If so, consider a TodoStateService for it.
Routing
- Should this be routed behavior or reusable?
- Should the route be be added existing feature module or get a new one?
- Should there be sub-routing within an existing router?
- Does this content need special guarding? Children routes can have extra guards in addition to any guards from parent routes. Maybe any authenticated user can read, create, and update todo items but only administrators can delete them.
- Should the data be pre-fetched through a resolver?
Components
- Does it need a new component?
- Is it a detail view or a list view?
  - Detail
    - Does it need a form?
    - Will the DynamicForm builder work?
    - Can it be part of an existing detail view? (e.g. edit view for something with a create view and form already).
  - List
    - Output list values to list/table.
    - Consider using an existing table component or making one that receives the list data from the parent list view. This way, the parent list view is in charge of retrieving the data, and the table component can know the particulars of how to be a table.