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 occ 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
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
create-fetcher
command
creates a global fetcher. To create a fetcher for a specific widget,
use the --forComponent
flag. For
example:yarn occ 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 aPOST /invoice/payments
endpoint would bepostInvoicePayments
, and the identifier for aGET /invoice/payments/{id}
endpoint would begetInvoicePaymentsId
.
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-selector --name mySubscriber
This command creates the index.js
and
meta.js
files for the subscriber.