Skip to content

TASK: improve exisiting & add missing codeblocks #60

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

TASK: improve exisiting & add missing codeblocks #60

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
65 changes: 44 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,8 @@ for instructions on how to set the following configurations:
* templatePackage

Hint: to override the sender address for this package, you will need the following setting:
```YAML

```yaml
Sandstorm:
TemplateMailer:
senderAddresses:
Expand Down Expand Up @@ -66,7 +67,8 @@ If you can't remove them, just include the subroutes for this package manually b
your packages, which allows you to override config and will make sure authorizations work correctly. Keep in mind that you have to add this into all
packages that use features from user management - very important if your site is split into multiple packages or plugins.
Here's an example:
```

```json
{
"description": "Your Site Package",
"type": "neos-site", (or "neos-package" if you're using Flow only or building a Plugin)
Expand All @@ -84,7 +86,8 @@ Here's an example:

## Basic configuration options
These are the basic configuration options for e-mails, timeouts etc. You will usually want to adapt these to your application.
```

```yaml
Sandstorm:
UserManagement:
# Validity timespan for the activation token for newly registered users.
Expand All @@ -107,7 +110,8 @@ Sandstorm:

### I18N
It is possible to use i18n for the messages configured in the settings. Simply by setting the values to 'i18n'.
```

```yaml
Sandstorm:
UserManagement:
authFailedMessage:
Expand All @@ -120,7 +124,8 @@ Sandstorm:

## Additional Settings for usage in Neos
You should switch the implementation of the Redirect and User Creation Services to the Neos services. Add this to your `Objects.yaml`:
```

```yaml
# Use the Neos services
Sandstorm\UserManagement\Domain\Service\RedirectTargetServiceInterface:
className: 'Sandstorm\UserManagement\Domain\Service\Neos\NeosRedirectTargetService'
Expand All @@ -136,7 +141,7 @@ as it's in the templates of this package.
Add the following to your package's (or the global) `Settings.yaml`. This creates a separate authentication provider so Neos can
distinguish between frontend and backend logins.

```
```yaml
Neos:
Flow:
security:
Expand Down Expand Up @@ -169,33 +174,42 @@ with `Typo3BackendProvider` in the config above.
### Creating users
The package exposes a command to create users. You can run

`./flow sandstormuser:create [email protected] password --additionalAttributes="firstName:Max;lastName:Mustermann"`
```bash
./flow sandstormuser:create [email protected] password --additionalAttributes="firstName:Max;lastName:Mustermann"
```

to create a user. This will create a Neos user if you're using the package in Neos. You can assign
roles to the new user in the Neos backend afterwards.

### Confirming user registration
It is possible to confirm a registrationflow and trigger user creation by running

`./flow sandstormuser:activateregistration [email protected]`
```bash
./flow sandstormuser:activateregistration [email protected]
```

### Resetting passwords
Since 1.1.2, it is possible to reset passwords for users created with this package.

`./flow sandstormuser:setpassword [email protected] password`
```bash
./flow sandstormuser:setpassword [email protected] password
```

If the package detects that the NeosUserCreationService is used, it forwards the command to the
Neos `UserCommandController->setPasswordCommand()`. Otherwise, our oackage's own logic is used.

The Authentication Provider can be passed in as an optional argument to reset passwords for users created
with a different provider that the default UserManagement one (`Sandstorm.UserManagement:Login`):

`./flow sandstormuser:setpassword [email protected] password --authenticationProvider=Typo3BackendProvider`
```bash
./flow sandstormuser:setpassword [email protected] password --authenticationProvider=Typo3BackendProvider
```

## Redirect after login/logout
### Via configuration
To define where users should be redirected after they log in or out, you can set some config options:
```

```yaml
Sandstorm:
UserManagement:
redirect:
Expand All @@ -216,6 +230,7 @@ The pages you link here will be shown after users log in or out. Please note tha
on a restricted page: in that case you MUST set a redirect target, otherwise you will receive an error message on logout.
If the redirection is configured via Settings.yaml, they will take precedence over the configuration at the node.
You can, of course, set these properties from TypoScript also if you have a login/logout form directly in you template:

```
loginform = Sandstorm.UserManagement:LoginForm {
// This should be set, or there will be problems when you have multiple plugins on a page
Expand All @@ -229,15 +244,16 @@ loginform = Sandstorm.UserManagement:LoginForm {
If redirecting to a specific controller method is still not enough for you, you can simply roll your own implementation of the
`RedirectTargetServiceInterface`. Just add the implementation within your own package and add the following lines to your `Objects.yaml`.
Mind the package loading order, you package should require sandstorm/usermanagement in its composer.json.
```

```yaml
Sandstorm\UserManagement\Domain\Service\RedirectTargetServiceInterface:
className: 'Your\Package\Domain\Service\YourCustomRedirectTargetService'
```

## Checking for a logged-in user in your templates
There is a ViewHelper available that allows you to check if somebody is logged into the frontend. Here's an example:

```
```html
{namespace um=Sandstorm\UserManagement\ViewHelpers}

<um:ifAuthenticated>
Expand All @@ -248,7 +264,6 @@ There is a ViewHelper available that allows you to check if somebody is logged i
You are not logged in!
</f:else>
</um:ifAuthenticated>

```

If you have configured a different Authentication Provider than the default one, the viewhelper has an `authenticationProviderName`
Expand All @@ -261,7 +276,7 @@ You can change any template via the default method using `Views.yaml`. Please se
http://flowframework.readthedocs.io/en/stable/TheDefinitiveGuide/PartIII/ModelViewController.html#configuring-views-through-views-yaml.
Here's an example how to plug your own login template:

```YAML
```yaml

-
requestFilter: 'mainRequest.isPackage("Neos.Neos") && isPackage("Sandstorm.UserManagement") && isController("Login") && isAction("login")'
Expand All @@ -282,7 +297,8 @@ You might want to add additional information to the user model. This can be done
the User model delivered with this package and adding properties as you like. You will then
need to switch out the implementation of `UserCreationServiceInterface` to get control over
the creation process. This can be done via `Objects.yaml`:
```YAML

```yaml
Sandstorm\UserManagement\Domain\Service\UserCreationServiceInterface:
className: 'Your\Package\Domain\Service\YourCustomUserCreationService'
```
Expand All @@ -292,7 +308,8 @@ The UserManagement package emits three signals during the login and logout proce
using Flows [Signals and Slots](http://flowframework.readthedocs.io/en/stable/TheDefinitiveGuide/PartIII/SignalsAndSlots.html)
mechanism. You could for example use this to set additional cookies when a user logs in, e.g. to enable JWT authentication
with another service. Here is an example of using all three, you could copy this into your own `Package.php` file:
```PHP

```php
public function boot(Bootstrap $bootstrap) {
$dispatcher = $bootstrap->getSignalSlotDispatcher();
$dispatcher->connect(
Expand All @@ -311,7 +328,8 @@ public function boot(Bootstrap $bootstrap) {
```

Your example service could then look like this:
```PHP

```php
namespace Your\Package\Domain\Service;

use Neos\Flow\Mvc\ActionRequest;
Expand Down Expand Up @@ -343,7 +361,8 @@ It has a few default properties and can be extended with arbitrary additional da

### Adding custom fields to the Registration Flow
Exchange the registration template as described above and add a field:
```HTML

```html
<f:form.checkbox id="terms" property="attributes.terms" value=""/>
```
This will add the field, but of course you might also want to validate it.
Expand All @@ -353,7 +372,8 @@ The UserManagement package has a hook for you to implement your custom registrat
called directly from the domain model validator of the package. All you need to to is create an implementation of
`Sandstorm\UserManagement\Domain\Service\RegistrationFlowValidationServiceInterface` in your own package. It could
look like this:
```PHP

```php
class RegistrationFlowValidationService implements RegistrationFlowValidationServiceInterface {
/**
* @param RegistrationFlow $registrationFlow
Expand All @@ -371,7 +391,10 @@ class RegistrationFlowValidationService implements RegistrationFlowValidationSer

# 4. Running Tests
Run all tests with:
`./bin/phpunit -c ./Build/BuildEssentials/PhpUnit/UnitTests.xml Packages/Application/Sandstorm.UserManagement/Tests/Unit`

```bash
./bin/phpunit -c ./Build/BuildEssentials/PhpUnit/UnitTests.xml Packages/Application/Sandstorm.UserManagement/Tests/Unit
```

# 5. Known issues

Expand Down