Widgets

Widgets are independently managed, small applications that perform specific tasks, which you can develop and deliver across your digital channels. Widgets are what allow you to create a microfrontend architectural style for better maintainable codebases, more scalable, autonomous teamwork within your organization, and updates to your digital channels in a more consistent, incremental fashion.

When you enter the Widgets section of any site or channel, you see a list of all the widgets in that channel. In the top bar, you can filter the list of widgets by status, author or tags, or search for any widget by either its name or tags.

In the upper right corner you can select the + New primary button to create a new widget. Give the widget a name, then click Create to begin building your widget.

In the widget editing view, you can see three areas: the top action bar, the main work area and the properties column on the right.

Widget builder

Along the top bar, on the left, you can see the widget name and current status:

  • Draft: This status means a widget is new or is unpublished.
  • Published: This status means a widget is published and the version in the editor contains no unpublished changes.
  • Pending changes: This status means there is a published version of a widget, and the editor contains unpublished, pending changes.
  • In review: This status means team review is enabled and this widget is in review.
  • Approved: This status means team review is enabled and a widget passed the review process. You can now publish this widget.

Tip

You may notice that some widgets with Pending changes and In review statuses have a small green mark. This green mark indicates that there is an active, published version of this widget available.

Here are the available actions on the right side of the top bar: Preview : Opens a preview of the widget in a new tab.

Differences : Clicking this icon opens a modal to compare the differences between the active published version of this widget, and the editable version you are currently working on. You can use the version selectors to compare either the editable or active published versions to older back up versions as well.

Tip

If you do not see the Differences icon, then there is no published version of this widget.

Show activity : Displays a sidebar with activity history and comments. At the bottom of the sidebar, you can submit comments. Next to each activity, click on "see detail" to show the complete information of an activity log.

More actions :

  • Archive: Archives the widget. You cannot archive published widgets.
  • Copy: Instantly creates a copy of the widget, prepending "Copy of " on the widget name.

Primary actions

  • Save: Saves current changes.
  • Send to review: Changes the widget status to "In review". You can continue making changes, but each change sends a notification to all assigned reviewers via email.
  • Publish: Once reviewers approve the widget, it can be published.

Other primary actions :

  • Reject: Returns the widget status to the "Pending changes", notifying reviewers that the changes were rejected.
  • Force Publish: Admin team members have the option to forcibly publish widgets, circumventing the established reviewal process.
  • Unpublish: If the widget is published, you can take it out of production using this option.

Tip

Only unpublished widgets can be archived.

Tip

Widgets that are active in one or more pages of your site or channel cannot be unpublished. In order to unpublish a widget, you must first remove it from all pages.

Tip

Archived widgets do not appear in the main widget list or in the Custom widget selection in Page Builder. You can restore an archived widget by editing it and using the restore option in the upper right corner of the editing view.

Once a widget is published, it is available as a custom widget in the page builder.

Tip

To learn more about publication lifecycles in Modyo, review the Versioning section.

In the main work area you can see the following:

  • Code tabs: The Widget Builder has a JavaScript, CSS and HTML tab at your disposal to build your widgets.
  • Asset manager: Opens a modal that lists all account files and provides filters and searching. Clicking the image preview or file name opens an editor where you can resize/crop the image, and change attributes such as the title or alternate text. Selecting the copy icon provides you with a URL you can paste, and you can select the "Upload files" tab to upload files. You can learn more about By clicking on it, you will raise the file management modal, where you can filter and search the files you have uploaded in the File manager and copy its URL to use them in your widget. You can also upload new files from this modal.
  • Shortcuts helper: A small pop-up that displays useful keyboard shortcuts for the Widget Builder.
  • Snippets: Displays a list of custom snippets where you can copy their reference code and insert them in your widget.
  • Changes: A list of every "Save" state of this widget since it was last published. Click on any of these save states to change the content of the widget to that particular save state. If doing so, all your current changes will be lost.

Tip

To avoid losing any changes you currently have, be sure to save before jumping between save states. This way, you can always return to the most recently saved version in the Changes list.

Tip

If you publish a new version of your widget, the Changes list resets and erases all save states. This is because the new editable version now matches the version you just published. Saving new changes adds new save states until the next time you publish.

You can make use of Liquid in the Javascript, CSS, and HTML tabs in the widget builder. For more information check the associated Liquid documentation.

The Properties on the right contains the following fields:

  • Name: Use this field to update the name of your widget.
  • Tags: Use this field to add tags to your widget. Tagging a widget makes it easier to search and filter. As your digital channels scale in size and complexity, good tagging helps keep your channel management well organized.

Modyo CLI

The Modyo Command Line Interface (CLI) is a command line tool based in two principles acceleration and integration, and this principles has a command get and push respectively.

Introduction

First, you need to install the Modyo CLI globally on your local machine to have the modyo-cli command available, this will allow you to initialize a project with some Front end architectural decisions already taken, or use to initialize a widget from the catalog if you have access.

To install the modyo-cli globally you must use one of this options

  $ npm i -g @modyo/cli #via npm
  $ yarn global add @modyo/cli #via yarn

This command will make the command modyo-cli available on the terminal session globally

The available commands are get, push and help

modyo-cli (-v|--version|version)

Print the modyo-cli version

  $ modyo-cli (-v|--version|version)
  modyo-cli/3.0.6 darwin-x64 node-v12.13.1

modyo-cli help [COMMAND]

USAGE
  $ modyo-cli help [COMMAND]

ARGUMENTS
  get   Pull a widget from our catalog into a new directory
  help  Display help for modyo-cli
  push  Push widget to Modyo platform

Get a template for a project

The Modyo CLI is designed to work based on micro front-end architecture, and will accelerate the process of initialization of a widget, with modyo decisions.

modyo-cli get NAME [DIRECTORY]

In general, the get command is used to obtain a boilerplate widget. If you have a token provided by Modyo, the same command can be used to pull any of our premium widgets from our Widget Library.:

USAGE
  $ modyo-cli get NAME [DIRECTORY]

ARGUMENTS
  NAME       The name of the widget
  DIRECTORY  Name of directory to init

OPTIONS
  -f, --force       Override folder if exist
  -h, --help        Output usage information
  -x, --no-install  Don't install packages

EXAMPLE
  $ modyo-cli get name [directory]

there are some public widget names that can be accessed via this command

  EXAMPLE
    $ modyo-cli get modyo-widgets-template-vue [DIRECTORY] #to initialize a widget
    $ modyo-cli get modyo-widgets-project-vue [DIRECTORY] #to initialize a base project library

From this command and on you can continue using the widget like any other vue-cli widget.

modyo-cli push NAME

The push command is the one in charge of the integration principle, used to send the widget to the selected site in the modyo platform.

It will use an argument called name to upload the widget to the platform and some required flags like token site_base id or host to can identify the ®Modyo platform which host the widget and have an additional flag to avoid the manual process flow of widget publication.

USAGE
  $ modyo-cli push NAME

ARGUMENTS
  NAME  The name of the widget

OPTIONS
  -b, --build-command=build-command      [default: build] Build command in package.json
  -d, --build-directory=build-directory  [default: dist] Build directory path
  -h, --help                             Output usage information
  -i, --site-id=site-id                  Id of the site where the widget will be push
  -n, --site-host=site-host              Host of the site where the widget will be push
  -p, --publish                          Force widget publication
  -t, --token=token                      (required) Modyo Api token
  -u, --account-url=account-url          (required) URL of your ®Modyo account ex("https://account.modyo.com")
  -v, --version=8|9                      [default: 9] Version of Modyo platform

EXAMPLE
  $ modyo-cli push <NAME>

Many of the options can be defined as environment variables or inside of an .env file that is recommended to avoid the publication to the github registry because can contain some delicate information

MODYO_BUILD_DIRECTORY=buildDirectoryPath
MODYO_VERSION=version
MODYO_TOKEN=token
MODYO_ACCOUNT_URL=account-url
MODYO_SITE_ID=siteId
MODYO_SITE_HOST=siteHost
MODYO_BUILD_COMMAND=buildCommand
MODYO_REGEX_EXCLUDE=regexToExcludeFiles