Documentation

Custom card dev tools

Grunt command line tools for developing and deploying ThoughtFarmer Custom cards.

Installation:


Getting started:
First set up a default site. All commands will use this site unless otherwise specified by --site=siteName or just the flag -siteName
grunt sites:add
Be sure to name the site "default"

 

Manage sites

grunt sites:add
Will ask for:
  • name: the identifier for the site when using --site=siteName or just the flag -siteName
  • URL: the base URL for the site
  • username: yup, you guessed it
  • password: the corresponding password
  • applicationId: Found in the ThoughtFarmer Admin Panel --> Configuration Settings --> api.ApplicationCodes setting. You can just use the "Identifier" value for "General" (e.g. "UDFOISDDF........NFDHNW").
No passwords are stored in the config.json for the working directory. Instead a token will be fetched and stored after the site has been validated.
 
grunt sites:list
Shows all the configured sites

 
grunt sites:delete --site=siteName
OR 
grunt sites:delete -siteName
Deletes the site with the specified name in the --site option. 

 
grunt auth-test --site=siteName
OR
grunt auth-test -siteName
Will test the authentication with the specified site. If no site specified will use "default".  
 

Manage cards


 To configure and create a new card run the following from the root working directory.
grunt newcard

The command will ask for:
  • name: name of the card
  • Use JSX?: If this is a React card then say yes.
  • ID for site: This is the custom template ID of this card for the specified site. This question will be asked for every site configured. If you do not wish to add an ID for a specific site just hit enter. To configure IDs of a card for specific sites later you can run grunt configure.
Once completed the command will create a folder and files matching the name. This will include:
  • ./name/name.cshtml
  • ./name/name.js
  • ./name/name.jsx (if you said yes to JSX)
  • ./name/name.css
  • ./name/GruntFile.js - this file should not be modified and is only to allow for running grunt commands from the child folder.
  • ./name/config.json - this file contains id to site mappings for this card.
  
// from the root working directory
grunt configure --folder=cardName

// from the folder itself grunt configure


The command will ask for:
  • ID for site: This is the custom template ID for the specified site. It will ask this question for every configured site. You can keep an existing value, or skip an unused value just be hitting enter. Otherwise, enter the ID to associate it for this card for the site. 
 

Develop cards

All commands below can be run from the main root directory. If they are then you must specify the following command line parameters if required.

--folder=cardname
--site=name
--id=customPortletTemplateId

NOTE: It is recommended instead to change your working directory to the folder of the card you are working on. The folder will automatically be designated and the id parameter will automatically be assigned depending on the configuration for the specific card. All you need to do is specify the site or leave empty to use the 'default' site.
 

Examples

Running from the root working directory and deploying a specific card to the default site, using the card's configured id:
grunt deploy --folder=cardName
Running the same command from the folder ./cardName:
grunt deploy
Deploying from the folder ./cardName to a specific site called "dev" (not default):
grunt deploy --site=dev
OR
grunt deploy -dev
 

Commands

grunt compile-jsx
Required parameters: folder
Will transpile the file ./cardname/cardname.jsx to /cardname/cardname.js

 
grunt check-js 
Required parameters: folder
Will ESLint the file ./cardname/cardname.js using the options as set in the .eslintrc

 
grunt check-jsx 
Required parameters: folder
Will ESLint the file ./cardname/cardname.jsx using the options as set in the .eslintrc

 
grunt push 
Required parameters: folder, site, id
Will push all the contents of the ./cardname folder to the card with the id at the site specified (default if not). No upgrade called so the live card at the site will remain unchanged. Use this to get your updates to the server without making live changes.

 
grunt upgrade
Required parameters: folder, site, id
Will upgrade the portlet with the id at the site specified (default if not). For use when there is already a newer version on the server that is not yet set as the latest version. 

 
grunt deploy-js 
Required parameters: folder, site, id
Will  push all the contents of the ./cardname folder and upgrade the portlet with the id at the site specified (default if not).
 
grunt deploy 
Required parameters: folder, site, id
Will transpile the file ./cardname/cardname.jsx to /cardname/cardname.js and then push all the contents of the ./cardname folder and upgrade the portlet with the id at the site specified (default if not).