Q cli
Maintainer: Nicolas Staub
Table of contents
Installation
npm install -g @nzz/q-cli
Development
git clone git@github.com: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
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,sophie-input@1.css",
},
],
},
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 theupdate-item
command will look for a config file calledq.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 theupdate-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
, whereENV
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 thecopy-item
command will look for a config file calledq.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 thecopy-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
, whereENV
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.
}
}
]
}
}
]
}
License
Copyright (c) Neue Zürcher Zeitung.
This software is licensed under the MIT License.