Create Components Using Command-Line Tools

The OSF command-line interface includes several commands that you can use to simplify the process of creating a widget and supporting components.

You can use these commands to create templates for building the following types of components:

  • widgets
  • actions
  • fetchers
  • endpoints
  • selectors
  • subscribers

The commands create the files and directories that make up the structure of the components. The files include comments that provide guidance about writing the code and supplying the configuration for the component.

Create a Widget

To create a widget from a template, you use the create-widget command. You can use this command with the --template flag to specify the template to use (either Blank to create a basic widget, or CurrencySelector to create a widget whose files include specific implementation logic and instructions for creating a currency selector). If you omit the flag, the widget is created from the Blank template.

For example, the following command creates a widget named MyWidget from the Blank template: 

yarn rdc create-widget --name MyWidget

[cli] info: Creating Widget: MyWidget
[cli] info: Widget path: packages\apps\blank-store\src\plugins\components
[cli] info: App locals - en,de
[cli] info: Creating new widget folder packages\apps\blank-store\src\plugins\components\my-widget
[cli] info: Writing template files to packages\apps\blank-store\src\plugins\components\my-widget
[cli] info:      config\index.js
[cli] info:      config\locales\en.js
[cli] info:      config\locales\de.js
[cli] info:      index.js
[cli] info:      locales\en.js
[cli] info:      locales\de.js
[cli] info:      meta.js
[cli] info:      README.md
[cli] info:      styles.css
[cli] info:      __test__\my-widget-widget.spec.js
[cli] info: Updating exports for files:
[cli] info:     packages\apps\blank-store\src\plugins\components\index.js
[cli] info:     packages\apps\blank-store\src\plugins\components\meta.js
This command creates a widget from the CurrencySelector template:
yarn occ create-widget --name MyWidget --template CurrencySelector

The widget is created in the default application in the workspace. For example, if the default application is named my-app, the widget files are created in packages/apps/my-app/src/plugins/components/my-widget. To create a widget in an application other than the default application, you can specify the application name in the command. For example: 

yarn occ create-widget my-other-app --name AnotherWidget

Create an action

To create an action, you use the create-action command. For example: 

yarn occ create-action --name myAction

[cli] info: Creating action: myAction
[cli] info:      Action exported as _myAction
[cli] info:      Action's Path: src/plugins/actions
[cli] info: Creating new action folder packages\apps\blank-store\src\plugins\actions\my-action
[cli] info: Writing template files to packages\apps\blank-store\src\plugins\actions\my-action
[cli] info:      index.js
[cli] info:      meta.js
[cli] info:      schema\input.json
[cli] info:      __test__\index.spec.js
[cli] info: Updating exports for files:
[cli] info:     packages\apps\blank-store\src\plugins\actions\index.js
[cli] info:     packages\apps\blank-store\src\plugins\actions\meta.js

When you create an action, you can also create a reducer that the action invokes:

yarn occ create-action --name myAction --reducer

The reducer is created in the action's index.js file.

You can also specify an endpoint that the action invokes:

yarn occ create-action --name myAction --endpoint myEndPoint

Note that this command doesn't create the endpoint, it just specifies the name of the endpoint required by the action. You can either specify an endpoint that has already been created, or write one afterward with the name you specified. (If you use --endpoint but omit the endpoint name, the name defaults to the name of the action.)

Create a Fetcher

To create a fetcher, you use the create-fetcher command. For example: 

yarn occ create-fetcher --name myFetcher --endpoint getSite --selector mySelector
By default, the create-fetcher command creates a global fetcher. To create a fetcher for a specific widget, use the --forComponent flag. For example:
yarn rdc create-fetcher --name myFetcher --endpoint getOrder --selector mySelector --forComponent HelloWorld

Note that the specified widget must already exist. The specified endpoint and selector can already exist, or you can write ones afterward with the specified names.

Create an Endpoint

To create an endpoint, you use the create-endpoint command. The version of the command that you use depends on whether your organization maintains a Swagger-based document containing a JSON representation of the REST API endpoints that can be called from widget code.

To create an endpoint from a Swagger document, you use the --swagger flag to specify the location of the Swagger document, which can be either a URL or a local file. For example: 

yarn occ create-endpoint --directoryName swagger-endpoints --swagger http://www.example.com/catalogApi --endpoints getOrder,putOrder

The --directoryName flag specifies the subdirectory (relative to the application's \src\plugins\endpoints directory) to create the endpoint in. The command creates the specified directory; it cannot already exist. If you do not include the --directoryName flag, the directory name is based on the pathname of the Swagger document's URL or file.

The --endpoints flag is used to specify a comma-separated list of the IDs of the REST endpoints in the JSON document. There are two ways to specify these IDs:

  • If the JSON document includes an operationId value for each endpoint, use these values to specify the endpoints. The example above illustrates using these values.
  • If the JSON document does not include operationId values, the identifier for an endpoint is constructed by concatenating the method and pathname, removing non-alphabetic characters, and then converting the result to camel case. For example, the identifier for a POST /invoice/payments endpoint would be postInvoicePayments, and the identifier for a GET /invoice/payments/{id} endpoint would be getInvoicePaymentsId.
Note that you can display a list of all the endpoints in a Swagger document by using the list-endpoints command. Like the create-endpoint command, list-endpoints uses the --swagger flag to specify the location of the Swagger document, which can be either a URL or a local file. For example:
yarn occ list-endpoints --swagger http://www.example.com/catalogApi

To create an endpoint from a document that is not in Swagger format, you use create-endpoint with the --url flag to specify the URL of the document, and the --verb flag to specify the HTTP verb. For example: 

yarn occ create-endpoint --directoryName other-endpoints --url http://www.example.com/orders --verb GET

If you do not include the --directoryName flag, the directory name is based on the pathname of the API document's URL.

Create a Selector

To create a selector, you use the create-selector command. For example: 

yarn occ create-selector --name mySelector --repository myRepository

You use the --repository flag to specify the state subobject that the selector accesses. You can also specify a table of that repository using the --table flag: 

yarn occ create-selector --name mySelector --repository myRepository --table myTable

You can specify an entity of the table as well:

yarn occ create-selector --name mySelector --repository myRepository --table myTable  --entity myEntity --entityId myEntityId

Note that you must include both --entity and --entityId to specify the entity.

Create a Subscriber

To create a subscriber, you use the create-subscriber command. For example: 

yarn occ create-subscriber --name mySubscriber

This command creates the index.js and meta.js files for the subscriber.