Skip to main content

Lesson 2 - Add a Custom Page

Next we will add a new custom page to your application.

In order to add a custom page to your application there are two things you must do:

  1. Create the page component that will be displayed when you navigate to the page
  2. Update your user config to display the page

Download the Custom Page#

  1. Download the custom page code by clicking here
  2. Extract the zip file
  3. Copy ItemsView.jsx into app/ipaCore/pageComponents

Read the pageComponent Code#

  1. Open the page in your IDE and examine the code.

It is a simple component that by default will display the page's handler from the user config. There are also a number of other template functions which we will complete in a later step to add the ability for the page to display your items from the Item Service.

Update Your User Config#

Add the Page Handler#

  1. In your IDE, open the 'Developer User Config' if you do not yet have it open
  2. Update the handlers section to match the below:
"handlers": {  "items": {    "title": "Items",    "icon": "fas fa-database fa-2x",    "shortName": "items",    "description": "Item Display",    "pageComponent": "ItemsView",    "path": "/items",    "config": {},    "scriptTypes": []  }},

This is a basic page handler. It specifies to the ipa-core framework information about the page you want to load.

  • title: The name of the page and what will be displayed in navigation user interfaces
  • icon: An icon that will appear alongside the title in navigation user interfaces. You can use font awesome version 5 icons or icons that you build and make available as part of your app
  • shortName: A short name for the page
  • description: A description of the page
  • pageComponent: The React component that should be loaded when the user navigates to the page. It is the page you downloaded and placed in app/ipaCore/pageComponents
  • path: The path that will appear in the browser's url when the user navigates to the page
  • config: Any configuration information you would like to provide to your page component
  • scriptTypes: A list of _userTypes for scripts that should be loaded when the user navigates to the page

We will see how the config and scriptTypes enables you to specify user group specific options and business logic in later lessons.

Add the Page to the Navigation Pane#

  1. Update the user config's groupedPages to match the below:
"groupedPages": {  "My Pages": {    "icon": "fas fa-database fa-2x",    "position": 1,    "pages": [      {        "page": "Items",        "handler": "items"      }    ]  }},

This will create a My Pages group of pages in the Navigation pane of the application and add your Items page to it. Notice that the Items page references the handler you created above.

Add the Homepage#

Once we have pages in the application we must specify a page as the homepage.

  1. Update the homepage section to match the below:
"homepage": {  "handler": "items"}

Commit Your Updated User Config#

  1. Save your user config
  2. In the Twinit IDE Extension right click on the user config and click 'Commit to New Version'
  3. Enter a commit message and click Save

View Your Page in the Web Client#

If your client is still running in your browser, you can now easily reload your user config by selecting 'Switch Project' in the top right hand menu of the application and then selecting your project again.

If your client is not running, run npm run watch to bring it up.

You should now see your Items page displayed in the My Pages group in the navigation pane and your page should be displaying the handler you have configured for your page.

first page nav A new group called My Pages displays containing your new page

first page page The new page displays the handler you configured for the page

As you can see, the handler which you configure in the user config is made available in the props of the pageComponent. In this way you can use the configuration of the page to alter the page. It allows you to create generic pages that can be configured to show different information and it allows you configure the page to behave differently based on the user group to which the user config is associated.

In the next step, we will enhance the page to display items in the Item Service.

Create Sample Item Service Data#

Next we will create some test data in your project for your application to use.

  1. Download the CreateTestData.zip by clicking here and extract it
  2. Add the 'Create Test Data.mjs' script to your project (right click script folder, select Create New Script, and copy paste the content of the downloaded script)
  3. Right click the script and click 'Run Script' and select 'Create Project Test Data'
  4. When prompted select the 'GraphTestData.xlsx' file

When the script completes your project will be populated with the sample data we will use with your custom page.

Display Sample Items on Your Page#

Open ItemsView.jsx in app/ipaCore/pageComponents.

You'll notice that a few template functions are provided. In this step you will complete those template functions to enable your page to show a select control listing the NamedUserCollections in your project and when a user selects one it will show the items in that NamedUserCollection.

Notice: When using ipa-core, it is not necessary to provide your ctx to the platform-api functions. The framework will manage this for you.

In the following steps you will be given the chance to write code to accomplish tasks on your own. Remember to use https://twinit.dev to look up anything you need. If you have issues, the completed code files are attached at the end of this lesson.

Get the NamedUserCollections in Your Project#

In the getCollections function uncomment the code that does these two things:

  1. Uses IafItemSvc.getAllNamedUserItems to fetch the NamedUserItems with _itemClass of 'NamedUserCollection'
  2. Sets the collections state to the result of the IafItemSvc.getAllNamedUserItems call

When a Collection is Set Current, Fetch its Items#

In the getItems function uncomment the code that does these things:

  1. Use IafItemSvc.getRelatedItems to fetch the items in collection with the _userItemId in currentCollection
  2. Set the items state to the result of the IafItemSvc.getRelatedItems call

Result#

When complete you should see a dropdown listing the Systems, System Elements, Spaces, Assets, and Alerts NamedUserCollections and the items in each should display on the page when you select them.

show items In addition to the handler, the page now displays a dropdown containing the various sample collections, and a list of items in the selected collection

Use the Handler to Configure Your Page#

Your page is currently hard coded to display the contents of any and all NamedUserCollections. But what if we wanted to allow for configuring which NamedUserCollections would be able to be displayed? In order to accomplish that we will utilize the config section of the handler in the user config.

To accomplish updating our page to be configurable we will do these things:

  1. Update our user config to provide the _userType to use when fetching NamedUserCollections
  2. Update our ItemsView pageComponent to use the handler.config to retrieve the _userType

Update Your User Config#

  1. In the Twinit IDE Extension, open the 'Developer User Config' from Twinit if you do not yet have it open
  2. Add a _userType config to the handlers config section as below:
"config": {  "_userType": "graph_system_els"},
  1. Save the user config and commit it to a new version (provide a commit message if desired)

Update the pageComponent#

  1. Update the getCollections function in itemsView.jsx to use props.handler.config._userType in the getRelatedItems query.
IafItemSvc.getAllNamedUserItems({query: {      _itemClass: 'NamedUserCollection',      _userType: props.handler.config._userType    }}).then((colls) => {      setCollections(colls)})
  1. Save the file

Result#

Note: You will need to reload your user config in the web client by clicking Switch Project in the menu in the top right hand corner (or logging out and back in) and then selecting your project again. If you do not, the page will not function correctly.

Now when you view your page in the application you should see the _userType configuration in the handler and the page should only display System Elements in the dropdown.

first page config The handler now displays the _userType config from the User Config, and only allows the 'System Elements' collection to be selected

Add a Second Instance of ItemsView#

Now that we have the ItemsView pageComponent using the handler's config, we can configure multiple instances of the same pageComponent displaying different types of data.

Update Your User Config#

  1. Open the Developer User Config in the Twinit IDE Extension
  2. Add the following to the handlers section
"spaces": {   "title": "Spaces",   "icon": "fas fa-database fa-2x",   "shortName": "dashboard",   "description": "Space Display",   "pageComponent": "ItemsView",   "path": "/spaces",   "config": {     "_userType": "graph_spaces"   },   "scriptTypes": []}
  1. Add the following to the pages array on your My Pages group of pages
{     "page": "Spaces",     "handler": "spaces"}
  1. Since we are adding a second page, update the title for the original page to be "System Elements"
  2. Save the user config and commit it to a new version

Result#

Note: You will need to reload your user config in the web client by clicking Switch Project in the menu in the top right hand corner (or logging out and back in) and then selecting your project again. If you do not, the page will not function correctly.

Now, without writing any code we have repurposed the same page to display different data utilizing the handlers config.

first page second nav A second instance of the same page now displays in the navigation group

first page second page The second instance of the page displays Spaces instead of System Elements

Using scriptTypes#

Not only can you use the handler config to alter and customize the application for your users but you can also use scripts to customize the business logic of your page for your users. In this lesson we will move the getItems code into a script and configure the itemsView to use the script to fetch items.

In the next steps we will:

  1. Create a new script to contain our getItems business logic
  2. Update the user config to include configuration for a button which will execute our new script when clicked
  3. Update our ItemsView to run the configured script when the button is clicked

Download the new Item Search Scripts.mjs script.

Create a Script to Search Items#

Using the Twinit IDE Extension, create a new script in your project. You can give it any name, short name, and description, but be sure to give it the _userType iss.

Copy and paste the contents of the attached Item Search Scripts.mjs into the new script, save the file, and commit it to a new version.

Open and read through the Item Search Scripts.mjs. It is relatively simple. It takes three fields in the input parameter.

  • input.userItemId: this is the _userItemId for the NamedUserCollection in which we want to search for items
  • input.field: this is the field to search on items in the NamedUserCollection
  • input.value: this is the value in the field we want to search for

Both input.field and input.value are optional. If neither is supplied all items will be returned.

Load Scripts Using scriptTypes#

Next we will configure both instances of the ItemsView pageComponent to load the script. Currently the scriptTypes array for both are empty. However, we can add the _userTypes of the scripts to the arrays to have our page load those scripts and make them available to be executed by our page.

In this case, we will have our page load the script with the _userType iss.

  1. Open the 'Developer User Config' in the Twinit IDE Extension
  2. In both the 'System Elements' and 'Spaces' handler, add "iss" to the scriptTypes array as below:
"scriptTypes": [    "iss"]

Add Search Configuration#

  1. Next add an additional configuration to the System Elements handler to enable search on the page, by adding the search configuration below:
"config": {    "_userType": "graph_system_els",    "search": {         "field": "system element name",         "script": "searchItems"    }},
  1. Then add the same configuration to the Spaces handler but instead provide 'name' in the field to search:
"config": {    "_userType": "graph_spaces",    "search": {         "field": "name",         "script": "searchItems"    }},
  1. Save and commit the user config to a new version

These configurations serve a number of purposes.

  • If the page finds config.search it will display a text search field and button
  • If the user types in a search term and clicks the button, the page will execute the searchItems script

Update Items View to Execute the Script#

Next we will update ItemsView to run the script. To do this we will use the ScriptHelper library.

ScriptHelper is a utility provided by ipa-core to make it easy to execute scripts on your page. The ScriptHelper.executeScript function accepts these parameters in this order:

  • scriptName: The name of the script to run. It must be a script either specified in a handler's scriptTypes or loaded explicitly with ScriptHelper.loadScript
  • operand: Any input to the script, usually a javascript object
  • scriptResVar: Deprecated option, no longer in use and will be removed in the future, pass null for now
  • ctx: Your context
  • callback: a function to receive asynchronous results from the script as it executes

To update ItemsView:

  1. At the top of the file uncomment the import of the ScriptHelper library
  2. In the getItems function, comment the existing code executing IafItemSvc.getRelatedItems
  3. In the getItems function, uncomment the code using ScriptHelper to execute the script
  4. Save the file

Read over these changes and understand how they work before continuing.

Result#

Note: You will need to reload your user config in the web client by clicking Switch Project in the menu in the top right hand corner (or logging out and back in) and then selecting your project again. If you do not, the page will not function correctly.

After reloading your user config, you should now see a new search box.

script type result 1 A search box now displays underneath the collection dropdown

  1. On the System elements page select the System Elements option, type in 'DUCTS' to the search box and click searchItems.

You should see two System Elements with the name 'DUCTS'.

script type result 2 The list of DUCT items is displayed

Why Use a Script?#

You may be asking yourself why use a script?

By using a script to define the business logic, we can now change the business logic for different user configs associated with different users. This lesson was a simple case, but by using a script we could adjust the search to do different things for different groups of users. For instance, we could have a search that only returns the Room system elements for some users, but a search that returns all System Elements for others.

The user config allows us to connect a user with the UI and the business logic for their role.