Greppy Frontend - Documentation ¶

The Greppy Frontend's documentation explains how to use and maintain the library and applications build with it.

The lead developer and maintainer of this project is Hermann Mayer (hermann.mayer92@gmail.com). For feedback or suggestions compose an issue on Github.

Structure ¶

The Greppy Frontend source is divided into multiple js-files and mostly follows the rule one class per file.

• header.js Contains code which will be executed first.

• application.js Contains the application class. Allows easy modal handling.

• controller.js Contains the controller class. Allows easy link generation.

• data-grid.js Contains the base class for the data-grid.

• data-grid/

  • pagination.js Contains the paginator class which allows paginating of the data-grid.

  • search.js Contains the search class which handles search operations of the data-grid.

  • sort.js Contains the sort class which handles sorting of the data-grid.

• styler.js Contains the styler class. Allows easy styling of different elements.

• styler/

  • number.js Contains the number-styler. Allows adding a number spinner to inputs.

  • upload.js Contains the upload-styler. Allows "styling" an upload to look like BS3.

• validator.js Contains the validator class. Allows better HTML5 validation for bootstrap elements.

• footer.js Contains code which will be executed last.

The files are concatenated into one .js (and .min.js respectively) on building.

Header ¶

The header contains code, which is executed before every other file.

When concatenating the source file to greppy.js and greppy.min.js, the header contents will be placed first.

Examples ¶

Currently, the global greppy is being defined in the header:

var greppy = {};

Application ¶

The application class is used for application-related functionality.

Methods ¶

dialog(body, options, buttons) ¶

Example usage:

greppy.app.dialog(
  'Logout every user?',
  {
    ok: function(callback) {
      logoutAllUsers();
      callback && callback();
    }
  }
);

Here, we provide only two parameters: The body of the modal and an option for the ok-button.

This basically says: If the user clicks the ok-button, call the function we provided. The provided function's main purpose is to call the logoutAllUsers function. But we also need to take and call the callback, so the modal internals work.

We could also extend the second parameter to provide a function for the cancel-button:

greppy.app.dialog(
  'Logout every user?',
  {
    ok: function(callback) {
      logoutAllUsers();
      callback && callback();
    },
    cancel: function(callback) {
      goBack();
      callback && callback();
    }
  }
);

So now, if the user clicks cancel, our goBack-function will be called.

Controller ¶

The controller class is currently only used to generate links.

Methods ¶

link(action. params) ¶

First, pass an options object as an argument to the constructor of the class:

myController = new greppy.Controller({
    basePath: 'my/path/',
    actions: {
        show: {
            path: 'show/:id'
        }
    }
});

Now you can generate links with the link() method:

var link = myController.link('restore', {id: 23});

The first parameter names the action, which we are referring to. The second one is an object containing the desired parameters for our generated url.

The method will automatically recognize the parameter(s) in the path and replace them with the passed values.

So in our case, link() would equal: my/path/show/23

Data-Grid ¶

The data-grid class is responsible for the core data-grid functionality.

It's constructor instantiates some other relevant data-grid classes:

• Search
• Sort
• Paginator

They are assigned to properties of the data-grid instance.

Methods ¶

The following methods are offered by the data-grid class:

load(rows, pagination, page) ¶

This method is used to trigger loading of the data-grid. The parameters are all optional and allow defining custom settings for rebuilding.

By default, the first two parameters, rows and pagination, are true which means that the rows and the pagination will be updated.

The third parameter, page, can be used to define a custom page which should be loaded. Providing it is only needed, if you don't want the data-grid to handle the current page.

If you'd want to update only the pagination (and not the rows), you could simply pass a false as the first argument:

load(false);

It's quite similar, if you'd only want the rows to be updated:

load(true, false);

buildUrl(params) ¶

Only used in internals.

loadAndRebuild(params, callback) ¶

Only used in internals. Executes preLoad-hooks (if any exist) and sends the AJAX-request to load the rows and update the table.

reset() ¶

Only used in internals. Reloads the data-grid. If there's a preReset-hook provided, it's executed with the reload-function as first argument.

Examples ¶

Initialize a new data-grid with softDeletion-option:

var datagrid = new greppy.DataGrid($('table.datagrid'), {
    softDeletion: true
});

Paginator (Data-Grid) ¶

The paginator class is meant to be used in conjunction with the data-grid class. In fact, it will be instantiated by the data-grid class most of the time.

As it's name suggests, it mainly handles pagination-related functionality; mostly event handling of the paginator, to be precise.

Methods ¶

getParameters(page) ¶

Only used in internals. Returns an array of objects with relevant parameters (page and limit). The page-parameter is optional and defaults to the page of the instance.

Examples ¶

None at this time. Please refer to data-grid.

Search (Data-Grid) ¶

The search class is meant to be used in conjunction with the data-grid class. In fact, it will be instantiated by the data-grid class most of the time.

Methods ¶

settings(property, placeholder) ¶

Only used in internals. Customizes the search-box according to the provided arguments.

clear() ¶

Only used in internals. Clears the search-box.

getParameters() ¶

Only used in internals. Returns an array of objects with relevant parameters (search and sprop).

Examples ¶

None at this time. Please refer to data-grid.

Sort (Data-Grid) ¶

The sort class is meant to be used in conjunction with the data-grid class. In fact, it will be instantiated by the data-grid class most of the time.

It is responsible for attaching sort-related events and handling sort-operations.

Methods ¶

toggle(th) ¶

Only used in internals. Clears eventually exiting old sort-settings and applies sorting regarding the current settings. If there's no sorting specified, the data-grid will simply be reset by calling it's reset-method. Else, the load-method of the associated data-grid- object will be called.

getParameters() ¶

Only used in internals. Returns an array of objects with relevant parameters (order and oprop).

Examples ¶

None at this time. Please refer to data-grid.

Styler ¶

The styler class offers easy to use methods for enhancing the ui.

Methods ¶

initOverlay(el, showEvent, removeEvent) ¶

With help of this method, you can create a dynamic overlay for an element of your choice (first parameter). This is especially useful for situations where a page is loading for some time. The overlay will have a spin.js based spinner in it.

Parameters:

• el The element which should be covered by the overlay
• showEvent The event which triggers the overlay to be shown
• removeEvent The event which triggers the overlay to be removed

initSpinner(target, opts) ¶

Only used internally.

Number (Styler) ¶

The number class is used to style an input element (or a set of input elements) to have a number spinner attached to them.

Methods ¶

style(el) ¶

The only relevant method for the end user (that's probably you!). el might be a selector string or a jQuery object. If you pass a selector or a set of jQuery elements, ensure that every element is an input element. style will then style the passed elements.

More methods (these are used mainly internally) ¶

validate(el) ¶

handleCleanup(el) ¶

addStyles(el) ¶

addButtonHandlers(el) ¶

getVal(el) ¶

getAddedVal(el) ¶

getSubtractedVal(el) ¶

isNumber(el) ¶

clearStyled(el) ¶

Upload (Styler) ¶

The upload class is used to style an input[type="file"] element (or a set of such elements) to have them replaced by elements in Bootstrap 3 look.

Methods ¶

style(el) ¶

The only relevant method for the end user (that's probably you!). el might be a selector string or a jQuery object. If you pass a selector or a set of jQuery elements, ensure that every element is an input[type="file"] element. style will then style the passed elements.

More methods (these are used mainly internally) ¶

validate(el) ¶

addStyles(el) ¶

getMarkup(el) ¶

showFilename(el) ¶

getStyledUploadSelector(el) ¶

handleFilePreselected(el) ¶

addNewFileSelectedHandler(el) ¶

addButtonHandlers(el) ¶

showFileDialog(el) ¶

hideOriginalInput(el) ¶

Validator ¶

The validator class offers a clean and uniform HTML5 validation for bootstrap elements.

How to use it ¶

Simply add the class greppy-validator to every input, select or textarea element you want to be validated. Then just use regular HTML5 validation attributes to define validation rules.

Greppy will then show a red box with an error message, if the validation fails.

Attributes ¶

Attributes help you customizing the behavior of validators. They are optional.

• data-greppy-validator-msg You can define a message for a failing validation here. If added, it needs to be placed either to the element which has the data-greppy-validator-mark-attribute (preferred for radio buttons) or directly to the validated element.

• data-greppy-validator-mark Defines the element which is marked on failed validation and under which the validation message is placed. The value must be the name of the corresponding validated element.

Multiple Elements with the same name ¶

If there are multiple elements with the same name - which can occur when using radio buttons - you need to give every one of them the class greppy-validator. However, duplicating the message or mark would be annoying in our opinion, so Greppy validator only considers the attributes of the first matched element if there is more than one element with the same name.

Methods ¶

Except the init-method, most methods aren't really important for simple usage of the validator - just use attributes to define basic behavior. But in case you need advanced functionality, you have to take a look at the methods described here.

init() ¶

Simply call it, to initialize the Greppy validator. By default, it searches for all input-, select- and textarea-elements with the class greppy-validator and registers the following events triggered by them: invalid, change, keyup.

bindEvent(origEvtName, gEvtName) ¶

This one is useful, if your inputs are modified by third party plugins, which trigger custom events. Since Greppy validator does only register the standard events by default, it can't always properly revalidate elements with custom behavior. To fix this, simply call bindEvent with the following parameters:

• origEvtName A string with the event you'd like to register
• gEvtName The corresponding Greppy validator event as String.

gEvtName may be either gValidationUpdate or gValidationInvalid. You will probably mostly use gValidationUpdate, which checks if the element is valid and shows/removes the warning if it is/isn't. For more details, see the section Events.

getMark(el) ¶

The getMark-method will return the corresponding mark of the element (which may be the element with the corresponding data-greppy-validator-mark attribute or the passed element itself). Use it if you need to know, what will be marked on validation.

More methods (these are used mainly internally) ¶

isUniqueValidator(el) ¶

getUniqueValidator(el) ¶

getUniqueValidators(allValidators) ¶

validate(el) ¶

markInvalid(el) ¶

removeInvalidMark(el) ¶

showMsg(el) ¶

hasActiveMsg(el) ¶

removeMsg(el) ¶

Events ¶

Greppy validator uses two events internally: gValidationUpdate and gValidationInvalid.

It's recommended to not directly attach these events and instead make use of the bindEvent-method to register custom events.

gValidationUpdate will basically check if the corresponding element is valid or invalid and display or remove the warning message according to it's state.

gValidationInvalid will show the warning message and prevent the default behavior of the element (which is especially useful to suppress displaying the default browser messages for HTML5 validation).

Footer ¶

The footer contains code which is executed after every other file.

When concatenating the source file to greppy.js and greppy.min.js, the footer will be appended last.

Examples ¶

Currently, the application class is being instantiated in the footer:

greppy.app = new greppy.Application();

Building ¶

When you make changes to the greppy source, you probably want to (re-)build the files at some point.

Requirements ¶

You should have node.js installed. If you have, switch to the greppy-folder via terminal and run the command npm install. This will install the required dependencies.

Start building ¶

Building is done via make.

The following targets are currently available in the Makefile:

• dist: Build css and js.
• dist-js: Build js only.
• dist-css: Build css only.

So if for example you'd like to have your changes to source files translated to minified versions, you'd simply switch to the greppy-folder via terminal again and run the command make dist. The files located in the dist-folder will be replaced with new ones based upon the current sources.