Tutorial | Creating a “Top Blog Posts” Dashboard Page Using the Wix CLI

One of the ways that 3rd-party developers can extend the Wix ecosystem is by creating apps that appear in the site owner’s dashboards. These apps can work with data from the site they’re installed on, such as Content Management System (CMS) data and business solution data (like CRM).

This tutorial explains how to create a dashboard page that displays a site’s most liked and most viewed blog posts.

We use the following technologies to create the app:

• Wix CLI: Used to create, test, and deploy the app.
• JavaScript SDK: Used to retrieve blog post data from the site.
• Wix Design System: Used to display data on the dashboard page.

The end result will look like this:

We use the following steps to build the “Top Blog Posts” dashboard page:

1. Initialize the app
2. Set up the dashboard page
3. Add permissions
4. Set up Wix Blog
5. Develop the app
6. Display the top posts in the dashboard
7. Test the app
8. Build and deploy the app

Before you begin

Before getting started, make sure that:

• You install Node.js (v18.16.0 or higher).
• You install npm or yarn
• You're logged into your Wix Developer account. If you don't already have one, sign up for a Wix Developer account.

Step 1 | Initialize the app

We use the Wix CLI to initialize our "Top Blog Posts" app. In the process of initializing our app, the Wix CLI automatically:

• Creates a new app in the Custom Apps page of your Wix Studio workspace.
• Sets up a new folder for your app in your local file system. The folder includes:
  • A src folder containing initial boilerplate code for an app with a dashboard page.
  • A package.js file containing your app dependencies.
• Creates a local Git repository for your app.
• Prompts you to set up a development site for testing your app.

To initialize the app:

1. Open a terminal and navigate to the folder where you want to create your app.

2. Run the following command using npm:

   Copy

3. Select A new Wix App.

4. Enter a name for your app. Let’s name our app Top Blog Posts.

5. The CLI prompts you to choose a development site (test site), which you’ll use throughout this tutorial to run and test your app. You can choose an existing Wix site as your development site, or create a new one. Let’s Create a new Development Site. The newly-created development site is automatically named something like Dev Site 5x2043, and can be found in your Wix account’s list of sites.

6. Follow the prompts to open the development site on your default browser. If the browser doesn’t open, install your app on your test site manually and skip the next step.

7. Click Agree & Add to install your app on your development site.

8. Back in the terminal, press Enter to select the default folder name (top-blog-posts) for your app in your local file system.

You now have a new app in the Custom Apps page, a new folder in your local file system, and a local Git repository for developing and testing your app.

Step 2 | Set up the dashboard page

Now that you’ve initialized your app, you can run a local development server to see the app in action, and view local changes as you develop your app. The local development environment runs the app and its initial boilerplate code on the development site that you chose in the previous step.

To run a local development server for your app:

1. Navigate to your newly-created folder for your app.

   Copy

2. Run the following command using npm:

   Copy

3. Press 1 to open the local environment in your browser. Your development site’s dashboard opens, and you can see your newly-created app’s dashboard page in the left sidebar. We add the content of our app’s dashboard page in the next step.

Your app is now running on your development site. As you develop your app, any changes made to your app’s code are reflected in real time on your development site.

Step 3 | Add permissions

In this step, we'll show how to add permissions for the app. We use the queryPosts() and getPostMetrics() functions in the Wix SDK’s Blog API to get a list of all posts and post metrics. Then we use React code to display the most liked and viewed posts on our dashboard page.

To use the queryPosts() and getPostMetrics() functions, we need to give our app permission in your app's dashboard. Let’s first look for the permission that we need in the Permission Scopes section of the queryPosts() function’s page.

The Permission Scopes section reads that we must have one of the permission scopes on the list. In our example, we choose the Manage Blog permission scope.

The same is for getPostMetrics(). Let's choose the Manage Blog permission scope.

To add permissions for the app to request upon installation:

1. Go to your app's dashboard.
2. Click Permissions in the left sidebar.
3. For each permission scope:
   1. Click Add Permissions.
   2. Enter the permission scope's name in the Search by name or ID field.
   3. Check the permission scope's checkbox under Choose Permission Scopes.
   4. Click Save.

When a site owner installs the app, Wix prompts them to grant the necessary permissions.

Step 4 | Set up Wix Blog

Before you can start coding, you need to set up Wix Blog on your site and app:

1. Install the Wix Blog app on your test site. You can create some new blog posts, or use the sample ones provided by Wix.

   Note: Make sure to add Wix Blog in both the Dashboard and the Editor.

2. Once you install the app, publish the site and “like” one of the posts. You can find the blog at https://{your-site-url}/blog.
3. In your test site dashboard, select Apps > Manage Apps from the sidebar.
4. Delete your app from the site.
5. Open your app’s dashboard.
6. Select Test Your App > Dashboard. Select your test site in the Site Selector. Follow the prompts to reinstall the app and approve the new permissions.

   Note: You'll be prompted to create an extension before testing the app. Ignore this prompt and click Test Your App.

Step 5 | Develop the app

Next, we will use the JavaScript SDK to retrieve blog data from the test site.

Create a code file for your SDK code

Before starting to write code for the SDK, set up a file for your code and import the necessary SDK modules. Your code will use the sdk, blog, and dashboard-sdk modules. dashboard-sdk is preinstalled by the CLI.

1. Create a file named blog-utils.js in the src > dashboard > pages directory of your app’s repo.

2. In your IDE terminal, run the following commands:

   Copy

Create an SDK client

Next, create an SDK client that you can use to make authorized SDK calls. You can do this using the createClient() function from the sdk module. When you create an SDK client you have to pass in some settings:

• Authorization Strategy: This tells the client how to authorize the calls it makes to the SDK. In this case, pass the OAuthStrategy() function from the sdk module. This configures the client to make SDK calls on behalf of your app.

• Modules: The SDK submodules you want to call with the client. In this case, pass in the posts submodules from the blog module.

Paste the following code into your code file to import modules and create a new SDK client:

Retrieve blog data

Finally, use the blog module in the SDK to retrieve the data you need.

1. Create an async function called getTopBlogPosts in your code file.
2. Use the queryPosts() function to find the posts with the most likes and views. The query allows you to sort the posts in descending order based on likes and views. Call this function twice, once for likes and once for views.
3. Extract the first item IDs from the result and save them as mostLiked and mostViewed variables.
4. Use the getPostMetrics() function to retrieve the post metrics by passing the ID of the post. These metrics include likes and views. Save these metrics as mostLikedMetrics and mostViewedMetrics variables.
5. Your function should return an object with two keys, mostViewed and mostLiked. The value for each key should be an object containing the post data and the likes and views respectively of the highest-ranking posts.

Paste the following code into your code file:

Finally, your blog-utils.js file should look like this:

Step 6 | Display the top posts in the dashboard

Now that we have the blog data, we can use the Wix Design System to display it on a dashboard page. The app framework created by the CLI includes the code for a sample dashboard page. We can use that code as the basis for a dashboard page.

Set up the dashboard code files

1. Open the page.tsx file.

2. Delete all the import statements and paste in the following ones:

   Copy

3. In the return statement for the Index() component, delete everything in between the <WixDesignSystemProvider> tags.

When you’re done, your file should look like this:

Prepare blog data for display

Next, get your blog data ready to display on your dashboard page. This code goes below the import statements on your page.tsx file:

1. Define the interfaces for viewed and liked blog posts.

   Copy

2. In the Index() component use React hooks to access the data.

   Copy

3. Add a loader that displays while data are loading.

   Copy

Create the page structure

Next, add React components from the Wix Design System to create the page structure.

1. Add nested components between the <WixDesignSystemProvider> tags in the return statement for the Index() component. Structure your components to match the following diagram. Wrap <Text> components in <div> tags so that they each display on a different line.

1. Add the following variables to the opening tag of the Box component to ensure the cards inside it display correctly:

When you’re done, your Index() component should look like this:

Add content to the page

Add static text, dynamic text, and other content to your Design System components. In some cases, text is added between the component’s opening and closing tags. In other cases, the text is passed into the component as a variable.

1. Pass these variables to the Heading components inside the Card.Header components:

   Copy

2. Pass these variables to the Heading components inside the Car.Content components:

   Copy

3. Add an onClick event handler to the Button component in the page header actions bar. Set the variable to this function:

   Copy

When you’re done, your Index() function should look like this:

Step 7 | Test the app

Now that the app’s code is ready, you can test it locally using the Wix CLI.

The finished code sample should look like this:

To test your app, do the following:

1. Run a local development server for your app. Your app’s dashboard page will now look like this:
2. Click the button to show top blog posts.
3. If things don’t look right, open your browser’s developer tools and check for errors in the console.

Step 8 | Build and deploy the app

After testing your app and seeing that it works as expected, you can:

• Create a public preview of your app,
• Build your app
• Deploy your app.