The Scrivito Example App includes a generator for conveniently creating CMS object and widget classes. In this brief tutorial, we are going to show you how to generate a widget class and explain the purpose and working principle of the files the generator creates. Generating an object class works analogously, so we are not going to deal with this part here. If you are a first-time user, consider taking a look at our Introduction to Creating and Rendering Pages and Widgets before you start.

Note that using the generator is optional – you can also code your widget and page classes from scratch or create them by copying an existing one. Sometimes, the latter is even more efficient, for example if the new class has a lot in common with some other class in the Example App.

To use this generator, first make sure you have Yeoman installed on your computer or development environment. You can quickly check on your command line or terminal with the command yo --version. If you do not get a version number returned then you likely do not have Yeoman already installed. To install it, use the command npm install -g yo.

Let’s jump straight in and create a widget class for providing editors with a simple page title widget that displays the title in bold and capitalizes each word! In a terminal window, change to your Example App’s project directory and execute yo scrivito:

$ yo scrivito
Welcome to the Scrivito Obj/Widget generator!
? What do you want to generate?
  An Obj class
❯ A Widget class

After selecting “A Widget class” and hitting the return key, you can enter the name to be given to the new class.

Object and widget class names must be camelcase style, i.e. start with a capital letter and must not contain underscores. Enter PageTitleWidget (without the quotes):

Welcome to the Scrivito Obj/Widget generator!
? What do you want to generate? A Widget class
? Enter the name of the new Widget class (e.g. GiphyWidget): PageTitleWidget

After hitting the return key, the generator creates the widget’s directory in “src/Widgets” (it’s “src/Objs” for object classes) and adds four files to it:

Welcome to the Scrivito Obj/Widget generator!
? What do you want to generate? A Widget class
? Enter the name of the new Widget class (e.g. GiphyWidget): PageTitleWidget
   create src/Widgets/PageTitleWidget/PageTitleWidgetClass.js
   create src/Widgets/PageTitleWidget/PageTitleWidgetEditingConfig.js
   create src/Widgets/PageTitleWidget/PageTitleWidgetComponent.js
   create src/Widgets/PageTitleWidget/PageTitleWidget.scss
$

We are now going to take a look at the individual files and edit one of them (the component) according to our demands.

The “…Class” file is mainly for specifying the attributes in which the content of the actual widgets will be stored. As a default, the generator provides an attribute named headline, but we’ve changed it to pageTitle so that it reflects the widget’s purpose:

With respect to the above class file, there are a couple of things that should be mentioned:

• Scrivito.provideWidgetClass creates a React component class and makes it known to Scrivito so that the SDK takes care of fetching and updating the content in the instances of this class (the actual widgets on pages).
• Scrivito has several built-in attribute types for handling different types of content, e.g. date or enum.

Generally speaking, an “…EditingConfig” file lets you specify how a CMS object or widget class is presented to editors, for example when using the respective selection dialog to create a page or add a widget to a page. Of the several aspects that can be dealt with via the “…EditingConfig”, the generator addresses only two here, the widget’s title and the default value of its only attribute. Again, we’ve renamed the headline attribute to pageTitle:

As you can see, the configuration is defined using Scrivito.provideEditingConfig. We’ve changed the widget’s title as well as the initialContent of the pageTitle attribute, the latter being what an editor sees after adding our PageTitleWidget to a page.

You guessed it, the “…Component” file of an object or widget definition is for rendering the respective model instances. Let’s inspect what the generator has prepared for us:

The call to Scrivito.provideComponent serves to define a functional React component for a model class. In our case, the generator has provided us with a function that returns a Scrivito.ContentTag component for rendering the headline attribute of the passed-in widget. Scrivito.ContentTag is one of Scrivito’s built-in components for accessing CMS content.

The above component imports “./PageTitleWidget.scss”, the CSS file provided by the generator as well:

The file includes an empty CSS class selector named after the widget so you can add your styles dedicated to the widget right away.

Now, let’s do what needs to be done to make this component render a capitalized page title: rename headline to pageTitle, specify the tag to use and the CSS classNames to apply, strong and text-capitalize (originating from Bootstrap):

After firing up your Example App, you should now be offered the “Page Title” widget when adding a widget to a page. Go ahead, type a couple of words and see how their initial letters are automatically capitalized!