Creating a new add on
- When you first start developing an add-on, there are some considerations to be made.
Before you start of creating a new add-on, look at the list of published add-ons at schemaform.io and check if someone hasn't already done it. May sound obvious, but people have reinvented the wheel before.
Also, Open Source is about collaboration, and unless you after a thorough discussion realize that you have unsolvable creative and technical differences, you should try and get involved in and improve an existing project first.
If you didn't find a matching add-on, then by all means, continue reading:
If it is code that have been developed as part of a commercial project, there might be some issues to consider.
Here on Github. It can be located anywhere, but ASF is located here, and Github is integrated with linking and lots of other features that makes it beneficial.
The norm is angular-schema-form-my-add-on-name. I is recommended that you follow that standard, if for no other reason, because that is one of the ways schemaform.io compiles its list.
First, try and base it on an existing example. There are lots of things that are easy to forget and hard to configure, like packaging and build environment. Also, the examples follow the conventions of ASF.
To help you out with that, there is a python-tool that creates a new add-on based on the "minimal" example. It renames all constants, files and so on.
Do not use stand-alone controllers
First, ng-controller is going away in Angular2, and second, it is bad design, so do not use it. Instead, use directives and use a controller in it.
Try to make the add-on implement and use as many of the existing options and features of ASF as possible. If you, for example, want to extend some built-in component, make your add-on act as the built-in component(within reason of course), so that users can easily change to and from using it.
The technical documentation on how to extend ASF is version specific, and therefore located here.
Also, the documentation is based on the examples, this means that it will make you somewhat familiar with their structure.
What? Building a script application? Yes, yo have to. This is actually required, not a consideration per se. In the most basic case, which is applicable to all ASF add-ons, these steps are needed:
- concatenation - Creating the .js-files that are actually run by the web application. Mainly, this is about injecting the template caches into the top of the files.
- minification - To lessen the amount of data having to be loaded by the client, all empty space is removed, the syntax tree is optimized, and all variable and function names are shortened. This uglification often result in significantly smaller(and harder to read) code.
There is also actual compilation in some cases, for example if a project uses Typescript(which could be considered a good idea, soon).
The convention for ASF add-ons is using gulp. It is therefore highly recommended to use that as well, as it then will become far easier to get help here.
Think long-term. Be a collaborator. Welcome and value other's input. If the project succeeds, it will be in use for several years. It is seldom that life doesn't change at all, so think cooperation and try to entice and invite other developers to share the experience with you.
- all git hub concepts, like issues and pull requests.
- to create a plunkr example, it is useful to get help, but also to pinpoint a problem.
- add a gitter chat to your project. This is a really nice way to connect and discuss.
- put effort in writing the documentation for your add on. This is very important. Do not expect people to follow links too much, those are for reference stuff.
- consider what options you should implement:
- To be a well behaved ASF add-on, it needs to support the relevant ASF built-in options. Check which may apply to you add-on and add support for them. It may not be a big issue, many you may support without knowing it, because they apply to behaviour that your add-on isn't involved with.
- It may be hard to guess what options users want, but usually, the common thing is that people simply want to pass on settings to the object you are wrapping. If you pass on those (for example), and set reasonable defaults, that will probably satisfy most.
- This is open source, and unless you are paying for it, no one is obliged to help you. So be super nice and don't ask questions where the responder has to do your work. Do not use slang. Carefully proofread your question.
- The language in open source is almost exclusively English.
Poor language can make it almost impossible to understand an already complicated problem.
If you have poor command of English, it is especially important to use examples when explaining yourself(plunkr etc.). Keep sentences short, use short paragraphs.
Well done! But you are not completely done, if you want anyone else is to see it, you will need to publish it.
No problem, we are here to help, ask the other add-on developers in the gitter chat room:
