bulletin

Customisable notifications for FiveM. Mimics native GTAV notifications, but allows more customisation

Features

No external libraries
Modern JS - no jQuery bloat
Customisable screen position
Customise the look by adding your own css overrides to ui/css/custom.css
Animated auto-arrange
Supports default GTA:V and custom notification pictures
Supports queueing
Supports stacking
Supports pinning
Supports color codes (~r~, ~b~, ~h~, etc)
Supports HTML as message

Usage

Standard Notification

exports.bulletin:Send(message, timeout, position, progress, theme, exitAnim, flash)

-- or 

exports.bulletin:Send({
    message = 'Message',
    timeout = 5000,
    theme = 'success'
    ...
})

Advanced notification

exports.bulletin:SendAdvanced(message, title, subject, icon, timeout, position, progress, theme, exitAnim, flash)

-- or

exports.bulletin:SendAdvanced({
    message = 'Some Message',
    title = 'Some Title',
    subject = 'Some Subtitle',
    icon = 'CHAR_BANK_MAZE',
    ...
})

Pinned notification

local pinID = exports.bulletin:SendPinned({
    type = 'advanced', -- or 'standard'
    message = 'This is pinned!',
    title = 'Title',
    subject = 'Subject',
    icon = 'CHAR_BANK_MAZE'
})

-- unpin
exports.bulletin:Unpin(pinID)

-- unpin multiple
exports.bulletin:Unpin({pinID1, pinID2, pinID3, ...})

-- unpin all
exports.bulletin:Unpin()

-- update content
exports.bulletin:UpdatePinned(pinID, options)

Helper Functions

These are shorthand methods for sending themed notification. They take the same params / table as the Send() method:

-- Send standard success notification
exports.bulletin:SendSuccess(...)

-- Send standard info notification
exports.bulletin:SendInfo(...)

-- Send standard warning notification
exports.bulletin:SendWarning(...)

-- Send standard error notification
exports.bulletin:SendError(...)

Server Events

All methods can be triggered from both the client and server:

-- standard
TriggerClientEvent('bulletin:send', source, ...)

-- advanced
TriggerClientEvent('bulletin:sendAdvanced', source, ...)

Parameters

These are passed as either individual params or in a table:

param	type	default	options	optional	description
`message`	`string`			NO	The message to send. Can be a string or valid HTML
`timeout`	`integer`	`5000`		YES	The duration in `ms` to display the notification
`position`	`string`	`"bottomleft"`	`"bottomleft"`, `"topleft"`, `"topright"`, `"bottomright"`, `"bottom"`, `"top"`	YES	The postion of the notification
`progress`	`boolean`	`false`	`true`, `false`	YES	Whether to display the progress of the notification timeout
`theme`	`string`	`"default"`	`"default"`, `"success"`, `"info"`, `"warning"`, `"error"`	YES	The theme of the notification
`exitAnim`	`string`	`"fadeOut"`	See `animate.css` for the options	YES	The animation used to hide the notification
`flash`	`boolean`	`false`		YES	Makes the notification blink
`title`	`string`			NO	The title of the notification (advanced only)
`subject`	`string`			NO	The subject / subtitle of the notification (advanced only)
`icon`	`string`			NO	The picture to use (advanced only)

Default Config

Config.Timeout          = 5000          -- Overridden by the `timeout` param
Config.Position         = "bottomleft"  -- Overridden by the `position` param
Config.Progress         = false         -- Overridden by the `progress` param
Config.Theme            = "default"     -- Overridden by the `theme` param
Config.Queue            = 5             -- No. of notifications to show before queueing
Config.Stacking         = true
Config.ShowStackedCount = true
Config.AnimationOut     = "fadeOut"     -- Default exit animation - overriden by the `exitAnim` param
Config.AnimationTime    = 500           -- Entry / exit animation interval
Config.FlashCount       = 5             -- No. of times the notification blinks when `flash` param is used
Config.SoundFile        = false         -- Sound file stored in ui/audio used for notification sound. Leave as false to disable.
Config.SoundVolume      = 0.4           -- 0.0 - 1.0

Config.Pictures = {
    -- advanced notification icons
}

Custom Notification Pictures

To add your own custom picture, upload a 64x64 jpg image to the ui/images directory and add the custom code and filename to the Config.Pictures table in config.lua,

Example

Upload my_custom_icon_image.jpg to the ui/images directory and use MY_CUSTOM_ICON_CODE (NO SPACES!) as the key.

Config.Pictures = {
    ...
    MY_CUSTOM_ICON_CODE = "my_custom_icon_image.jpg" -- Add this
}

Then use the custom code in the notification call:

exports.bulletin:SendAdvanced("Message", "Title", "Subject", "MY_CUSTOM_ICON_CODE")

Notification Sound

You can enable a notification sound by uploading a custom sound file to the ui/audio directory and editing the config to use it:

Config.SoundFile        = 'my_notification_sound.mp3'
Config.SoundVolume      = 0.4

Valid audio files: .mp3, .ogg, .wav

Formatting

Bulletin supports the following formatting:

\n = new line
~r~ = Red
~b~ = Blue
~g~ = Green
~y~ = Yellow
~p~ = Purple
~o~ = Orange
~u~ = Black
~w~ = White
~h~ = Bold Text

You can also use HTML for colors:

exports.bulletin:Send("<span class='r'>I am red</span> and <span class='y'>I am yellow</span>")

or any HTML you like

exports.bulletin:Send("<h1>Some Title</h1><p class='paragraph'>Some text</p><footer>Some footer text</footer>")

Pinned Notifications

In order to send a pinned notification, you'll need to store the notification's pin_id so you can unpin it later.

local pinID = exports.bulletin:SendPinned({
    type = 'advanced' -- or 'standard'
    message = 'This is pinned!'
})

Then to unpin it just pass the stored value to the Unpin() method:

exports.bulletin:Unpin(pinID)

The Unpin() method also accepts a table of pin ids:

exports.bulletin:Unpin({pinned1, pinned2, pinned3})

or omit the param to unpin all:

exports.bulletin:Unpin()

You can also update the content of a pinned notification:

-- Send pinned notification
local pinID = exports.bulletin:SendPinned({
    type = 'advanced',
    message = 'This is pinned!',
    title = 'Title',
    subject = 'Subject',
    icon = 'CHAR_BANK_MAZE',
    theme = 'success'
})

-- Update it's content
exports.bulletin:UpdatePinned(pinID, {
    message = 'Updated message!',
    title = 'Updated title',
    subject = 'Updated subject',
    icon = 'CHAR_TREVOR',
    theme = 'error',
    flash = true
})

Only the message, title, subject, icon, theme and flash options can be updated at the moment.

Pinned notifications are not queued so, for example, if you set Config.Queue to 5 and you have 2 pinned notifications, you'll get a max of 7 notifications shown at any time.

ESX Overrides

If you're using ESX then you can get bulletin to override the notifications by editing the appropriate functions in es_extended/client/functions.lua:

ESX.ShowNotification = function(msg)
    -- SetNotificationTextEntry('STRING')
    -- AddTextComponentString(msg)
    -- DrawNotification(0,1)
	
    exports.bulletin:Send(msg)
end

ESX.ShowAdvancedNotification = function(sender, subject, msg, textureDict, iconType, flash, saveToBrief, hudColorIndex)
    -- if saveToBrief == nil then saveToBrief = true end
    -- AddTextEntry('esxAdvancedNotification', msg)
    -- BeginTextCommandThefeedPost('esxAdvancedNotification')
    -- if hudColorIndex then ThefeedNextPostBackgroundColor(hudColorIndex) end
    -- EndTextCommandThefeedPostMessagetext(textureDict, textureDict, false, iconType, sender, subject)
    -- EndTextCommandThefeedPostTicker(flash or false, saveToBrief)
	
    exports.bulletin:SendAdvanced(msg, sender, subject, textureDict)
end

To Do / Planned

Reduce number of params in favour of table of options
Support stacking
Support notification sound
Support pinned notifications
Support user-defined entry animations (currently only supports exit animations)

Legal Notices

bulletin

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program.
If not, see https://www.gnu.org/licenses/

mobius1 / bulletin Goto Github PK

bulletin's Introduction

bulletin

Features

Demo Videos

Table of Contents

Usage

Standard Notification

Advanced notification

Pinned notification

Helper Functions

Server Events

Parameters

Default Config

Custom Notification Pictures

Example

Notification Sound

Formatting

Pinned Notifications

ESX Overrides

To Do / Planned

Legal Notices

bulletin's People

Contributors

Stargazers

Watchers

Forkers

bulletin's Issues

Recommend Projects

Recommend Topics

Recommend Org