Components

Account

Use cases

• User registration
• Logging in
• Logging out
• Changing user settings

Template Data Getters

• createSettings() Returns a list of dynamic settings which are makred as registerable
• updateSettings() Returns a list of dynamic settings which are marked as editable
• user() Returns the user object for the logged in user
• signUp() Returns whether or not we are using email or username to register

Handlers

• onUpdate() Called to update user settings and details
• onRegister() Called to preform a registration
• onLogin() Called to authenticate and login a user
• onLogout() Logs out a user

Usage Examples

To render any of the account feature you will have to manually specify the partial you wish to use.

In the future, this will be integrated into the component inspector.

{% partial 'account::update' %} - User Settings

{% partial 'account::signup' %} - User Registration

{% partial 'account::login' %} - User Login

{% partial 'account::logout' %} - User Logout

Friends

Use cases

• Send friend request
• Delete friend
• Block user - Might be moved to a different component
• Visit profiles
• Accept friend request
• Decline friend request
• Display friends list
• Display friend requests

Template Data Getters

• type() : propType Returns whether we want to render a friends list or a friend request list
• friendsList() : UserCollection Returns a list of a users friends
• friendRequests() : UserCollection Returns a list of friend requests for the logged in user

Handlers

• onDelete(post userId) Removes a friend from the logged in users friends list
• onBlock(post userId) Blocks a user from the logged in users friends list
• onVisitProfile(prop profilePage) Redirects to a users profile page
• onAccept(post userId) Accepts a friend request
• onDecline(post userId) Declines a friend request
• onRequest(post userId) Sends a friend request

Usage Examples

• Add the component to a page and use the inspector to choose an output type.
• You can also use the AJAX handlers directly if you would like to utilize them in your own plugin.

Current output types:

• Friends list
• Friend requests

User

Use cases

• Creating a profile page
• Displaying random users
• Searching users
• Displaying a user
• Sending friend requests
• Handling user profile comments
• Visiting user profile

Template Data Getters

• randomUsers(prop maxItems) : UserCollection Returns a collection of random users who aren't on our friends/block list
• type() : propType Returns the type of rendering to do: 'random' users, 'single' user, 'search' users, user 'profile' page
• singleUser(prop paramCode) : UserExtended Returns a user
• user(prop paramCode) : UserExtended Returns a user object
• locked(prop paramCode) : bool Returns whether we are a friend or own the profile we are looking at
• comments(prop paramCode) : CommentsCollection Returns a collection of comments associated with a user
• roles() : RoleCollection Returns a collection of roles for the logged in user
• groups() : GroupsCollection Returns a collection of groups for the logged in user
• userRoles(prop paramCode) : RoleCollection Returns a collection of roles for an arbitrary user
• userGroups(prop paramCode) : GroupsCollection Returns a collection of groups for an arbitrary user

Handlers

• onRequest() Sends a friend request
• onSearch(post phrase) : PartialRender Searches for users based on a phrase and returns a list of results
• onFriendUser(prop paramCode) Sends a friend request to a user
• onComment(prop paramCode, post comment) : PartialRender Creates a new comment and then refreshes the comment list
• onDeleteComment(post commentid) : PartialRender Deletes a comment and then refreshes the list
• onVisitProfile($property = null, post id, prop profilePage) : Redirect,false Redirects a user to a profile page if valid

Page Variables

• groups Collection of a users groups

Usage Examples

• Add the component to a page and utilize the inspector to choose the output type.
• You can also use the AJAX handlers directly if you wish.

Modules

How to extend UserExtended

If you are writing a plugin and you would like to use functions from UserExtended or provide your own functions, then this is the right place to come.

UserExtended provides two methods of extensibility. The old method is called User Utilities and the new method is called Modules.

Modules

Modules are a form of registration which plugins can use to directly interact with other modules as well as UserExtended.

Modules consist of:

• Meta data: $name, $description, $author, $version
• Overridden functions: injectComponents(), injectNavigation(), injectLang(), initialize()
• Extensible functions. While the functions and meta data above are required, extensible functions are entirely up to the module author and can be non existent.

How do I create a Module?

Please use the scaffolding command shipped with UE:

php artisan create:uemodule author.pluginName

author.pluginName is the plugin you wish to create a module for.

What are modules for?

Modules allow plugin authors to form a strict contract for what they would like other plugin authors to be able to manipulate and access with their plugin when it comes to User functions.

As an example, imagine you are writing a forum plugin. It may be useful for you to create a module which can return a users latest activity, a users post history, or user post stats. Rather then having other plugin authors snoop through your code and database tables, you can just create some simple extensible functions in your module and other plugin authors can use those directly.

Okay, so I made a module class, how do I register it?

To register your module, you will have to go into your plugin's plugin.php file and add the line Module::register() inside of the register function.

My module is registered, now how do I use them?

To use a module, you simply use the following syntax anywhere in your plugin. UserExtended::moduleName()->extensibleFunction($params);

The moduleName is the $name meta data defined within a module registration file.

What are module best practices?

The name of a module should be in a format like: authorModuleName as this helps prevent naming conflicts.

What if I want to check if other modules are loaded before providing features? What is this initialize function for?

The initialize function which you override to create a module, is called on each module after all the modules have been registered.

This allows you as a plugin dev to unlock more functionality if various other modules are loaded.

What are the injection functions for?

It allows you to add components, lang, navigation and more in the future to UserExtended!

User Utilities

UserExtended provides a class called UserUtil which has many common User based functions which you may find useful to use in your own plugins.

The long term goal is to move these functions into the UserExtended core module and deprecate User Utilities.

UserUtil

All functions in User Util are declared as static and should be used like UserUtil::function();

Function API

getUsers($value, $property = "name") : UserCollection Preforms a DB query for users with their $property = $value

getUser($value, $property = "id") : UserExtended Preforms a DB query for the first user with their $property = $value

getRainlabUser($value, $property = "id") : User Preforms a DB query for the first user with their $property = $value

getLoggedInUser() : User Returns the Rainlab User model for the logged in user

getLoggedInUsersTimezone() : string Returns the timezone code for the logged in user

getUserTimezone($value, $property = "id") : string Returns the timezone code for a user where their $property = $value

castToRainLabUser(UserExtended $user) : User Preforms a top level cast by transferring only the attributes of the UserExtended object to a User object (Fast)

castToUserExtendedUser($user) : UserExtended Preforms a top level cast by transferring only the attributes of the User object to an UserExtended object (Fast)

convertToUserExtendedUser($user) : UserExtended Preforms a low level conversion by preforming a DB query to populate the UserExtended object (Slow)

searchUsers($phrase) : UserExtendedCollection Searches for users via $phrase. It searches first name, surname, email, and username

getUsersIdElseLoggedInUsersId($userId = null) : int Gets the user ID for the logged in user, if no user is logged in, it returns the passed ID as a fallback

getUserForUserId($userId = null) : UserExtended Returns the UserExtended object for the user ID passed in. If the user ID passed in is null, gets logged in user

idIsLoggedIn($userId) : bool Returns whether or not a passed in ID is the ID of the logged in user

getLoggedInUserExtendedUser() : UserExtended Gets the logged in user object and converts it to an UserExtended user object before returning it

Timezone Trait

Usage

1. Add this trait to a model:

   use Clake\UserExtended\Traits\Timezonable;

2. Add a protected data member to your model:

   protected $timezonable = [
       'created_at',
       'updated_at'
   ];

   This contains model attributes to convert to a users timezone

3. The trait will automatically convert timezones when using the model attributes specified. Defaults to UTC.

Searchable Trait

Usage

1. Add this trait to a model:

   use Clake\UserExtended\Traits\Searchable;

2. Add a protected data member to your model:

   protected $searchable = [
       'email',
       'name',
       'surname',
       'username'
   ];

   This contains model attributes to search

3. Utilize the traits search function:

   $results = new Model();
   
   return $results->search($phrase);

Core Stable Release v2.2.00

With the latest release of User Extended (UE), we added a few DB seeders as well as created and changed some tables. This is the first of 4 feature development releases, but it should still be stable. We decided to go ahead and include two beta features, Routes Manager, and Module Manager. The Module Manager is capable of viewing version notes and documentation, but changing module settings do not actually do anything as of yet. The Routes Manager is working and stable, however, the way some of the whitelist and blacklist rules interact with each other can be confusing and will be cleaned up in the next release.

There are no extra steps you have to take for this release.

Creating modules for User Extended is a great way to promote compatibility between plugins. Please consider creating a module for your plugin, and if you post it on the October marketplace (and it meets expectations), we will feature your plugin on the front page of this plugin.

Core Stable Release v2.1.00

With the latest release of User Extended (UE), we included many DB changes in preparation for the next few releases. Now that the focus on stability, minor improvements, and bug fixing has completed, we are now going to start moving into feature development for releases v2.2.00, v2.3.00, v2.4.00 and v3.0.00

There are no extra steps you have to take for this release.

Many deprecated functions have been removed as well as all of the deprecated components. Please check your project as they may cause issues if you haven't removed the old ones.

Core Stable Release v2.0.00

With the latest release of User Extended (UE), I recommend running php artisan plugin:refresh clake.userextended as I did some work with Table dropping and forming to solve some bugs and problems. However, I did design these changes in such a way that it should be backwards compatible, however, refreshing the plugin will ensure that.

It's also important to note that many functions have been marked as deprecated. In the following release these functions will be removed from the code base. Please check your project if you have used any functions from UE. As well, the components marked deprecated in the beta release, have now been de-registered. For backwards compatibility, you can re-register these functions manually as the code still exists. However, many of these components are now broken because of changes I made to other parts of the code base. In the next release, the old components source code will be removed.

Please see the documentation pages and the Github wiki for more information.