The Akumina Widget Builder was created as a tool to be embeded within your existing front end development projects. The goal was not to require you to utilize the Akumina project structure. Akumina assumes that most dev teams have a way of doing development and that the Akumina product is just a piece of it. Akumina has recommended "Starter Projects" for those dev teams that are newer to front end development. For the newer dev teams the ability to learn at their own pace was a big part of this design. You can isolate Akumina Widget code from your own code. Akumina also does not require you to learn Typescript, React, GULP, WEBPACK, etc all at once. Although we do recommend some of these tools / technologies as it helps development processes. Akumina realises the different level of developers within an implementation and has tried to cater to any skillset.
As you are learning about this tool, please keep in mind the tool was primarily developed for quick development, debugging and packaging of the following pieces of the component (Widget):
- Widget Definition (Class structure)
- Available views
- Settable properties / property types and default property values
- Assigned Content Types
- Widget Instances (Objects insert into pages)
- Assigned view
- Assigned property values
Starting the Process
Requirements: Established Akumina Project Directory. For assistance with this, please consult the Akumina Yeoman Generator page.
Starting the process is as straight-forward as starting any Akumina-native tool. Simply open the terminal and enter in the following command to start the Akumina Widget Builder experience:
npm run stub
The process will begin to walk you through the steps to create a new widget. The experience looks similar to the following:
The options are detailed below:
- The name of the widget you would like to create. There is no default option for this. This will be the name of the widget folder, the widget JS file, and the name of the widget as defined in the config.json file.
- The Namespace of the widget you're creating. This is also an option in the Akumina Yeoman Generator experience. However, because this value is saved in a property in webpack.config.js and not in a global settings file, it is necessary to enter this option. The default option for this is "MyClientNamespace".
- The template of the stub you wish to create. Currently the Widget Builder supports two templates: Hello World and Get List. Hello World is a simple widget that renders as Hello World message when uploaded to a Sharepoint site collection runing the Akumina Framework. The Get List template comes with Sharepoint Data Retrieval functions scaffolded.
- Widget directory. It is imperative to place widgets in the correct directory for building and bundling. The default value for this option, and the default directory structure generated by Yeoman, is src/js/widgets.
- Instance only widgets. This option will flip a flag in the config.json of the widget to denote the widget is not being uploaded as a full widget, but only as an instance of an already existing widget.
- Typescript. This option is very important. If your project structure was not set up to use Typescript, you should not create a Typescript widget. The widget will fail to be built or packaged. We do not advise mixing widget frameworks within the same project.
Once all options are set, the widget will be created in the directory of your choosing with defaulted values. For more information on the default files created by this process, please see the Akumina Widget Structure page.