Q cli

Maintainer: Nicolas Staub

Table of contents

• Installation
• Development
• Functionality
• License

Installation

npm install -g @nzz/q-cli

to the top

Development

git clone [email protected]:nzzdev/Q-cli.git
cd Q-cli
nvm use
npm install

For testing local changes of Q-cli, one can link the local package to the global installation of Q-cli:

cd Q-cli
npm link

Q commands will now use the local Q-cli.

To unlink, simply install Q-cli again globally:

npm install @nzz/q-cli -g

to the top

Functionality

Q dev server

Once Q cli installed one can start Q dev server by running:

Q server

With the Q dev server running one can now test a tool with fixture data. Of course the respective tool has to be started as well.

• Default port is 5000 and can be overwritten by using -p or --port as option while starting Q dev server:

Q server -p 4001

• Default base url of the tool your are currently developing is http://localhost:3000, this can also be changed by passing the option -b or --tool-base-url while starting Q dev server.

Q server -b http://localhost:4000

• Default target is nzz_ch and can be overwritten by using -t or --target.

Q server -t your_target

• One can optionally specify a path to a config file by using option -c or --config, e.g.

Q server -c ./config-file-name.js

A config file should export an async function returning a config object. The config object has to contain an object for each target. Target objects can contain

• tool specific additionalRenderingInfo like additional stylesheets and scripts to load
• a target specific context which can also contain stylesheets, scripts or background information
• toolRuntimeConfig containing information which a tool might need at runtime Config file example:

async function getConfig() {
  return {
    nzz_ch: {
      // target name
      additionalRenderingInfo: {
        // additionalRenderingInfo is tool based
        stylesheets: [
          {
            url: "https://service.sophie.nzz.ch/bundle/sophie-q@1,sophie-font@1,sophie-color@1,sophie-viz-color@1,[email protected]",
          },
        ],
      },
      context: {
        // context is target based
        stylesheets: [
          {
            url: "https://context-service.st.nzz.ch/stylesheet/all/nzz.ch.css",
          },
        ],
        background: {
          color: "#fff",
        },
      },
      toolRuntimeConfig: {
        displayOptions: {
          hideTitle: true,
        },
      },
    },
  };
}

module.exports = getConfig;

Creating new Q server implementation

Once Q cli is installed one can create the skeleton of a Q server implementation by executing

Q new-server my-server-name

• The directory name where the server implementation is being created defaults to the server name and can be overwritten by using option -d or --dir

Q new-server my-server-name -d my-server-directory

Creating new tool

Once Q cli is installed one can create the skeleton of a new tool by executing

Q new-tool my-tool-name

• The directory name where the new tool is being created defaults to the tool name and can be overwritten by using option -d or --dir

Q new-tool my-tool-name -d my-tool-directory

Creating new custom code project

Once Q cli is installed one can create the skeleton of a new custom code project by executing

Q new-custom-code my-project-name

• The directory name where the new custom-code project is being created defaults to the project name and can be overwritten by using option -d or --dir

Q new-custom-code my-project-name -d my-project-directory

Creating new ed-tech utility package project

Once Q cli is installed one can create the skeleton of a new ed-tech utility package project by executing

Q new-et-utils-package package-name package-author package-description

• The directory name where the new ed-tech utility package project is being created defaults to the project name and can be overwritten by using option -d or --dir

Q new-et-utils-package package-name -d my-project-directory

Notes

New utility package projects should only be created inside the ed-tech-utilities repository.

Q item actions

The Q cli can copy and/or update existing Q items.

Updating existing Q items

Once Q cli installed one can update one or many Q items by executing:

Q update-item

• The path to the config file can be set by using option -c or --config. By default the update-item command will look for a config file called q.config.json in the current directory

Q update-item -c [path]

• Items of a specified environment can be updated by using the option -e or --environment. By default the update-item command updates all item specified in the config file

Q update-item -e [env]

• Stored configuration properties like Q-Server url or access tokens can be reset by using option -r or --reset

Q update-item -r

• Credentials can be provided as environment variables to avoid user prompts. The variable names are Q_ENV_SERVER, Q_ENV_USERNAME, Q_ENV_PASSWORD, Q_ENV_ACCESSTOKEN, where ENV is the uppercase version of the environment name.

Q_TEST_SERVER=[server_route] Q_TEST_USERNAME=[username] Q_TEST_PASSWORD=[password] Q update-item

or

Q_TEST_SERVER=[server_route] Q_TEST_ACCESSTOKEN=[accessToken] Q update-item

The config file has to follow this json-schema. This schema will be extended by the respective tool schema of your Q item. Here's an example:

{
  "items": [
    {
      "environments": [
        // "environments" references the desired q items to be updated, at least 1 environment is required
        {
          "name": "production",
          "id": "6dcf203a5c5f74b61aeea0cb0eef7e0b" // Id of your q item in the production environment
        },
        {
          "name": "staging",
          "id": "6dcf203a5c5f74b61aeea0cb0ef2ca9f" // Id of your q item in the staging environment
        }
      ],
      "item": {
        // The actual content you want to update for your referenced q items listed in "environments"
        "title": "Der Konsum in der Schweiz springt wieder an",
        "subtitle": "Wöchentliche Ausgaben mittels Bankkarten in Mio. Fr. im Jahr 2020, zum Vergleich 2019",
        "data": [
          // "data" represents the data table of your q item inside the q-editor
          ["Datum", "2020", "2019"],
          ["2020-01-06", "690004302", "641528028"],
          ["2020-01-13", "662122373", "617653790"],
          ["2020-01-20", "688208667", "654303249"]
        ]
      }
    }
  ]
}

Copy existing Q items

Once Q cli installed one can copy one or many Q items by executing:

Q copy-item

• The path to the config file can be set by using option -c or --config. By default the copy-item command will look for a config file called q.config.json in the current directory

Q copy-item -c [path]

• Items of a specified environment can be updated by using the option -e or --environment. By default the copy-item command updates all item specified in the config file

Q copy-item -e [env]

• Stored configuration properties like Q-Server url or access tokens can be reset by using option -r or --reset

Q copy-item -r

• Credentials can be provided as environment variables to avoid user prompts. The variable names are Q_ENV_SERVER, Q_ENV_USERNAME, Q_ENV_PASSWORD, Q_ENV_ACCESSTOKEN, where ENV is the uppercase version of the environment name.

Q_TEST_SERVER=[server_route] Q_TEST_USERNAME=[username] Q_TEST_PASSWORD=[password] Q update-item

or

Q_TEST_SERVER=[server_route] Q_TEST_ACCESSTOKEN=[accessToken] Q update-item

The config file has to follow this json-schema. This schema will be extended by the respective tool schema of your Q item. Here's an example:

{
  "items": [
    {
      "environments": [
        {
          "name": "production",
          "id": "6dcf203a5c5f74b61aeea0cb0eef7e0b" // Id of your q item in the production environment
        },
        {
          "name": "staging",
          "id": "6dcf203a5c5f74b61aeea0cb0ef2ca9f" // Id of your q item in the staging environment
        }
      ],
      "item": {
        "title": "Russische Angriffe auf die Ukraine",
        "subtitle": "Verzeichnete Angriffe in der ganzen Ukraine",
        "files": [
          // Adds or overwrites the listed files in your q item
          {
            "loadSyncBeforeInit": false, // Has to be set for the file upload to work
            "file": {
              "path": "./angriffsFlaechen.json" // Your local path to your file. The path is relative to where you execute the command.
            }
          }
        ]
      }
    }
  ]
}

to the top

License

Copyright (c) Neue Zürcher Zeitung.

This software is licensed under the MIT License.