Maintainer: Nicolas Staub
npm install -g @nzz/q-cligit 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 linkQ commands will now use the local Q-cli.
To unlink, simply install Q-cli again globally:
npm install @nzz/q-cli -gTo use the q-cli in github actions there are special access tokens provided. You can find them in 1password (LivingDocs Public API Access Tokens).
There is an entire thread in basecamp on how this solution works.
Example code for a github action to update on all environments. You can check the functionality section if you only want to update a specific environment.
You will need to set the secrets in github unders settings > secrets & variables > actions > New repository secret
- name: Run Q cli
run: Q update-item
env:
Q_STAGING_SERVER: ${{ secrets.Q_STAGING_SERVER }}
Q_STAGING_ACCESSTOKEN: ${{ secrets.Q_STAGING_ACCESSTOKEN }}
Q_PRODUCTION_SERVER: ${{ secrets.Q_PRODUCTION_SERVER }}
Q_PRODUCTION_ACCESSTOKEN: ${{ secrets.Q_PRODUCTION_ACCESSTOKEN }}
Once Q cli installed one can start Q dev server by running:
Q serverWith 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
-por--portas 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-bor--tool-base-urlwhile starting Q dev server.
Q server -b http://localhost:4000- Default target is
nzz_chand can be overwritten by using-tor--target.
Q server -t your_target- One can optionally specify a path to a config file by using option
-cor--config, e.g.
Q server -c ./config-file-name.jsA 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;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
-dor--dir
Q new-server my-server-name -d my-server-directoryOnce 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
-dor--dir
Q new-tool my-tool-name -d my-tool-directoryOnce 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
-dor--dir
Q new-custom-code my-project-name -d my-project-directoryOnce 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
-dor--dir
Q new-et-utils-package package-name -d my-project-directoryNew utility package projects should only be created inside the ed-tech-utilities repository.
The Q cli can copy and/or update 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
-cor--config. By default theupdate-itemcommand will look for a config file calledq.config.jsonin the current directory
Q update-item -c [path]- Items of a specified environment can be updated by using the option
-eor--environment. By default theupdate-itemcommand 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
-ror--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, whereENVis the uppercase version of the environment name.
Q_TEST_SERVER=[server_route] Q_TEST_USERNAME=[username] Q_TEST_PASSWORD=[password] Q update-itemor
Q_TEST_SERVER=[server_route] Q_TEST_ACCESSTOKEN=[accessToken] Q update-itemThe 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"]
]
}
}
]
}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
-cor--config. By default thecopy-itemcommand will look for a config file calledq.config.jsonin the current directory
Q copy-item -c [path]- Items of a specified environment can be updated by using the option
-eor--environment. By default thecopy-itemcommand 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
-ror--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, whereENVis the uppercase version of the environment name.
Q_TEST_SERVER=[server_route] Q_TEST_USERNAME=[username] Q_TEST_PASSWORD=[password] Q update-itemor
Q_TEST_SERVER=[server_route] Q_TEST_ACCESSTOKEN=[accessToken] Q update-itemThe 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.
}
}
]
}
}
]
}Copyright (c) Neue Zürcher Zeitung.
This software is licensed under the MIT License.