feat: add tour for list pages (#2243)

web/src/App.js

@@ -89,6 +89,7 @@ import ThemeSelect from "./common/select/ThemeSelect";
 import OrganizationSelect from "./common/select/OrganizationSelect";
 import {clearWeb3AuthToken} from "./auth/Web3Auth";
 import AccountAvatar from "./account/AccountAvatar";
+import OpenTour from "./common/OpenTour";
 
 const {Header, Footer, Content} = Layout;
 
@@ -379,6 +380,7 @@ class App extends Component {
               });
             }} />
           <LanguageSelect languages={this.state.account.organization.languages} />
+          <OpenTour />
           {Setting.isAdminUser(this.state.account) && !Setting.isMobile() &&
             <OrganizationSelect
               initValue={Setting.getOrganization()}

web/src/BaseListPage.js

@@ -13,11 +13,12 @@
 // limitations under the License.
 
 import React from "react";
-import {Button, Input, Result, Space} from "antd";
+import {Button, Input, Result, Space, Tour} from "antd";
 import {SearchOutlined} from "@ant-design/icons";
 import Highlighter from "react-highlight-words";
 import i18next from "i18next";
 import * as Setting from "./Setting";
+import * as TourConfig from "./TourConfig";
 
 class BaseListPage extends React.Component {
   constructor(props) {
@@ -33,6 +34,7 @@ class BaseListPage extends React.Component {
       searchText: "",
       searchedColumn: "",
       isAuthorized: true,
+      isTourVisible: TourConfig.getTourVisible(),
     };
   }
 
@@ -41,14 +43,23 @@ class BaseListPage extends React.Component {
     this.fetch({pagination});
   };
 
+  handleTourChange = () => {
+    this.setState({isTourVisible: TourConfig.getTourVisible()});
+  };
+
   componentDidMount() {
     window.addEventListener("storageOrganizationChanged", this.handleOrganizationChange);
+    window.addEventListener("storageTourChanged", this.handleTourChange);
     if (!Setting.isAdminUser(this.props.account)) {
       Setting.setOrganization("All");
     }
   }
 
   componentWillUnmount() {
+    if (this.state.intervalId !== null) {
+      clearInterval(this.state.intervalId);
+    }
+    window.removeEventListener("storageTourChanged", this.handleTourChange);
     window.removeEventListener("storageOrganizationChanged", this.handleOrganizationChange);
   }
 
@@ -144,6 +155,37 @@ class BaseListPage extends React.Component {
     });
   };
 
+  setIsTourVisible = () => {
+    TourConfig.setIsTourVisible(false);
+    this.setState({isTourVisible: false});
+  };
+
+  getSteps = () => {
+    const nextPathName = TourConfig.getNextUrl();
+    const steps = TourConfig.getSteps();
+    steps.map((item, index) => {
+      if (!index) {
+        item.target = () => document.querySelector("table");
+      } else {
+        item.target = () => document.getElementById(item.id) || null;
+      }
+      if (index === steps.length - 1) {
+        item.nextButtonProps = {
+          children: TourConfig.getNextButtonChild(nextPathName),
+        };
+      }
+    });
+    return steps;
+  };
+
+  handleTourComplete = () => {
+    const nextPathName = TourConfig.getNextUrl();
+    if (nextPathName !== "") {
+      this.props.history.push("/" + nextPathName);
+      TourConfig.setIsTourVisible(true);
+    }
+  };
+
   render() {
     if (!this.state.isAuthorized) {
       return (
@@ -161,6 +203,17 @@ class BaseListPage extends React.Component {
         {
           this.renderTable(this.state.data)
         }
+        <Tour
+          open={this.state.isTourVisible}
+          onClose={this.setIsTourVisible}
+          steps={this.getSteps()}
+          indicatorsRender={(current, total) => (
+            <span>
+              {current + 1} / {total}
+            </span>
+          )}
+          onFinish={this.handleTourComplete}
+        />
       </div>
     );
   }

web/src/PermissionListPage.js

@@ -110,11 +110,12 @@ class PermissionListPage extends BaseListPage {
 
     return (
       <Upload {...props}>
-        <Button type="primary" size="small">
+        <Button id="upload-button" type="primary" size="small">
           <UploadOutlined /> {i18next.t("user:Upload (.xlsx)")}
         </Button></Upload>
     );
   }
+
   renderTable(permissions) {
     const columns = [
       // https://github.com/ant-design/ant-design/issues/22184
@@ -361,7 +362,7 @@ class PermissionListPage extends BaseListPage {
           title={() => (
             <div>
               {i18next.t("general:Permissions")}&nbsp;&nbsp;&nbsp;&nbsp;
-              <Button style={{marginRight: "5px"}} type="primary" size="small" onClick={this.addPermission.bind(this)}>{i18next.t("general:Add")}</Button>
+              <Button id="add-button" style={{marginRight: "5px"}} type="primary" size="small" onClick={this.addPermission.bind(this)}>{i18next.t("general:Add")}</Button>
               {
                 this.renderPermissionUpload()
               }

web/src/ProviderListPage.js

@@ -241,7 +241,7 @@ class ProviderListPage extends BaseListPage {
           title={() => (
             <div>
               {i18next.t("general:Providers")}&nbsp;&nbsp;&nbsp;&nbsp;
-              <Button type="primary" size="small" onClick={this.addProvider.bind(this)}>{i18next.t("general:Add")}</Button>
+              <Button id="add-button" type="primary" size="small" onClick={this.addProvider.bind(this)}>{i18next.t("general:Add")}</Button>
             </div>
           )}
           loading={this.state.loading}

web/src/ResourceListPage.js

@@ -76,7 +76,7 @@ class ResourceListPage extends BaseListPage {
     return (
       <Upload maxCount={1} accept="image/*,video/*,audio/*,.pdf,.doc,.docx,.csv,.xls,.xlsx" showUploadList={false}
         beforeUpload={file => {return false;}} onChange={info => {this.handleUpload(info);}}>
-        <Button icon={<UploadOutlined />} loading={this.state.uploading} type="primary" size="small">
+        <Button id="upload-button" icon={<UploadOutlined />} loading={this.state.uploading} type="primary" size="small">
           {i18next.t("resource:Upload a file...")}
         </Button>
       </Upload>

web/src/SystemInfo.js

@@ -12,10 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import {Card, Col, Divider, Progress, Row, Spin} from "antd";
+import {Card, Col, Divider, Progress, Row, Spin, Tour} from "antd";
 import * as SystemBackend from "./backend/SystemInfo";
 import React from "react";
 import * as Setting from "./Setting";
+import * as TourConfig from "./TourConfig";
 import i18next from "i18next";
 import PrometheusInfoTable from "./table/PrometheusInfoTable";
 
@@ -29,6 +30,7 @@ class SystemInfo extends React.Component {
       prometheusInfo: {apiThroughput: [], apiLatency: [], totalThroughput: 0},
       intervalId: null,
       loading: true,
+      isTourVisible: TourConfig.getTourVisible(),
     };
   }
 
@@ -67,12 +69,48 @@ class SystemInfo extends React.Component {
     });
   }
 
+  componentDidMount() {
+    window.addEventListener("storageTourChanged", this.handleTourChange);
+  }
+
+  handleTourChange = () => {
+    this.setState({isTourVisible: TourConfig.getTourVisible()});
+  };
+
   componentWillUnmount() {
     if (this.state.intervalId !== null) {
       clearInterval(this.state.intervalId);
     }
+    window.removeEventListener("storageTourChanged", this.handleTourChange);
   }
 
+  setIsTourVisible = () => {
+    TourConfig.setIsTourVisible(false);
+    this.setState({isTourVisible: false});
+  };
+
+  handleTourComplete = () => {
+    const nextPathName = TourConfig.getNextUrl();
+    if (nextPathName !== "") {
+      this.props.history.push("/" + nextPathName);
+      TourConfig.setIsTourVisible(true);
+    }
+  };
+
+  getSteps = () => {
+    const nextPathName = TourConfig.getNextUrl();
+    const steps = TourConfig.getSteps();
+    steps.map((item, index) => {
+      item.target = () => document.getElementById(item.id) || null;
+      if (index === steps.length - 1) {
+        item.nextButtonProps = {
+          children: TourConfig.getNextButtonChild(nextPathName),
+        };
+      }
+    });
+    return steps;
+  };
+
   render() {
     const cpuUi = this.state.systemInfo.cpuUsage?.length <= 0 ? i18next.t("system:Failed to get CPU usage") :
       this.state.systemInfo.cpuUsage.map((usage, i) => {
@@ -99,33 +137,34 @@ class SystemInfo extends React.Component {
 
     if (!Setting.isMobile()) {
       return (
+        <>
           <Row>
             <Col span={6}></Col>
             <Col span={12}>
               <Row gutter={[10, 10]}>
                 <Col span={12}>
-                <Card title={i18next.t("system:CPU Usage")} bordered={true} style={{textAlign: "center", height: "100%"}}>
+                  <Card id="cpu-card" title={i18next.t("system:CPU Usage")} bordered={true} style={{textAlign: "center", height: "100%"}}>
                     {this.state.loading ? <Spin size="large" /> : cpuUi}
                   </Card>
                 </Col>
                 <Col span={12}>
-                <Card title={i18next.t("system:Memory Usage")} bordered={true} style={{textAlign: "center", height: "100%"}}>
+                  <Card id="memory-card" title={i18next.t("system:Memory Usage")} bordered={true} style={{textAlign: "center", height: "100%"}}>
                     {this.state.loading ? <Spin size="large" /> : memUi}
                   </Card>
                 </Col>
                 <Col span={24}>
-                <Card title={i18next.t("system:API Latency")} bordered={true} style={{textAlign: "center", height: "100%"}}>
+                  <Card id="latency-card" title={i18next.t("system:API Latency")} bordered={true} style={{textAlign: "center", height: "100%"}}>
                     {this.state.loading ? <Spin size="large" /> : latencyUi}
                   </Card>
                 </Col>
                 <Col span={24}>
-                <Card title={i18next.t("system:API Throughput")} bordered={true} style={{textAlign: "center", height: "100%"}}>
+                  <Card id="throughput-card" title={i18next.t("system:API Throughput")} bordered={true} style={{textAlign: "center", height: "100%"}}>
                     {this.state.loading ? <Spin size="large" /> : throughputUi}
                   </Card>
                 </Col>
               </Row>
               <Divider />
-            <Card title={i18next.t("system:About Casdoor")} bordered={true} style={{textAlign: "center"}}>
+              <Card id="about-card" title={i18next.t("system:About Casdoor")} bordered={true} style={{textAlign: "center"}}>
                 <div>{i18next.t("system:An Identity and Access Management (IAM) / Single-Sign-On (SSO) platform with web UI supporting OAuth 2.0, OIDC, SAML and CAS")}</div>
                 GitHub: <a target="_blank" rel="noreferrer" href="https://github.com/casdoor/casdoor">Casdoor</a>
                 <br />
@@ -138,6 +177,18 @@ class SystemInfo extends React.Component {
             </Col>
             <Col span={6}></Col>
           </Row>
+          <Tour
+            open={this.state.isTourVisible}
+            onClose={this.setIsTourVisible}
+            steps={this.getSteps()}
+            indicatorsRender={(current, total) => (
+              <span>
+                {current + 1} / {total}
+              </span>
+            )}
+            onFinish={this.handleTourComplete}
+          />
+        </>
       );
     } else {
       return (

web/src/TourConfig.js

@@ -0,0 +1,223 @@
+import React from "react";
+
+export const TourObj = {
+  home: [
+    {
+      title: "Welcome to casdoor",
+      description: "You can learn more about the use of CasDoor at https://casdoor.org/.",
+      cover: (
+        <img
+          alt="casdoor.png"
+          src="https://cdn.casbin.org/img/casdoor-logo_1185x256.png"
+        />
+      ),
+    },
+    {
+      title: "Statistic cards",
+      description: "Here are four statistic cards for user information.",
+      id: "statistic",
+    },
+    {
+      title: "Import users",
+      description: "You can add new users or update existing Casdoor users by uploading a XLSX file of user information.",
+      id: "echarts-chart",
+    },
+  ],
+  webhooks: [
+    {
+      title: "Webhook List",
+      description: "Event systems allow you to build integrations, which subscribe to certain events on Casdoor. When one of those event is triggered, we'll send a POST json payload to the configured URL. The application parsed the json payload and carry out the hooked function. Events consist of signup, login, logout, update users, which are stored in the action field of the record. Event systems can be used to update an external issue from users.",
+    },
+  ],
+  syncers: [
+    {
+      title: "Syncer List",
+      description: "Casdoor stores users in user table. Don't worry about migrating your application user data into Casdoor, when you plan to use Casdoor as an authentication platform. Casdoor provides syncer to quickly help you sync user data to Casdoor.",
+    },
+  ],
+  sysinfo: [
+    {
+      title: "CPU Usage",
+      description: "You can see the CPU usage in real time.",
+      id: "cpu-card",
+    },
+    {
+      title: "Memory Usage",
+      description: "You can see the Memory usage in real time.",
+      id: "memory-card",
+    },
+    {
+      title: "API Latency",
+      description: "You can see the usage statistics of each API latency in real time.",
+      id: "latency-card",
+    },
+    {
+      title: "API Throughput",
+      description: "You can see the usage statistics of each API throughput in real time.",
+      id: "throughput-card",
+    },
+    {
+      title: "About Casdoor",
+      description: "You can get more Casdoor information in this card.",
+      id: "about-card",
+    },
+  ],
+  subscriptions: [
+    {
+      title: "Subscription List",
+      description: "Subscription helps to manage user's selected plan that make easy to control application's features access.",
+    },
+  ],
+  pricings: [
+    {
+      title: "Price List",
+      description: "Casdoor can be used as subscription management system via plan, pricing and subscription.",
+    },
+  ],
+  plans: [
+    {
+      title: "Plan List",
+      description: "Plan  describe list of application's features with own name and price. Plan features depends on Casdoor role with set of permissions.That allow to describe plan's features independ on naming and price. For example: plan may has diffrent prices depends on county or date.",
+    },
+  ],
+  payments: [
+    {
+      title: "Payment List",
+      description: "After the payment is successful, you can see the transaction information of the products in Payment, such as organization, user, purchase time, product name, etc.",
+    },
+  ],
+  products: [
+    {
+      title: "Session List",
+      description: "You can add the product (or service) you want to sell. The following will tell you how to add a product.",
+    },
+  ],
+  sessions: [
+    {
+      title: "Session List",
+      description: "You can get Session ID in this list.",
+    },
+  ],
+  tokens: [
+    {
+      title: "Token List",
+      description: "Casdoor is based on OAuth. Tokens are users' OAuth token.You can get access token in this list.",
+    },
+  ],
+  enforcers: [
+    {
+      title: "Enforcer List",
+      description: "In addition to the API interface for requesting enforcement of permission control, Casdoor also provides other interfaces that help external applications obtain permission policy information, which is also listed here.",
+    },
+  ],
+  adapters: [
+    {
+      title: "Adapter List",
+      description: "Casdoor supports using the UI to connect the adapter and manage the policy rules. In Casbin, the policy storage is implemented as an adapter (aka middleware for Casbin). A Casbin user can use an adapter to load policy rules from a storage, or save policy rules to it.",
+    },
+  ],
+  models: [
+    {
+      title: "Model List",
+      description: "Model defines your permission policy structure, and how requests should match these permission policies and their effects. Then you can user model in Permission.",
+    },
+  ],
+  permissions: [
+    {
+      title: "Permission List",
+      description: "All users associated with a single Casdoor organization are shared between the organization's applications and therefore have access to the applications. Sometimes you may want to restrict users' access to certain applications, or certain resources in a certain application. In this case, you can use Permission implemented by Casbin.",
+    },
+    {
+      title: "Permission Add",
+      description: "In the Casdoor Web UI, you can add a Model for your organization in the Model configuration item, and a Policy for your organization in the Permission configuration item. ",
+      id: "add-button",
+    },
+    {
+      title: "Permission Upload",
+      description: "With Casbin Online Editor, you can get Model and Policy files suitable for your usage scenarios. You can easily import the Model file into Casdoor through the Casdoor Web UI for use by the built-in Casbin. ",
+      id: "upload-button",
+    },
+  ],
+  roles: [
+    {
+      title: "Role List",
+      description: "Each user may have multiple roles. You can see the user's roles on the user's profile.",
+    },
+  ],
+  resources: [
+    {
+      title: "Resource List",
+      description: "You can upload resources in casdoor. Before upload resources, you need to configure a storage provider. Please see Storage Provider.",
+    },
+    {
+      title: "Upload Resource",
+      description: "Users can upload resources such as files and images to the previously configured cloud storage.",
+      id: "upload-button",
+    },
+  ],
+  providers: [
+    {
+      title: "Provider List",
+      description: "We have 6 kinds of providers:OAuth providers、SMS Providers、Email Providers、Storage Providers、Payment Provider、Captcha Provider.",
+    },
+    {
+      title: "Provider Add",
+      description: "You must add the provider to application, then you can use the provider in your application",
+      id: "add-button",
+    },
+  ],
+  organizations: [
+    {
+      title: "Organization List",
+      description: "Organization is the basic unit of Casdoor, which manages users and applications. If a user signed in to an organization, then he can access all applications belonging to the organization without signing in again.",
+    },
+  ],
+  groups: [
+    {
+      title: "Group List",
+      description: "In the groups list pages, you can see all the groups in organizations.",
+    },
+  ],
+  users: [
+    {
+      title: "User List",
+      description: "As an authentication platform, Casdoor is able to manage users.",
+    },
+    {
+      title: "Import users",
+      description: "You can add new users or update existing Casdoor users by uploading a XLSX file of user information.",
+      id: "upload-button",
+    },
+  ],
+  applications: [
+    {
+      title: "Application List",
+      description: "If you want to use Casdoor to provide login service for your web Web APPs, you can add them as Casdoor applications. Users can access all applications in their organizations without login twice.",
+    },
+  ],
+};
+
+export const TourUrlList = ["home", "organizations", "groups", "users", "applications", "providers", "resources", "roles", "permissions", "models", "adapters", "enforcers", "tokens", "sessions", "products", "payments", "plans", "pricings", "subscriptions", "sysinfo", "syncers", "webhooks"];
+
+export function getNextUrl(pathName = window.location.pathname) {
+  return TourUrlList[TourUrlList.indexOf(pathName.replace("/", "")) + 1] || "";
+}
+
+export function setIsTourVisible(visible) {
+  localStorage.setItem("isTourVisible", visible);
+  window.dispatchEvent(new Event("storageTourChanged"));
+}
+
+export function getTourVisible() {
+  return localStorage.getItem("isTourVisible") !== "false";
+}
+
+export function getNextButtonChild(nextPathName) {
+  return nextPathName !== "" ?
+    `Go to "${nextPathName.charAt(0).toUpperCase()}${nextPathName.slice(1)} List"`
+    : "Finish";
+}
+
+export function getSteps(pathName = window.location.pathname) {
+  return TourObj[(pathName.replace("/", ""))];
+}

web/src/UserListPage.js

@@ -187,7 +187,7 @@ class UserListPage extends BaseListPage {
 
     return (
       <Upload {...props}>
-        <Button type="primary" size="small">
+        <Button id="upload-button" type="primary" size="small">
           <UploadOutlined /> {i18next.t("user:Upload (.xlsx)")}
         </Button>
       </Upload>
@@ -426,7 +426,7 @@ class UserListPage extends BaseListPage {
           title={() => (
             <div>
               {i18next.t("general:Users")}&nbsp;&nbsp;&nbsp;&nbsp;
-              <Button style={{marginRight: "5px"}} type="primary" size="small" onClick={this.addUser.bind(this)}>{i18next.t("general:Add")}</Button>
+              <Button style={{marginRight: "5px"}} type="primary" size="small" onClick={this.addUser.bind(this)}>{i18next.t("general:Add")} </Button>
               {
                 this.renderUpload()
               }

web/src/basic/Dashboard.js

@@ -13,15 +13,23 @@
 // limitations under the License.
 
 import {ArrowUpOutlined} from "@ant-design/icons";
-import {Card, Col, Row, Statistic} from "antd";
+import {Card, Col, Row, Statistic, Tour} from "antd";
 import * as echarts from "echarts";
 import i18next from "i18next";
 import React from "react";
 import * as DashboardBackend from "../backend/DashboardBackend";
 import * as Setting from "../Setting";
+import * as TourConfig from "../TourConfig";
 
 const Dashboard = (props) => {
   const [dashboardData, setDashboardData] = React.useState(null);
+  const [isTourVisible, setIsTourVisible] = React.useState(TourConfig.getTourVisible());
+  const nextPathName = TourConfig.getNextUrl("home");
+
+  React.useEffect(() => {
+    window.addEventListener("storageTourChanged", handleTourChange);
+    return () => window.removeEventListener("storageTourChanged", handleTourChange);
+  }, []);
 
   React.useEffect(() => {
     if (!Setting.isLocalAdminUser(props.account)) {
@@ -42,6 +50,35 @@ const Dashboard = (props) => {
     });
   }, [props.owner]);
 
+  const handleTourChange = () => {
+    setIsTourVisible(TourConfig.getTourVisible());
+  };
+
+  const setIsTourToLocal = () => {
+    TourConfig.setIsTourVisible(false);
+    setIsTourVisible(false);
+  };
+
+  const handleTourComplete = () => {
+    if (nextPathName !== "") {
+      props.history.push("/" + nextPathName);
+      TourConfig.setIsTourVisible(true);
+    }
+  };
+
+  const getSteps = () => {
+    const steps = TourConfig.TourObj["home"];
+    steps.map((item, index) => {
+      item.target = () => document.getElementById(item.id) || null;
+      if (index === steps.length - 1) {
+        item.nextButtonProps = {
+          children: TourConfig.getNextButtonChild(nextPathName),
+        };
+      }
+    });
+    return steps;
+  };
+
   const renderEChart = () => {
     if (dashboardData === null) {
       return;
@@ -83,7 +120,7 @@ const Dashboard = (props) => {
     myChart.setOption(option);
 
     return (
-      <Row gutter={80}>
+      <Row id="statistic" gutter={80}>
         <Col span={50}>
           <Card bordered={false} bodyStyle={{width: "100%", height: "150px", display: "flex", alignItems: "center", justifyContent: "center"}}>
             <Statistic title={i18next.t("home:Total users")} fontSize="100px" value={dashboardData.userCounts[30]} valueStyle={{fontSize: "30px"}} style={{width: "200px", paddingLeft: "10px"}} />
@@ -112,6 +149,17 @@ const Dashboard = (props) => {
     <div style={{display: "flex", justifyContent: "center", flexDirection: "column", alignItems: "center"}}>
       {renderEChart()}
       <div id="echarts-chart" style={{width: "80%", height: "400px", textAlign: "center", marginTop: "20px"}} />
+      <Tour
+        open={isTourVisible}
+        onClose={setIsTourToLocal}
+        steps={getSteps()}
+        indicatorsRender={(current, total) => (
+          <span>
+            {current + 1} / {total}
+          </span>
+        )}
+        onFinish={handleTourComplete}
+      />
     </div>
   );
 };

web/src/common/OpenTour.js

@@ -0,0 +1,40 @@
+// Copyright 2023 The Casdoor Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import React from "react";
+import {Tooltip} from "antd";
+import {QuestionCircleOutlined} from "@ant-design/icons";
+import * as TourConfig from "../TourConfig";
+import * as Setting from "../Setting";
+
+class OpenTour extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = {
+      isTourVisible: props.isTourVisible ?? TourConfig.getTourVisible(),
+    };
+  }
+
+  render() {
+    return (
+      <Tooltip title="Click to enable the help wizard">
+        <div className="select-box" style={{display: Setting.isMobile() ? "none" : null, ...this.props.style}} onClick={() => TourConfig.setIsTourVisible(true)} >
+          <QuestionCircleOutlined style={{fontSize: "24px", color: "#4d4d4d"}} />
+        </div>
+      </Tooltip>
+    );
+  }
+}
+
+export default OpenTour;