Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

List imports explicitly in readme examples #59

Merged
merged 1 commit into from
Sep 3, 2023
Merged

List imports explicitly in readme examples #59

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 55 additions & 35 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ your backend.**
### Creating a policy

A policy accepts a user, often the current user of your session, and the
resource you wish to authorise against.
resource you wish to authorise against, referred to as a record.

Policies can be defined by extending the `Policy` class. Add a constructor that
accepts the user and record objects as parameters, also calling
Expand Down Expand Up @@ -115,38 +115,54 @@ You can determine what is shown based on what a user is authorised to see by
using the `When` component.

```jsx
<When can="edit" policy={postPolicy} user={user} record={post}>
<EditButton />
</When>
import { When } from 'pundit'
import PostPolicy from 'src/policies/post.policy.js'

// ...

return (
<When can="edit" policy={postPolicy} user={user} record={post}>
<EditButton />
</When>
)
```

The `user` and `record` attributes are not required if these passed into the
policy's contructor when instantiating it. The following acts as a shorthand:

```jsx
<When can="edit" policy={new PostPolicy(user, post)}>
<EditButton />
</When>
return (
<When can="edit" policy={new PostPolicy(user, post)}>
<EditButton />
</When>
)
```

In order to avoid passing user/policy/record props to every usage of the
`When` component you can use the `PunditProvider`.

```jsx
<PunditProvider policy={postPolicy} user={user} record={post}>
<When can="view">
<Link />
</When>
<When can="fork">
<ForkButton />
</When>
<When can="edit">
<EditButton />
</When>
<When can="destroy">
<DeleteButton />
</When>
</PunditProvider>
import { PunditProvider, When } from 'pundit'
import PostPolicy from 'src/policies/post.policy.js'

// ...

return (
<PunditProvider policy={postPolicy} user={user} record={post}>
<When can="view">
<Link />
</When>
<When can="fork">
<ForkButton />
</When>
<When can="edit">
<EditButton />
</When>
<When can="destroy">
<DeleteButton />
</When>
</PunditProvider>
)
```

As with the `When` component, you can pass the `user` and `record` attributes
Expand All @@ -155,24 +171,28 @@ attributes for particular usages of `When` within the provider, for example to
check if an alternative user or record is authorised.

```jsx
<PunditProvider policy={new PostPolicy(user, post)}>
<When can="view">
<Link>View Post</Link>
</When>
<When can="view" user={masqueradeUser}>
<Link>View Post Masquerading as {masqueradeUser.name}</Link>
</When>
<When can="view" record={nextPost}>
<Link>View Next Post</Link>
</When>
</PunditProvider>
return (
<PunditProvider policy={new PostPolicy(user, post)}>
<When can="view">
<Link>View Post</Link>
</When>
<When can="view" user={masqueradeUser}>
<Link>View Post Masquerading as {masqueradeUser.name}</Link>
</When>
<When can="view" record={nextPost}>
<Link>View Next Post</Link>
</When>
</PunditProvider>
)
```

### Testing

Policies can be unit tested, for example with Jest/Vitest:

```javascript
import PostPolicy from 'src/policies/post.policy.js'

describe('post policy, edit action', () => {
const user = { id: 1 }

Expand Down Expand Up @@ -201,7 +221,7 @@ MIT
1. Push to the branch (`git push origin my-new-feature`)
1. Create new Pull Request

---
## Authors

> Built by [johno](https://johno.com) ([@4lpine](https://twitter.com/4lpine))
> and [Chris Alley](https://github.com/chrisalley).
Built by [johno](https://johno.com) ([@4lpine](https://twitter.com/4lpine)) and
[Chris Alley](https://github.com/chrisalley).