j-Directory is part of the jComponent library from Total.js. You can find more information about j-Exec on componentator.com or GitHub.

It is a singleton component and after declaring can be used in a whole HTML document. This component will render options from your datasource to a user and they can choose one or more depending on your settings. It can be used as an independent component or in combination with j-Input (if you want to learn more about this usage, read my previous blog post). It works also with touches and supports dark mode. 

How to use j-Directory

As the first step you have to know how to use the jComponent library. I wrote about it in my previous blog, so for more information please read this blog post.

In this post, I want to show you how to use j-Directory independently.

Initialization

First, we have to initialize the j-Directory component in our code. Because it is singleton we will do it the same as with the j-Exec component on the top of our document after the body element.

<ui-component name="directory" config="placeholder:Search..."></ui-component>

As you can see, I added a config with a placeholder and text Search… because I want to have this placeholder displayed in an input of our directory to search for options. With this done, we can use our component in the whole code. 

To make this example work I will also use the component j-Exec, if you want to learn more about this component, please read this blog.

<span class="exec" data-exec="?/click">Click</span>

I created a span element with text Click and after clicking on it, we want to invoke a function, so I used exec to invoke function click in our PLUGIN.

When invoking a directory, we will do it with the method SETTER.

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    SETTER('directory/show', obj);
  };
});

In the code you can see the function click with argument el, which represents the clicked jQuery element. As the last thing in function, we have the method SETTER with two arguments. The first argument is string value 'directory/show' which means, that this setter calls the method show of directory component. The second argument is an object, which is designed for the setup of a particular directory. In this example, I used only the property element to our object, because I wanted to show just the rendering of j-Directory. Argument el is assigned to the property element and with this set, our component will be rendered in the correct place (on an element with the text Click on our page).

As you can see, our j-Directory is empty. That is because we didn't put any options there. We can add options easily by adding property items to object obj. 

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    obj.items = [{ name: 'Palo' }, { name: 'Peter' }, { name: 'Dodo' }, { name: 'Marek' }]; // added property
    SETTER('directory/show', obj);
  };
});

Now we have 4 options (Palo, Peter, Dodo and Marek) in property items. This property is an array of objects, each object includes property a name which is used as the default value for rendering in the directory.

Now, when we have options, we can move to handling the chosen option after clicking on it. To do this, we need to add another property to our object. This property is a callback. Callback is a function, which will be invoked after clicking on one of our options.

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    obj.items = [{ name: 'Palo' }, { name: 'Peter' }, { name: 'Dodo' }, { name: 'Marek' }];
    obj.callback = function(item) {
      console.log('item -->', item);  // added property
    };
    SETTER('directory/show', obj);
  };
});

The callback function can have more arguments, but in this case, we will use only the first, which is the item. This item retrieves us an object of the chosen option from the directory.

This is the core functionality of j-Directory. With this, you can handle in callback function all your desired functionality. Of course, searching in options is supported. 

Multiple select

There is also the possibility to configure j-Directory to handle the processing of selecting multiple options. For this, it is necessary to add a property checkbox to our obj object with a boolean value true.

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    obj.checkbox = true; // added property
    obj.items = [{ name: 'Palo' }, { name: 'Peter' }, { name: 'Dodo' }, { name: 'Marek' }];
    obj.callback = function(item) {
      console.log('item -->', item);
    };
    SETTER('directory/show', obj);
  };
});

 With this checkboxes will be added to our options in j-Directory. After clicking on one of these options directory will stay open and we can choose another.

As you can see in the example, after clicking on the option callback function is invoked and now instead of an object we are retrieving an array of objects. Every object includes properties as before, and with extra property selectedts. With this property, we can easily sort selected options by time, when they were selected. Every selected option can be also unselected by clicking on it.

Option highlighting

If you want to highlight some of the options you can do that by adding the template to the object with the desired object and adding code with Tangular.

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    obj.checkbox = true;
    obj.items = [{ name: 'Palo', template: '<b>{{ name }}</b>' }, { name: 'Peter' }, { name: 'Dodo' }, { name: 'Marek' }]; // added property template to first object
    obj.callback = function(item) {
      console.log('item -->', item);
    };
    SETTER('directory/show', obj);
  };
});

I used the HTML b tag for highlighting the first option.

As you can see that the first option Palo is bold with this template. You can do that also for all options easily with property render added to the obj object. This property needs a function returning HTML code.

Rendering of another property

If you don't want to render values from the property name in your directory, you can change the property where are these values saved by the property key added to the obj object.

PLUGIN('common', function(exports) {
  exports.click = function(el) {
    var obj = {};
    obj.element = el;
    obj.key = 'text'; // added property
    obj.checkbox = true;
    obj.items = [{ text: 'Palo' }, { text: 'Peter' }, { text: 'Dodo' }, { text: 'Marek' }]; // changed name of properties
    obj.callback = function(item) {
      console.log('item -->', item);
    };
    SETTER('directory/show', obj);
  };
});

Positioning and dimensions

You have more options to modify the positioning of a directory. First are properties align and position. Align is for positioning the directory horizontally with values left, right and top and position is for vertical positioning with values top and bottom.

Another option is to use the properties offsetX and offsetY. Here you have to use the number in pixels to move in the required directions.

For dimensions, there are properties height, minwidth and maxwidth. In these properties, you have to use the number in pixels for the dimensions of your directory.

Lazy component

j-Directory is a singleton component where you can use also LAZY. LAZY means lazy load, it means that the component will be loaded only when it is needed. It is useful for better performance because if a user doesn't need j-Directory, it won't be loaded.

<ui-component name="LAZY directory" config="placeholder:Search..."></ui-component>

It is very easy to use the LAZY component, everything you need to do is add the word LAZY in the initialization of j-Directory.

Video tutorial