C8y front end apps: Project Setup - m-kostira/angularjs-notes GitHub Wiki

For more complete walkthrough, see: https://cumulocity.com/guides/web/web-sdk-for-plugins/#hello-world

For an example, see
https://bitbucket.org/mihail_kostira/managed-object-browser/
https://bitbucket.org/mihail_kostira/managed-object-browser/commits/744d36d709ec0246e43dad9633ebb5e38eaf7fa2

• Creating a new folder with an arbitrary name.
• Creating a "cumulocity.json" file inside this folder, representing our application manifest.
• Running the command "npm init" to create a new "package.json" file.
• Running the command "c8y install latest" to get the latest core plugins.

(the "cumulocity.json" file inside our root folder) with information about our Cumulocity application, such as its name, key, URL and dependencies. NB if changing noAppSwitcher property value, you need to redeploy the app (c8y deploy:app <contextPath>) for the change to take effect (even when testing with c8y server!)

$ c8y deploy:app <appContextPath>
You will be asked for the name and base url of your tenant, as well as your username and password. After deploying your application, it appears in the "Own applications" menu of the "Administration" application.

To run your application locally, just run
$ c8y server
Additionally, you can pass options:

-u https://tenant.cumulocity.com with the instance as parameter where you want your api calls to be proxied to, -t examples or -t targets/examples.json to use specific target file, e.g. if you want to test your plugins inside one of the standard applications and you have defined your target file as in the example:

{
  "name": "Examples",
  "comment": "Release with additional example plugins",
  "replaceImports": {
    "core/c8yBranding": "myapplication/myBranding" 
  },
  "applications": [
    {
      "contextPath": "administration",
      "addImports": [
        "myapplication/weatherAdmin"
      ]
    }
  ]
}

NB: it seems the -target option is required:
$ c8y server -u https://mkostira.cumulocity.com -t targets/example.json
Also $ c8y deploy:app will actually build, create and upload the app, not just create it in the tenant.

Below is a target file that adds the mo-browser plugin from the managed-object-browser app to the administration application. The managed-object-browser app does NOT need to be deployed in advance.

{
  "name": "Examples",
  "comment": "Release with additional example plugins",
  "applications": [
    {
      "contextPath": "administration",
      "addImports": [
        "managed-object-browser/mo-browser"
    ]
    }
  ]
}

See the full example at https://bitbucket.org/mihail_kostira/managed-object-browser/commits/744d36d709ec0246e43dad9633ebb5e38eaf7fa2

To deploy a target file, you have to execute $ c8y deploy:target [targetFile]

NB If you modify one of the default apps, e.g. administration/cockpit, you can reset it by going to administration->applications->own applications and deleting this application. It will now appear only in subscribed applications.

So to add a plugin to our application, we have to

• Create a "plugins" folder in our project
• Create a folder named "myplugin" inside the "plugins" folder.
• Create "cumulocity.json" file inside the "myplugin" folder, representing our plugin manifest.
• Create a "views" folder inside the "myplugin" folder.
• Create "myplugin/views/hello.html" representing the view of our plugin
• Create "myplugin/hello.module.js" for the module
• Create "myplugin/hello.config.js" for the config
• Create "myplugin/hello.controller.js" for the controller

$ c8y build:app [appContextPath] [outputFolder]
Builds the application to the specified folder (./build by default). Inside the outputFolder you will find a directory named [appContextPath] and a zip file [appContextPath].zip. This zip file can then be uploaded in the "Administration" application. If you omit appContextPath the contextPath will be read from the "cumulocity.json" file at the path where the command was executed.
The build process for an app includes the following steps:

• Copy a built version of each plugin defined in the imports list.
• Assemble all the localization files available in each plugin and assemble them in a single .json and .po file for each available language.
• Generate an index.html.
• Copy the application manifest.
• Create a zip file with the above contents.

$ c8y build:plugin <pluginName> [outputFolder]
Builds the plugin to the specified folder (./build by default). Inside the outputFolder you will find a directory named [pluginName] and a zip file [pluginName].zip. This zip file can be uploaded in the "Administration" interface and added to any application.

The build process for plugins includes the following steps:

• Annotate angular functions with $inject. (Using ng-annotate). [This seems to take care of /* @ngInject */]
• Replace the :::PLUGIN_PATH::: by the proper strings.
• Transform every html file to be included via $templateCache.
• Concatenate and minify all the defined js files in the manifest (using UglifyJS 2).
• Compile all the less files.
• Concatenate and minify all the css and result of the less files.
• Copy all the files defined in 'copy' in the manifest.
• Copy all the localization files that may be available inside locales folder inside the plugin.
• Copy the plugin manifest.
• Create a zip file with the above contents.

$ c8y deploy:app <appContextPath>
Builds all the plugins, assembles the application and uploads it to the defined tenant. If the app doesn't yet exist on the remote instance it will be automatically created.

You can also add or replace plugins in the core applications by specifying a target .json file. This file is not restricted in its name or path. For more details, see https://cumulocity.com/guides/web/web-sdk-for-plugins/#hello-world

{
    "name": "Examples",
    "comment": "Release with additional example plugins",
    "applications": [
        {
            "contextPath": "administration",
            "addImports": [ "myapplication/myplugin" ]
        }
    ]
}