contact-collection

@fluid-example/contact-collection

Contact collection demonstrates how a data object can be treated as a collection of multiple smaller objects.

The collection pattern demonstrated here might be a fit for your scenario if:

1. Your data can be described as a homogenous collection of separately usable pieces.
2. The consumers of your data (e.g. views or other data objects) might prefer to operate on a single piece, rather than the full collection.

Whereas a non-collection approach might have a collection data object holding handles to many other completely distinct data objects, the collection approach uses a single data object to organize all the data in one place. It then provides interfaces to access individual members as standalone objects. In this example, the ContactCollection data object stores contact data with one contact per key in its root, to be accessed through a Contact class which is not a data object. In comparison, the non-collection approach would have stored handles to separate Contact (full-fledged) data objects. @fluid-example/todo is a good example of the non-collection approach, storing TodoItem data objects as handles in the Todo data object.

The key feature of the collection pattern is that it facilitates individual retrieval of a piece for use in consumers that don't wish to operate on (or shouldn't have access to) the full collection. This enables you to retain the granular access that individual data objects provide without the overhead of data object creation and async access of handles.

The specific access mechanisms can vary -- in this example, ContactCollection has getContacts() and getContact() methods which return Contact objects. getContacts() is used in the renderContactCollection() view, and getContact() is used by the app to retrieve a singular Contact for use with the renderContact() view.

For another example of this pattern, consider the SharedDirectory DDS. The getWorkingDirectory() method allows granular access to an IDirectory that can be used separately from the remainder of the SharedDirectory, despite the data being stored in the same data store. Although the details differ since it is a DDS rather than a data object, the principle is the same.

Getting Started

You can run this example using the following steps:

1. Enable corepack by running corepack enable.
2. Run pnpm install and pnpm run build:fast --nolint from the FluidFramework root directory.
   • For an even faster build, you can add the package name to the build command, like this: pnpm run build:fast --nolint @fluid-example/contact-collection
3. In a separate terminal, start a Tinylicious server by running pnpm tinylicious in this directory.
4. If using codespaces in a browser, set tinylicious (port 7070) visibility to "public". "Private to Organization" will not work. See sharing a port for how to do this.
5. Run pnpm start from this directory and open http://localhost:8080 in a web browser to see the app running.
6. If you want to run the app against SharePoint, follow the instructions in webpack-fluid-loader to get auth credentials. Then run pnpm start:spo or pnpm start:spo-df and open http://localhost:8080 like above.

Testing

    npm run test:jest

For in browser testing update ./jest-puppeteer.config.js to:

  launch: {
    dumpio: true, // output browser console to cmd line
    slowMo: 500,
    headless: false,
  },

Data model

Contact collection uses the following distributed data structures:

• SharedDirectory -- root

Contribution Guidelines

There are many ways to contribute to Fluid.

• Participate in Q&A in our GitHub Discussions.
• Submit bugs and help us verify fixes as they are checked in.
• Review the source code changes.
• Contribute bug fixes.

Detailed instructions for working in the repo can be found in the Wiki.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks or logos must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.

Help

Not finding what you're looking for in this README? Check out fluidframework.com.

Still not finding what you're looking for? Please file an issue.

Thank you!

Trademark

This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.

Use of these trademarks or logos must follow Microsoft's Trademark & Brand Guidelines.

Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.