Backend Back to HelloVib

Add Components to Manager

¿HOW DOES IT WORK?

Our component manager allows to show, in a clean and interactive UI, all the parameters accepted by a component, indicating if they are required or not, displaying a description or tip text and, more importantly, permitting to change the parameters values and see the resultant component in real time. Also, the UI shows the proper input control for every parameter and is capable to validate the inputs according to each component's documented rules.

We put special care to make very easy adding new components to the manager. All you have to do is documenting your component following certain conventions.

EXAMPLE

It is really easy to get started. Check the components included in the package to get familiar with a little more advanced examples.

PHPDOC BLOCK

The component's phpdoc block must include the following elements in order to make it compatible with the component manager.

  • NAME - The name of your component.
  • DESCRIPTION - A brief description of what your component does, it may include html markup.
  • @directive - What kind of blade directive your component will use (component or include). This tag is mandatory.
  • @managed - If this tag is not present, the component manager will ignore this component.
  • @slot - In case your component uses the 'component' directive you may use this tag to interact with the slots included in your component.
    It uses the form: @slot slot_name example_slot_content. Where slot_name should be 'default' for the anonymous blade slot of the component.
  • @param - Definition of every parameter accepted by the component. See below for more detail.

With this information in its phpDoc, your component will be included in the component manager. The key to be able to play with your component in th CM is in the @param tag. This key tag has the following structure:

    @param
        variable_type[:laravel_validation_parameter]
        $parameter_name
        [description][|o][|i=type_of_input:{comma_separated_input_parameters}][|d=default_value][|e=example_value]

Where:

  • variable_type - Php variable type (ie. string, array, bool)
  • laravel_validation_parameter - If you wish to make server side validation of the input (ie. url, integer, array)
  • description - Brief text for explanation or help on the parameter
  • o - If included, the parameter is marked as optional
  • i - Indicates the type of input to show at the UI, if not included the input will be text
  • type_of_input - text, textarea, select:{options_separated_by_comma}, number:{min,max,step,units}, color, colorAlpha or switch:{on_label,off_label}
  • d - Pass the default value of the parameter to the UI
  • e - Pass the example value of the parameter to the UI

OPTIONAL TAGS

  • @group - Tells the UI to show the component as part of a specific group in the menu. If not present the UI will include it in the 'General' group.
  • @alias - If your component has a blade alias you can tell the UI to use it by declaring this tag
  • @link - Optional tag to include a link in form of a button below the component description.
    It uses the form: @link url button_label
  • @version - Version of the component.
  • @author - Author of the component.
  • @copyright - Copyright notes of the component.

COMPONENTS FOLDER

You can use any view folder you want for your components files. By default, the CM will look for custom components at:
Resources/Views/Components
And therefore, it will use following view path for them:
components.you_component_file_name

To change the custom component folder or add additional ones, go to the 'vibrant' file in the config folder and modify the 'custom_components_paths' parameter to your needs.