djs-forms

djs forms is a little extension to discord.js This module helps you to manage RichEmbed, with some templating methods, and catch all MessageReactions easyly.

If you are building a discord bot and you want to easyly interact with the users, this module will provide you a component-like management of your RichEmbed forms

Getting Started

• Install the package

npm i djs-forms

• Import Statement

import form from 'djs-form'

Prerequisites

You will need an existing discord bot project, with at least an event that can handle the post creation

bot.on('message', msg => {
    if (msg.content === "hello") {
            //create a form instance
            let f = form(bot, msg.channel);

            //then create how many post you want
            let helloPost = f.createPost({
                post: {
                    content: 'New message',
                    embed: new djs.RichEmbed()
                        .setAuthor('Romuald')
                        .setTitle('Hello World')
                }
            });
            //then just display it, this will build the post and render it
            f.display(helloPost);
            //or
            helloPost.dispay()
        }
    })

Docs

Post Creation

to create a post you can either use the Builders Methods : - Post.setPost(post: PostData | PostBuilder) : Post - Post.setReacts(reacts: ReactsData | ReactsBuilder, handler: ReactsHandler) : Post - Post.setGlobal(builder: GlobalData | GlobalBuilder, handler: ReactsHandler) : Post or you can define rules of the post :

f.createPost(rules?: PostCreatorOptions): Post

rules need to be defined following one of those formats

interface PostCreatorOptions {
    postBuilder?: PostBuilder,
    globalBuilder?: GlobalBuilder,
    reactsBuilder?: ReactsBuilder,
    reactsHandler?: ReactsHandler,
    post?: PostData,
    reacts?: ReactsData
}

type PostBuilder = (ops: any) => PostData | Promise<PostData>;
type GlobalBuilder = (ops: any) => GlobalData | Promise<GlobalData>;
type ReactsBuilder = (ops: any) => ReactsData | Promise<ReactsData>;
type ReactsHandler = (react: djs.MessageReaction, state: StateProvider) => void;

type ReactsData = React[];
type React = string;

interface PostData {
    embed?: djs.RichEmbed,
    content?: string
}

interface GlobalData {
    reacts: ReactsData,
    post: PostData
}

post || postBuilder

f.creatPost({
    post: {
        embed: new djs.RichEmbed()
            .setAuthor('Romuald')
            .setTitle('Hello world'), 
        content: 'New message'
    },
})

or

f.creatPost({
    postBuilder(ops) { //example on given ops: {author: 'Romuald'}
        let embed = new djs.RichEmbed()
            .setAuthor(ops.author)
            .setTitle('Hello world'), 
        let content = 'New message'
        return { embed, content }
    },
})

same as the upper one but you have access to the ops parameter which has provided when doing f.display(post, ops)

f.creatPost({
    async postBuilder(ops) { //example on given ops: {id: '2134'}
        let author = await fetchFromApi('someapi.com/user?id=' + ops.id)
        let embed = new djs.RichEmbed()
            .setAuthor(author)
            .setTitle('Hello world'), 
        let content = 'New message'
        return { embed, content }
    },
})

This function can also be async returning a Promise that resolves {embed, content}

f.creatPost({
    postBuilder(ops) { //example on given ops: {id: '651'}
        return new Promise(async resolve => {
            let author = await fetchFromApi('someapi.com/user?id=' + ops.id)
            let embed = new djs.RichEmbed()
                .setAuthor(author)
                .setTitle('Hello world'), 
            let content = 'New message'
            resolve({ embed, content })
        })
    },
})

Same as the previous one.

(post || postBuilder) && (reacts || reactsBuilder) && reactsHandler

reacts and reactsBuilder work the same way as post and postBuilder you only need one of both. Unless, if you declare a reacts or reactsBuilder statement you will need to define a reactsHandler method

f.creatPost({
    post: {
        embed: new djs.RichEmbed()
            .setAuthor('Romuald')
            .setTitle('Hello world'), 
        content: 'New message'
    },
    reacts: ['🥃','🍇','💼'], 
    reactsHandler(react) {
        console.log('reaction!', react.emoji.name)
    }

reacts contains an Array of unicode emojis

f.creatPost({
    post: {
        embed: new djs.RichEmbed()
            .setAuthor('Romuald')
            .setTitle('Hello world'), 
        content: 'New message'
    },
    reactsBuilder (ops) { //example on given ops: {Quit: '❎ ', Prev: '⏪', Next: '⏩', Ok: '✅'}
        let emojis = [ops.Quit, ops.Prev, ops.Next, ops.Ok]
    }, 
    reactsHandler(react) {
        console.log('reaction!', react.emoji.name)
    }
})

Same as the upper one but you have access to the ops parameter which has provided when doing f.display(post, ops). This function can also be async returning a Promise that resolves an Array of unicode emoji.

globalBuilder && reactsHandler

The globalBuilder permits to build the post and the reacts in the same statement, It returns and Object containing an {embed, content} Object as post and an Array of unicode emoji as reacts. You also need a reactsHandler because you are also building emojis.

f.createPost({
    globalBuilder (ops) { //example of given ops: {author: 'Romuald'}
        let embed = new djs.RichEmbed()
            .setAuthor(author)
            .setTitle('Hello world');
        let content = 'New Message';
        return {
            post: {embed, content}, reacts: ['🥃','🍇','💼']
        }
    },
    reactsHandler (react) {
        console.log('reaction!', react.emoji.name)
    }
})

Of course it can be asyncronous, same as before.

post.setPost(post: PostData | PostBuilder): Post

post can be either a PostData Object or an sync/async function that return a PostData Object

interface PostData {
    embed: djs.RichEmbed,
    content: string
}

type PostBuilder = (ops: any) => PostData | Promise<PostData>  

Same as defining rules.post, or rules.postBuilder

post.setReacts(ReactsData | ReactsBuilder, ReactsHandler): Post

type ReactsData = string[];

type ReactsBuilder = (ops: any) => ReactsData | Promise<ReactsData>  

type ReactsHandler = (react: djs.EmojiReaction) => void  

Same as defining rules.reacts, or rules.reactsBuilder and rules.reactsHandler

post.setBuilder(GlobalData | GlobalBuilder, ReactsHandler): Post

interface GlobalData {
    post: PostData,
    reacts: ReactsData
};

type GlobalBuilder = (ops: any) => GlobalData | Promise<GlobalData>  

type ReactsHandler = (react: djs.EmojiReaction) => void  

Same as defining rules.post and rules.reacts, or rules.globalBuilder and rules.reactsHandler

post.build(ops: any)

Execute the builders, provided before, with ops ops Prepare for displaying

post.display(ops: any)

Execute the buid

f.display(post: Post, ops?: any)

The post parameter is a Post provided by the f.createPost() method The ops parameter is an Object which contains all the data you want to pass to the postBuilder | reactsBuilder | globalBuilder

let post = f.creatPost({
    post: {
        embed: new djs.RichEmbed()
            .setAuthor('Romuald')
            .setTitle('Hello world'), 
        content: 'New message'
    },
    reactsBuilder (ops) {
        let emojis = [ops.Quit, ops.Prev, ops.Next, ops.Ok]
    }, 
    reactsHandler(react) {
        console.log('reaction!', react.emoji.name)
    }
})

f.display(post, {Quit: '❎ ', Prev: '⏪', Next: '⏩', Ok: '✅'});

f.onReplies(handler: (msg) => void, filter?: (msg) => boolean)

f.onReplies(msg => {
    console.log('reply!', msg.content)
})

Get all Messages sent on the Channel provided at let f = form(bot, msg.channel)

f.onReplies(msg => {
    console.log('reply!', msg.content)
}, msg => msg.mentions.members.get(bot.user.id) ? true : false)

Get only the Messages which @mention the bot, sent on the Channel provided at let f = form(bot, msg.channel)

Examples

See Example

See Example1

See Example2

Authors

• MaxBly - Initial work - MaxBly

License

This project is licensed under the ISC License