{"id":13808919,"url":"https://github.com/Broadcom/bdc-walkthrough","last_synced_at":"2025-05-14T03:31:47.483Z","repository":{"id":38461358,"uuid":"242954049","full_name":"Broadcom/bdc-walkthrough","owner":"Broadcom","description":"An Angular Material library for displaying walk-through pop-ups and dialogs using a declarative way.","archived":false,"fork":false,"pushed_at":"2023-12-26T09:37:12.000Z","size":2995,"stargazers_count":72,"open_issues_count":13,"forks_count":15,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-04-26T18:06:43.810Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Broadcom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-25T08:58:05.000Z","updated_at":"2024-06-19T17:35:57.797Z","dependencies_parsed_at":"2024-06-19T17:35:43.200Z","dependency_job_id":"8f72e0b7-412d-486e-83f7-e42c9803471a","html_url":"https://github.com/Broadcom/bdc-walkthrough","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Broadcom%2Fbdc-walkthrough","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Broadcom%2Fbdc-walkthrough/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Broadcom%2Fbdc-walkthrough/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Broadcom%2Fbdc-walkthrough/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Broadcom","download_url":"https://codeload.github.com/Broadcom/bdc-walkthrough/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225273292,"owners_count":17448080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T01:01:55.009Z","updated_at":"2024-11-19T00:31:13.516Z","avatar_url":"https://github.com/Broadcom.png","language":"TypeScript","readme":"# Material walk-through library\n\nAn Angular Material library for displaying walk-through pop-ups and\ndialogs using a declarative way.\n\nby Amir Leshem (Broadcom)\n\n### [Show Demo](https://stackblitz.com/edit/angular-bdc-walkthrough)\n\n![bdc-walkthrough](screenshot.png)\n\n## Prerequisites\n\nThis library is compatible with Angular/Material 8.0 and higher.\u003cbr\u003e\nPlease install the version of bdc-walkthrough according to this table:\n\n| version |   Angular   |  Material   |\n|---------|:-----------:|:-----------:|\n| 1.2.x   | 14.0 - 15.0 | 14.0 - 15.0 |\n| 1.1.1   | 8.0 - 13.0  | 8.0 - 13.0  |\n\nImportant Note: When using Material 15.x this library will use the new MDC-based Angular Material Components.\nThis might lead to inconsistent style usage if the rest of your app is using the legacy (non-MDC) componenets.\nFor more info please check https://material.angular.io/guide/mdc-migration\n\n1. Install Angular Material:\n    ```\n    ng add @angular/material\n    ```\n\n2. Install bdc-walkthrough:\n    ```angular2html\n    npm install bdc-walkthrough\n    ```\n\n3. Import BdcWalkModule into app.module.ts\n\n## How to use it?\nThe walk-through library is composed of these parts:\n\n### BdcWalkService\nA service used to manage and store the completed tasks.\nThese are stored in the LocalStorage of the browser.\n\nEach task is either completed (true), uncompleted (false), or completed\nwith a value (any primitive or object).\n\nWhenever the state of a task is changed, all walk-through popups and dialogs on\npage are re-evaluated to appear or disappear according to their\n`[mustCompleted]` logic.\n\n\u003e Using the service is completely optional. You only need it to programmatically\n\u003e access the state of tasks or if you want to develop new components\n\u003e other than the available \u0026lt;bdc-walk-popup\u0026gt; and \u0026lt;bdc-walk-dialog\u0026gt;.\n\n```typescript\nexport class AppComponent implements OnInit {\n\n  constructor(private bdcWalkService: BdcWalkService) {}\n\n  ngOnInit() {\n    // make sure to unsubscribe on ngDestroy\n    this.bdcWalkService.changes.subscribe(() =\u003e {\n      // get the value of a task\n      const taskCompleted = this.bdcWalkService.getTaskCompleted('taskCreateApp');\n    });\n  }\n\n  submit(appForm) {\n    // set the value of a task\n    const app = DB.createApp(appForm);\n    this.bdcWalkService.setTaskCompleted('taskCreateApp', {id: app.id, name: app.name});\n  }\n\n  reset() {\n    // reset all tasks\n    this.bdcWalkService.reset();\n  }\n}\n```\n### \u0026lt;bdc-walk-popup\u0026gt;\nA component used to display popups automatically when a set of tasks match\nthe `[mustCompleted]` criteria.\n\nEach popup has a unique name, which is used to identify its task.\n\nIf the popup is closed by the user, its task is automatically marked as\ncompleted and it won't show up again.\n\n```angular2html\n\u003cbdc-walk-popup #taskDeleteApp name=\"taskDeleteApp\"\n                [mustCompleted]=\"{taskCreateApp: true}\"\u003e\n  Click to delete the App\n\u003c/bdc-walk-popup\u003e\n```\n\nIt can then be attached to an element or a component using `[bdcWalkTriggerFor]`\ndirective and the hashtag reference of the popup:\n\n```angular2html\n\u003cbutton [bdcWalkTriggerFor]=\"taskDeleteApp\" (click)=\"delete()\"\u003e\n  Delete\n\u003c/button\u003e\n```\n\nYou can also manually control which tasks to set when the popup is closed or\nits button is clicked using `[onButtonCompleteTask]` and `[onCloseCompleteTask]`.\n\n```angular2html\n\u003cbdc-walk-popup #step1 name=\"step1\" [showButton]=\"true\" buttonText=\"Next\" [onButtonCompleteTask]=\"{next: 1}\"\u003e\n  The next popup will only be displayed if you click \u003cb\u003eNext\u003c/b\u003e.\n\u003c/bdc-walk-popup\u003e\n\n\u003cbdc-walk-popup #step2 name=\"step2\" [showButton]=\"true\" buttonText=\"Next\" [mustCompleted]=\"{next: 1}\" [onButtonCompleteTask]=\"{next: 2}\"\u003e\n  The next popup will only be displayed if you click \u003cb\u003eNext\u003c/b\u003e.\n\u003c/bdc-walk-popup\u003e\n```\n\nRemember a task value can also be an object, not just a primitive.\n\nA task with a value can be evaluated both by its value or simply against `true`\n(a task with a value considered to be completed).\nYou can also compare values that are not equal (!3), smaller (\u003c3) or bigger (\u003e3) than the\nspecified value using [mustCompleted]=\"{next: '\u003e2'}\".\n\nYou can also display a value of a task in a template using `getValue()` on the\ntemplate reference.\n\n```angular2html\n\u003cbdc-walk-popup #taskCreateApp name=\"taskCreateApp\"\n                [onCloseCompleteTask]=\"{taskCreateApp: {id: 1, name: 'amazing app'}}\"\u003e\n  Click to create the App\n\u003c/bdc-walk-popup\u003e\n\n\u003cbdc-walk-popup #taskDeleteApp name=\"taskDeleteApp\"\n                [mustCompleted]=\"{taskCreateApp: true}\"\u003e\n  Click to delete the App {{taskDeleteApp.getValue('taskCreateApp').name }}\n\u003c/bdc-walk-popup\u003e\n```\n\n\u003e You can also evaluate only part of an object.\n\u003e For instance use `[mustCompleted]=\"{taskCreateApp: {id: 1}}\"` to\n\u003e evaluating only the id property of taskCreateApp but ignoring the name.\n\nA popup can be conditionally enabled by evaluating an expression (similar to *ngIf).\nThis is done by the `[enabled]` input on the `bdcWalkTriggerFor` directive.\n\nIn this case we evaluate the Angular's routerLinkActive directive to determine\nif the current page is the same as the router link of a navigation bar. In case\nit's not, we'll display a popup that asks the user to click on the link.\n\n```angular2html\n\u003cdiv [bdcWalkTriggerFor]=\"taskNavSites\" [enabled]=\"!linkSiteActive.isActive\"\u003e\n  \u003ca routerLinkActive=\"active\" routerLink=\"/sites\" #linkSiteActive=\"routerLinkActive\"\u003eSites\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbdc-walk-popup #taskNavSites name=\"taskNavSites\"\u003e\n  Click to navigate to Sites\n\u003c/bdc-walk-popup\u003e\n```\n\n#### Prioritizing popups\nMore than one popup can simultaneously appear on the screen. But sometimes despite\nthe conditions and logic of `[mustCompleted]` you still need to prioritize and\ndisplay only one popup. You can use `[mustNotDisplaying]` to prevent a\npopup from displaying if others are displayed at the same time.\n\nFor instance, when you display a list of sites and want the user to click on the site he\njust created.\nBut in case the site is not in the list (maybe on another page?) you want to\nsuggest the user to search for it.\n\nIt's more declarative to prevent the search suggestion\npopup from displaying in case taskClickSite popup appears, rather than\nwriting code that will check if the created site ID is found in the sites array.\n\n```angular2html\n\u003cinput [bdcWalkTriggerFor]=\"taskSearchCreatedSite\" (change)=\"search($event.value)\"\u003e\n\n\u003cdiv *ngFor=\"let site of sites\" [bdcWalkTriggerFor]=\"taskClickSite\" [mustCompleted]=\"{taskCreateSite: {id: site.id}}\"\u003e\n  {{ site.name }}\n\u003c/div\u003e\n\n\u003cbdc-walk-popup #taskSearchCreatedSite name=\"taskSearchCreatedSite\" header=\"Search Sites\" [mustCompleted]=\"{taskCreateSite: true}\" [mustNotDisplaying]=\"['taskClickSite']\"\u003e\n  Try searching the Site you just created.\u003cbr\u003e\n  Type \u003cb\u003e{{ taskSearchCreatedSite.getValue('taskCreateSite').name }}\u003c/b\u003e in the search box.\n\u003c/bdc-walk-popup\u003e\n\n\u003cbdc-walk-popup #taskClickSite name=\"taskClickSite\" header=\"Click me\"\u003e\n  Click this site\n\u003c/bdc-walk-popup\u003e\n```\n\n#### Popup visualization options\nThere are some input properties that let you customize the popup visualization:\n\n* `header` set the title of the popup.\n* `xPosition` set either the popup is positioned `before` (default) or `after` the triggered element.\n* `yPosition` set either the popup is positioned `below` (default) or `above` the triggered element.\n* `horizontal` set either the popup is positioned horizontally or vertically (default).\n* `arrow` set either an arrow is displayed (default) or not.\n* `offsetX` set an offset on the x-axis relative to the trigger element.\n* `offsetY` set an offset on the y-axis relative to the trigger element.\n* `alignCenter` set either to align the popup's arrow to the center of the element. Default (undefined) align center to small elements only.\n* `showCloseButton` set either to display the popup close button (default: true).\n* `showButton` set either to display the \"Got it\" button on a popup (default: false).\n* `buttonText` set the text on the \"Got it\" button (default: Got it).\n* `sideNoteText` set the text for the side note near the button.\n* `class` set a css class to apply to the popup.\n\n#### Other popup behaviours:\n\n* `name` set the task name for the popup. It's automatically marked as completed when the user close the popup and the popup will never display if the task is completed.\n* `closeOnClick` set either to close the popup (and mark it complete) when the user clicks on the triggered element (default: false).\n* `mustCompleted` set a dictionary object of tasks to evaluate. Completed task values can evaluate against a partial object value or just true.\n* `mustNotDisplaying` set a list of popup names that must not simultaneously appear on the screen in order to display the popup.\n* `onCloseCompleteTask` set a dictionary object of tasks to set when the user closes the popup.\n* `onButtonCompleteTask` set a dictionary object of tasks to set when the user clicks the \"Got it\" button of the popup.\n* `opened` event emitted when the popup appears. There is not a known reason why you should use it unless for debugging.\n* `closed` event emitted when the popup disappears (either by user or task evaluation). There is not a known reason why you should use it unless for debugging.\n\nMethods:\n* `getValue(taskName: string)` returns the value of a task.\n\n### [bdcWalkTriggerFor]:\n\nA directive used on any element or component to attach it to a popup instance.\nWhen the popup is displayed it will be positioned relative to that element\n(also called the trigger element) and according to the popup behaviours.\n\nIn case more than one trigger is attached to the same popup instance\n(like in *ngFor), only the first evaluated one will display the popup.\n\nSee examples of \u0026lt;bdc-walk-popup\u0026gt; above.\n\n#### Behaviours:\n* `bdcWalkTriggerFor` set a reference to the popup instance using a hashtag template variable.\n* `enabled` set a boolean expression to determine if the popup should be enabled (default: true).\n* `mustCompleted` set a dictionary object of tasks to evaluate. Completed task values can evaluate against a partial object value or just true. This is exactly the same as defining `mustCompleted` on the popup instance but is useful for cases you iterate on a list with *ngFor and need to compare from values of the iteration.\n* `data` set a context object that the popup instance template can then consume using `\u003cng-template let-value\u003e`.\n\n### \u0026lt;bdc-walk-dialog\u0026gt;\nA component used to display dialogs automatically when a set of tasks match\nthe `[mustCompleted]` criteria.\n\n```angular2html\n\u003cbdc-walk-dialog #dialogFinish name=\"dialogFinish\" width=\"650px\"\n                 [mustCompleted]=\"{taskCreateApp: true, taskDeleteApp: true}\"\u003e\n\n  \u003ch1\u003eFinished!\u003c/h1\u003e\n  Hurray,\u003cbr\u003e\n  You've successfully finished the tutorial.\n\n  \u003cdiv class=\"buttons\"\u003e\n    \u003cbutton (click)=\"dialogFinish.close()\" mat-raised-button color=\"primary\"\u003eClose\u003c/button\u003e\n  \u003c/div\u003e\n\u003c/bdc-walk-dialog\u003e\n```\n\nDialog behaviours:\n* `name` set the task name for the dialog. The dialog will never display (or will just close) if the task is completed.\n* `width` set the width of the dialog (default: 500px).\n* `mustCompleted` set a dictionary object of tasks to evaluate. Completed task values can evaluate against a partial object value or just true.\n* `mustNotDisplaying` set a list of popup/dialog names that must not simultaneously appear on the screen in order to display the dialog.\n* `opened` event emitted when the dialog appears. There is not a known reason why you should use it unless for debugging.\n* `closed` event emitted when the dialog disappears (either by user or task evaluation). There is not a known reason why you should use it unless for debugging.\n\nMethods:\n* `getValue(taskName: string)` returns the value of a task.\n* `close(setTasks?: { [taskName: string]: any | boolean })` closes the dialog by completing its task, and optionally set additional tasks.\n\n## Building source code and running the demo\nDownload the source code from github https://github.com/Broadcom/bdc-walkthrough.\nThen run `npm i` to install dependencies, `npm run build:lib` to build the bdc-walkthrough library, and finally `npm run start` to run the demo.\n","funding_links":[],"categories":["Third Party Components"],"sub_categories":["Onboarding and Product Tours"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBroadcom%2Fbdc-walkthrough","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBroadcom%2Fbdc-walkthrough","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBroadcom%2Fbdc-walkthrough/lists"}