Create and edit custom cards

The first step in creating or editing a ThoughtFarmer custom card is to navigate to the Admin panel: User interface section > Custom cards page.

The tables on the Custom cards page is your card and sub-application library. This shows every customization that is available on your intranet. These are separated out into 2 categories:

1. Page template cards
   • Cards that are added individually to a page or template. Most cards will end up here.
2. Global cards
   • Cards that run on every page of the intranet. These require code to be visible in the page's template. Please see the Custom Card API page for details.

Each table contains the following information about each card:

• Id: A unique card id is automatically generated when you create a card. This is the id you use to push a card you are working on locally to your Intranet.
• Name: The name of the card. If the card has a description, an info icon appears that you can click to display that information. You can also click the name to edit the code for the card.
• Modified by: Indicates who last modified this card. If it was last modified by the intranet system user or "bot", it is a built-in custom card provided by ThoughtFarmer.
• Date modified: Indicates when the card was last modified.
• Viewable by: When "Admins only" is checked it indicates the card is only able to be added to templates by admin users. Otherwise, anyone with edit permission on pages may utilize the card.
• Active: When active, this card will be available to be added to pages and all current instances will render. Deactivating a card will make it unavailable to add to pages. Any current templates using that card will also be set to inactive and not display.
• Action: Click the gear icon to open a menu with the actions below:
  • Edit card: Takes you to the template editor to change the code for the card.
  • Export card: Allows you to export the template to a zip file.
  • Replace card: Allows you to import an upgraded version or replacement for the current card.
  • View usage: Opens a modal that displays the number and names of unique pages and template layouts the card is used on. The page or template names are listed in the corresponding tab of the modal, clicking on a name will take you to that page or to a list of pages using that template layout.
  • Delete: Removes the card from the intranet including all instances currently added to page templates. NOTE: You cannot delete an active card. It must be deactivated first.

Import a card

Cards can be imported into your intranet. When you click on the Import custom card button at the top right of the page, a dialog will appear asking you to select the zip file containing the card to import. After selecting the zip file and clicking Upload, the card will be imported and appear in either the Page template cards table or Global cards table. The card automatically 'knows' what type it is depending on what it was originally created as. Don't forget to slide your card's toggle to Active and click Upgrade to newest version if you make any changes or add configuration!

Create a new card

Clicking the blue + Create page template card or + Create global card buttons at the bottom right of each table will take you to the custom card editor screen. This screen has a number of tabs and fields that allow you to modify the custom card. Learn more about your options below, or go to ThoughtFarmer development technologies for more information.

• Card name: The name of the card.
• Custom template Id: The unique card id
• HTML: This is the tab where any standard HTML is entered and is what the user sees when the card is run. (eg. Image tags, links, etc.)
• JavaScript: This is the tab where any JavaScript code that the card requires is entered. All code should be transpiled to plain old JavaScript.
• CSS: This is the tab where any CSS styling used by the card is entered. If you prefer, you can also write SASS directly in this tab, which will also be compiled on save.
• Details:
  • Description: This is a description of what the card does. It will show in the Manage cards admin page when the user clicks on the ? icon inline with the card title.
  • Default configuration: If there is information that you need to pass into the card when it is run, that goes here. The configuration must be in the JSON object format. E.g.:

    • { "customTitle": "The best page!", "adminsOnly": false }

  • Allow card configuration on edit page: If your card has per instance configuration, then this setting will allow for this to be configured separately for each instance when it is added to page template.
  • More information: This is a URL to a page with more information about this card.

Click Save when you finish creating the card.

Edit an existing card

Click the gear icon in the far right column in the row for the card you want to edit, and select Edit card from the menu that opens to go to the custom card editor screen. Also, if you click on the name of the card you will be brought straight to the editor. This screen has a number of fields that allow you to modify the page template card.

The available fields on this page are the same as those described above under the Create a new card heading, with the addition of one field:

• Version: A dropdown from which you can access a history of past changes made to the card, who made them, and when. Choosing an item from this dropdown reloads the page to show a read-only view of this version. To revert to this version, click the Revert button. Otherwise, click Cancel to return to the most recent version of the card.

Any custom cards that are available for free on the ThoughtFarmer Card Marketplace are managed by ThoughtFarmer and the HTML, JavaScript and CSS fields are not editable.

Click Save when you are finished editing the card**.

**NOTE: If you save a new version of a card and there are existing templates that have the card added, you will see a green banner at the top saying "{My Custom} card has been edited. Upgrade to this version now or later. Upgrade now." Clicking "Upgrade now" will push the update to all cards that are active on page templates.

Export an existing card

To make use of a card on another ThoughtFarmer installation, or to archive it outside of the application, you can export the card directly from the Cards page. In the Admin Panel: User interface section > Custom cards page, click on the gear icon to the right of the desired card. In the dropdown menu that opens, click Export card and save the generated zip file in the desired location on disk.

Upgrade your card with a new version

It is now easy to upgrade a card with an external zip file without any copy/pasting. It will be automatically added to all the page templates you have previously selected. Click the gear icon beside the card you wish to upgrade and click Replace card. This will bring up a modal where you can browse to your desired .zip file and upload it.

Global cards

Global cards have the same HTML, JavaScript, and CSS components as their page template counterparts. However, the code for these cards will be set to run globally and to bypass all per page template configuration. There is a special JavaScript API for placement of global cards on pages.