ManageMe

Make view system usage easy

⚠️ Breaking Change - Version 6.0.1

Important: Starting from 6.0.1, ManageMe no longer initialize views automatically. Views importation and initialization should be done via the project.

⚠️ Breaking Change - Version 5.0.0

Important: Starting from version 5.0.0, the HTML attributes have been changed for W3C compliance:

• me:view → data-me-view
• me:view:data → data-me-view-data

If you're upgrading from version 4.x, you'll need to update your HTML templates to use the new data- prefixed attributes.

Before (v4.x):

<div me:view="DemoView" me:view:data='{"key": "value"}'>

After (v5.0.0):

<div data-me-view="DemoView" data-me-view-data='{"key": "value"}'>

Installation

First of all, you must allow your project to download the package.

To do so, make sure you have a .npmrc file (at the same level as the package.json file) containing the following code:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Replace ${NPM_TOKEN} by the token you will find in Zoho behind NPM - Clé installation package.

Then, add the package to your project:

$ npm install @quatrecentquatre/manage-me

Usage

First, import the library in your main JS file:

import '@quatrecentquatre/manage-me'

Then, you're already good to go and create your first view!

Create your first view

To create a view, you'll need to add in a JS file the following code:

import { ViewBasic } from '@quatrecentquatre/manage-me'

export class ClassName extends ViewBasic {
	constructor(options) {
	    super(options);
	}
	
	initialize() {
        this.addEvents();
    }
	
	addEvents() {}
	
	terminate() {
	    this.removeEvents();
	}
}

Me.views['ClassName'] = ClassName;

You'll need to replace 'ClassName' by the name you want and that represent what the class refers to.

The last line is very important. Do not forget to copy paste it!

Now, import your view in your main file:

import './path/to/className/file';

After adding the Javascript part, you'll need to add some HTML to tell your view on what it need to be applied on.

You need to add an attribute on the element you need the view to be applied on. That attribute is data-me-view and you need to assign a string to that attribute. That string must be the class name you set in the Javascript part.

<div id="demo" data-me-view="DemoView"></div>

Then when the page will be loaded, the ViewManager will take care of everything. It will create your DemoView and initialize() will be call. You can add a console.log() to confirm that it enters the initialize() method.

Pass data to your view

If you need data provided by the Backend in your Javascript view, you can add a simple attribute. On the same element where the data-me-view is set, you can add the attribute data-me-view-data.

PHP

<!-- $data is an object -->
<div
  id="demo"
  data-me-view="DemoView"
  data-me-view-data="<?php echo json_encode($data, JSON_HEX_APOS); ?>"
></div>

TWIG

<!-- data is an object -->
<div
  id="demo"
  data-me-view="DemoView"
  data-me-view-data="{{ data|json_encode(constant('JSON_HEX_APOS')) }}"
></div>

Once added, you'll be able to retrieve this data in your Javascript view. Simply use this.params:

//Add a console.log in the initialize function of your view

initialize() {
    console.log(this.params);
}

ViewManager functions

Initialize new view

In case you need to add DOM and that DOM has a view in it, you'll need to call a function to create and initialize all of the new views added to the DOM. Right after you append new DOM, simply call the initViews() function of Me.manage.

initViews() accepts one parameter. This parameter define where the ViewManager will search for new views in the DOM. The parameter must be an element.

Me.manage.initViews();
// or
Me.manage.initViews(document.querySelector(".container"));

Clear deleted views

When deleting DOM that contains one or multiple views, you should clear them. Simply call the clearViews() function of Me.manage and the ViewManager will take care of the rest. Just don't forget to remove all events in the removeEvents() function of every view.

Me.manage.clearViews();

In every view that will be deleted we make sure that all events are removed through the removeEvents function.

ViewBasic functions

defaults()

This is the function where you set the default params for your class.

defaults() {
    return {};
}

initialize()

This is the function that will be call by the ViewManager once all views are created. You can declare options, variables, etc ... Most of the time it will end with a call to the addEvents() function.

initialize() {
    //Add thing here before addEvents

    this.addEvents();
}

afterAllViewInitialize()

This function will be triggered once all views are created. If you're looking to trigger an event when the view is loaded, you should trigger the event in this function. That way you'll be sure that all class will exist.

afterAllViewInitialize() {
  //Example
  Me.dispatch.emit('event-name', this, {});
}

addEvents()

This is where you set most of your listeners.
Use the custom function addEventListener to enable automatic cleanup.

addEvents() {
    const button = this.el.querySelector('.btn');
    this.addEventListener(button, 'click', ...);
}

How to use

this.addEvents();

removeEvents()

All your listeners created with this.addEventListener will be removed automatically. This function will be called by terminate() once the view is deleted.
If you need to overwrite it, don't forget to call super.removeEvents();

You can also use this.removeEventListener(element, type, listener, options).

removeEvents() {
    super.removeEvents();
}

How to use

this.removeEvents();

terminate()

Usualy, you do not have to modify this function. It is called when you delete a view and then it will call removeEvents() function

terminate() {
    this.removeEvents();
}

How to use

this.terminate();

bindAll(methodNames)

Use this method when you want to .bind(this) to your methods so that you can use this in them.

How to use

this.bindAll(["yourFunctionName", "yourOtherFunctionName"]);

Development

Build the library

This project uses Vite to build and minify the library. The source files are located in the lib/ directory and the compiled output is generated in the dist/ directory.

To build the library:

$ npm run build

This will:

• Take the entry point from lib/manage-me.js
• Bundle all the source files from the lib/ directory
• Generate the minified distribution file as dist/manage-me.js
• The output format is ES modules

Development mode

For development with live reloading:

$ npm run dev

This will start a development server using Vite.

Build configuration

The build configuration is defined in vite.config.js:

• Entry point: lib/manage-me.js
• Output: dist/manage-me.js
• Format: ES modules
• The library is bundled with all dependencies included

After making changes to the source files in lib/, make sure to run npm run build to update the distribution file.

To publish the package to NPM registry:

1. Make sure to update the version in the package.json file and update the CHANGELOG.md file
2. Run npm run build to update the distribution file
3. Run npm login, you will need OTP (Authy)
4. Run npm publish to publish the package to NPM registry