feat(relations): allow to hide or rename pivot attribute on belongsTo…

[italoiz]

Proposed changes

Allow to hide or rename pivot attribute from belongsToMany relationships.

How to use

When you create a relationship belongsToMany, you may want to hide the pivot attribute that is displayed by default. There are a few ways to do this.

First way

Adding a $pivot special field to the list of hidden fields on pivot model.
See https://adonisjs.com/docs/4.1/lucid#_hiding_fields

class PostUser extends Model {
  static get hidden () {
    return ['$pivot']
  }
}

Second way

Like .pivotModel() and other available methods, you can use a new .pivotAttribute() method to rename or hide the pivot attribute. If passing false is going to hide the field, if passing a string will rename it.
See https://adonisjs.com/docs/4.1/relationships#_belongs_to_many

// example 1
class Post extends Model {}

class PostUser extends Model {}

class User extends Model {
  posts () {
    return this.belongsToMany(Post)
        .pivotModel(PostUser)
        .pivotAttribute(false) // hide `pivot` attribute.
  }
}

// example 2
class Post extends Model {}

class PostUser extends Model {}

class User extends Model {
  posts () {
    return this.belongsToMany(Post)
        .pivotModel(PostUser)
        .pivotAttribute('rename_pivot') // rename `pivot` to `rename_pivot` attribute.
  }
}

Third way

Similarly to the static get hidden () {} static method, you can use a new static method called static get pivotAttribute () {}. If it returns false it will hide the pivot attribute, returning a string will rename the pivot attribute.
See https://adonisjs.com/docs/4.1/lucid#_hiding_fields

// example 1
class PostUser extends Model {
  static get pivotAttribute () {
    return false // hide `pivot` attribute.
  }
}

// example 2
class PostUser extends Model {
  static get pivotAttribute () {
    return 'renamed_pivot' // rename `pivot` to `rename_pivot` attribute.
  }
}

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• I have read the CONTRIBUTING doc
• Lint and unit tests pass locally with my changes
• I have added tests that prove my fix is effective or that my feature works.
• I have added necessary documentation (if appropriate)

Further comments

Related to #366

[coveralls]

Coverage increased (+0.09%) to 96.593% when pulling 8b95787 on italoiz:feat/allow-hide-pivot-attr into 6cd666d on adonisjs:develop.

[italoiz]

Is there anything new about this?

[MarcosGin]

+1

[thetutlage]

Thanks 😄