Angular HelpMe Component


In this post I am going to discuss about requirements and my design decisions for creating a reusable angular component, angular-help-me.

You can find the implementation of this discussion @Github. I am pretty much a newbie to Angular, so please share your valuable comments and suggestions for improvement.

Have you ever written / seen any help text in Web forms ? I believe the answer is yes, because as a developer we need to put help contents for our end users to guide them about requirements.

While working on my recent angular based project which consists of some complex forms, I also had to write multiple help blocks in HTML. Writing those help blocks are not cumbersome at first sight, but as it grew in numbers, changing / updating (style, html or text) was pain. Also, this is not the angular way as you are repeating yourself(the html template) for each help element.

Another thought, I have also worked on some projects where we have to render locale specific help texts(based on preferred locale selected by current user). However doing this was easy as template rendering was done from server side. But how will I do this if I have to build an Angular based SPA application ? Do I need to write multiple help elements(locale specific) and display one of them based on the current selected locale ? Of-course this will be pathetic to maintain and is violating Angular DRY philosophy.

To address these concerns, I came up with the idea of writing a Angular Based helpMe component. So, lets say hello to it.

A formal introduction to Component.

Help Me is an Angular component(not just a directive) which tries to solve the above mentioned problem in angular ways. The basic principles behind this component is

  • There should be a segregation between the text definition & its rendering. This will allow non-technical team members(PMs or QA) to define the help text(I might not be good with the language, my QA team always finds my help text more technical. Giving this separation enables me to take help from them).

  • There should be central place to control the rendering of all help texts.

  • Adding new help text should be easy.

  • Adding locale specific help text should be easy.

  • It should be flexible, so that developer can choose how they want to render the help text.

  • Updating help text should be easy i.e developer should't have to put changes in DOM.

Building Blocks

Before going into details of these building blocks, lets discuss if we have to design it in a very simple and angular way how will we approach. My approach is based on these points -

  • I need a simplistic way to put my help texts. And I think JSON would be the best one to define a key value pair, and I can extend it for locale specific keys as well. So, I will go for defining an angular value provider to put my knowledge base for help text.

  • Since I have to design a component which interacts with DOM, I will go for writing a directive(because that is the only way to interact with DOM in angular).

  • Now, I have my knowledge base and my directive which can render the help text with some predefined template, but I need some intermediary body which connects these two angular bodies(directive & value provider) and also controls the rendering of help texts. This intermediary body actually give multiple benefits.

    • Abstraction - I don't want my directive to be aware of how I have defined my knowledge base. This abstraction help me in defining help texts in client side as angular value provider or using http module to get help texts from backend.
    • Control Rendering - It allows to turn on or off the help texts from a central place, which is also a requirement.

Also, I want to design the component mimicking some real world situation. Lets see the design considering a Call Centre.

  1. User calls help desk with a query. Programatically I will put it as -

<i help-text="whatIsSSN"></i>

Here, help desk / front desk, which is good in interacting with user, will be my directive.

  1. Help Desk / Front Desk will then submit the query to HelpDesk Service, which in turn search for helpQuery in its knowledge base and will return the result by formatting it to front desk which in turn respond to user.

Good so far, okay lets see the block diagram for the actual component.

HelpMe Components

  • hiHelpDesk - Service Provider which uses knowledge database(service provider) to resolve client's query. It also provide few other features like -

    • specify what template should be used to render the response of query.
    • allow adding help text at run time. This can be used to add help text for keys which are not configured in helpDB service(very rarely to used, but can be used to specify dynamic help text).
    • allow to control display of all the help texts from a single point. This is very useful when you want to have a toggle help button in your app.
    • allow to set locale. This will take care of rendering the help text in the updated locale.
  • hiHelpDBService - A database service that return helpDB as JSON used by hiHelpDesk as source of knowledge for clients query. For all clients key(query) there must be a pair in helpDB.

  • hiHelpText - Directive that will be used in view. It acts as intermediary between client(HTML) and Angular Service Provider. It take the query(key) from client, ask service to resolve it and then return it back to Client by wrapping the response in some template(specified by service)

See in Action

I have already created an angular based library for this component. Please visit github to see the details of how to use it or to explore the implemenation details.


849 0 0