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

Demo Videos

• Themes
• Positions
• Animated auto-arrange
• Queued
• Stacking
• Custom Pics
• Formatting

Table of Contents

• Usage
  • Standard Notification
  • Advanced notification
  • Pinned notification
• Helper Functions
• Server Events
• Parameters
• Default Config
• Custom Notification Pictures
• Notification Sound
• Formatting
• Pinned Notifications
• ESX Overrides
• To Do / Planned

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:

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

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

Legal Notices