Whether you are an organisation or an individual who develops Sencha ExtJS/Touch components, it is important that the component meets certain standards in order to make it available and usable to others. There are various tangible as well as non-tangible benefits that one likes to get by creating components and offering it to others. However, as a developer, the primary goal is how to make your component available and usable for others. None other benefits can be derived without meeting this primary goal.
In this article, we would highlight the 10 things that a component developer must do to create and publish a usable component. The article would not give you the component ideas – what kind of component shall be developed – but it would assume you have a great component idea that you think would be useful to others and you wonder what are the things that you shall do to deliver it in the right possible way so that it is easier for your use to find, learn about it, try it, and adopt it.
1) List out the dependencies, clearly
Any component that is practically useful is built on top of some existing components or classes. E.g. in Sencha ExtJS 4.x and Touch 2.x, your component would at least extend Ext.Base class, or use Ext.util.Observable as a mixin. There could be more classes your component may have the dependency on. In case there are dependencies, it is important that you code your component in such a way that your user can make out what classes are required to get your component working. This is important as it tells your component user about the list of class files that need to be included in their build and packaging. I recommend you use the requires config that can be specified while defining a component using Ext.define. This is were you shall list out all the classes that this component requires in order to function as expected. This way, even the documentation generated using JSDuck will have the required classes listed.
Other advantage of this approach is better debugging experience even if you are using on-demand script loading or MVC.
2) Be explicit about version support and handle the in-compatibility, gracefully
It is very important that you indicate the versions of ExtJS/Touch your component is compatible with. There are different ways that you can indicate what framework versions, your component is compatible with:
- Option 1 – By shipping a version.md as part of the component package where you mention your component version and the list of ExtJS/Touch versions the component is compatible with. And, when you describe what is delivered as part of the package, mention this file and tell what is inside it.
- Option 2 – Document it inside the component file header. Currently, there is no JSDuck tag to indicate this. However, you can define a custom tag and use it to generate the supported versions list in the documentation
There are other options, such as, showing the version support information on the Web store, where you have published your component and its detail. But, these are additional options that you may opt for based on where you are publishing your component.
Now that we have looked at the ways to tell the users what versions the component is compatible with. However, chances are still there that users may just download and start using the component in their code even before reading the documentation. In that case, it’s good if you check for the version compatibility and report the relevant message in case in-compatibility is detected. To do this, your component file may have a JavaScript code that would run as soon as it is loaded by the browser and would check if the version of the framework is listed in the list of supported versions of your component. If it is listed, then the loading continues, otherwise, the code throws an exception logging that the component is not compatible with the framework version (the log message must print the list of versions the component is compatible with). In ExtJS 4.x and Touch 2.x, you can make use of Ext.getVersion() method to find out the framework version being used in the application. For ExtJS 3.x and Touch 1.x you can use Ext.version to find out the framework version. The syntax of the returned version string is:
major[.minor[.patch[.build[release]]]]
e.g. 4.1.1.833
In some cases, there could be the browser type or their version which need to be detected in order to enable/disable the related features. I would leave this to the component developer to handle and implement their behaviour. However, the supported browsers shall be documented using the options outlined above.
3) Use the new theming system
In the recent versions of ExtJS (4.2 and onward) and Touch (2.2 and onward) a brand new theming system has been implemented to ease the effort of theming a component or a complete application. The new theming system is based on SASS and Compass and defines component specific SASS variables, mixins, macros, etc. and uses the same to theme a component differently by specifying different values for the variables. As a component developer, you must follow the same process. That means, define your component specific theming variables, mixins, macros, etc. and use them. You must also document them using the related JSDuck tags – @var, @scss mixin, etc. – so that they become part of the generated documentation.
4) Create and Offer Test Scripts
It is important to have the test scripts as it allows you to manage your component releases and also creates credibility among the component users as they can review what use cases have been tested and they can see them working in action. It also helps them understand how to use the component and its different capabilities. Many a times, this offsets the lack of good documentation :)
To write the test scripts, Jasmine would be a good starting point. You may also look at the –tests option of JSDuck for the inline examples.
5) Assist users in decision making by offering Demo/Sample
Unless the user is a repeat customer of yours, it would be extremely difficult for someone to buy/download the component without seeing whether what they are planning to buy/download meets their requirement. So, in order to help the user in their decision making you shall have a demo available that can demonstrate the component capabilities – how it would look and how it would behave. The demo can either be hosted somewhere or it may be showcased as inline example that is part of the component documentation created using JSDuck. The recommendation is embedding it inside the JSDuck documentation as most of the times the user looking for the component would be a developer and also embedding the example inside the documentation will make you to document the example as part of the file header of the component file.
6) Document your component, well
Documentation is one of the critical aspects of the acceptance of a component as it offers the detail to the developer about what component classes are, how the component needs to be used in the application, and what APIs are available to interact and leverage the component behaviours. The documentation shall be offered as a JSDuck documentation that is generated from the source files of the component. Using JSDuck you can document the class, its configs, properties, methods, events, and also link examples, tutorials, and videos to provide all kind of documentation/help to the user in one place.
7) Package your component as Architect User Extension, as well
Sencha Architect 3 has the support for User Extensions where we can import an extension created by someone into the Sencha Architect and use that component/extension in the project. So, with the arrival of this feature it makes sense to package the component as a .aux (Sencha Architect User Extension) file so that the user can import in their Architect and use it inside their project. Remember, this capability is available for Sencha ExtJS 4.2+ and Touch 2.2+ versions. So, if you are creating a component for older versions of the frameworks, this is not applicable.
8) Commercial/Free/Open Source? – Have a licensing model
Licensing is a very important aspect of the component development when you want your component to be used by someone else. Licensing is going to tell the user how they can get the component, how they can use it, can they re-distribute it, can they create derivative work from the component, etc. You can choose from a list of “Open” licenses (e.g. MIT, Apache, GPL v2/3, LGPL, BSD, etc.) based on what truly reflects your licensing policy or have your own proprietary one. Once you have identified the suitable license for your component, you shall ship the license file along with the component when it is packaged. Alternatively, you can also provide an online URL of a website, in the documentation, where user can go through the license detail.
9) Publish the component where the visibility is high
Once you have packaged your component that is ready for your user to use, you need to think about how do you intend to distribute it so that people are able to download or purchase your component and use it in their application. You can publish your component on various places to gain the visibility and increase the possibility of more people knowing about it and trying it. However, one legitimate and highly visible place where you shall certainly publish your component is – Sencha Market. This is a very active repository of various Sencha components and Sencha developers/users mostly visit this to find out a component that they are looking for.
10) Offer Support – Increase adoption
No good software can survive without the support. PERIOD! And, this applies to every small or big component that you develop and publish for others to use in their application. Support could come during the pre-evaluation stage (e.g. Does your component support IE8?) or during the evaluation phase of the component (e.g. I am passing the buffer: true config while initializing the component but I don’t see buffering working) or post-evaluation (e.g. Will this component support saving BLOB files in near future?) or when it is being integrated into an user application. And, the kind of support you offer at these stages would determine how far your component would go. So, make sure that when you publish a component you also tell your user how to get support(e.g. email/chat/ticket/etc.) and what would be your SLA (within 2Hrs/within 24Hrs./etc.).
There are more items that as a component developer you might have already been doing or plan to do but here I wanted to mention the first 10 things that are needed in order to increase your component’s adoption rate.
Filed under: Sencha ExtJS, Sencha Touch
