|
|
aVquickEditTutorial
A simple tutorial about quickEdit library.
Introduction
quickEdit library can be used in order to make the elements in your websites editable very easily. We hope that you wont get shocked by the simplicity of the usage.
Details
Let's assume that you have a website as below :
<head> <title> My Id </title> <link type="text/css" rel="stylesheet" href="style.css"> </head> <body> <div id="idCard"> <img src="images/aV.gif" id="idPicture" alt="Me!" /> <ul id="idInfo"> <li>Name : <span id="idName">amplio</span></li> <li>Surname : <span id="idSurname">Vita</span></li> <li>Gender : <div id="idGender">Unisex</div></li> <li>Additional Info : <div id="idExtraInfo">An amateur software developers' group.</div> </li> </ul> </div> </body>
Now to make these div elements editable all you have to do is adding our library sources to your page. You don't have to edit even one bit of your website. For now you should include all these files(soon there will be an all-in-one-package). You should add them to the head section in the given order.
<script src="../../js/dE.cssQuery.js" type="text/javascript"></script> <script src="../../js/aV.ext.string.js" type="text/javascript"></script> <script src="../../js/aV.main.events.js" type="text/javascript"></script> <script src="../../js/aV.main.ajax.js" type="text/javascript"></script> <script src="../../js/aV.main.aParser.js" type="text/javascript"></script> <script src="../../js/aV.main.visual.js" type="text/javascript"></script> <script src="../../js/aV.plg.quickEdit.js" type="text/javascript"></script>
Now we should tell our library which elements will be editable and what will happen when they are edited. We will do this by writing some rules to a text file. Default rule file location is editableRules.txt in the same folder but this can be changed from QuickEdit.config.ruleFile variable. So let's examine our rule file and explain what can be written in this rule file.
#idInfo>li>div, #idInfo>li>span
{
action: 'change.php',
params: 'var=' + element.id + '&val',
condition: 1
}
#idGender
{
type: 'select',
selectValues: ['Unisex', 'Male', 'Female']
}
#idExtraInfo
{
type: 'textarea'
}
#idPicture
{
action: 'change.php',
params: 'var=' + element.id + '&val',
fade: 0.5,
condition: 1
}If you know a little CSS I think you have already understood what these rules mean. Let me explain briefly though.
The first line tells quickEdit to find an element whose id is idInfo and select all the divs under that element's lis. Then, tells QuickEdit to assign the attributes action, params, condition with the written values. Actuall aV.aParser module does all these so if you want to learn more you can have a look at it's tutorial.
Now let's talk about what attributes quickEdit needs or understands.
quickEdit Attributes
- condition
This parameter is used when the editablity of the element depends on some variables. In this case I wanted it to be always editable but it could have been as follows condition : 'isAdmin' where isAdmin is a globally defined JavaScript variable name. This may be used to make the element editable only for users who has administrative privileges. I used isAdmin also in quotes, as a string, because the statement in condition property is evaluated realtime everytime a user hovers over an editable element. For more information about using JavaScript expressions in rule definitons, please have a look at aVaParser.
Note: Do not forget that this condition is checked only client-side, you should always check user rights or, in short, editability rights from your server-side script.
- change
The parameter change is the server-side script file's adress that will be called when the editing is performed just as a form's action property. There will be an AJAX request working behind to actually change the value. This lets you to control and apply the change on the server side. The server-side script file may be used to store the new value in a database or XML file on the server. The parameters to this file can be given by the third parameter. If this script doesn't turn 1 as a result then quickEdit will understand that editing on the server side was not successful so won't change the value with the new one.
- params
The parameter params keeps the parameters that will be given to the server-side script file which is defined in editaction property. In this example we used an expression as follows 'var=' + element.id + '&val'. So in this case two parameters will be sent to the php file. Writing only the parameter name at the end of the parameters means that the new value of the edited text will be assigned to that parameter name. In this case the parameter val will hold the value which the user enters as the new value and the value of var is the id of the edited element. You may use Javascript in here, element would be the spesific element which is being edited. (ie. element.offsetHeight, element.getAttribute("myAttribute"), etc.)
QuickEdit has two more parameters that I believe you will like :
- type
Setting this parameter to 'textarea' will make a multiline edit which means that your box will expand in y direction. Or in technical terms, there will be a textarea element instead of a INPUT TYPE="text" element when user clicks to change the text. Setting to 'select' will create a combobox(select element, dropdown menu) whose elements will be taken from the selectValues parameter.
- selectValues
As you can see in our example you can directly write a Javascript array. Or you can write a expression string which will be evaluated when the user starts editing. This expression must result in an array.
- fade
Giving this parameter will make the element fade to the given value when it is on hover. Giving 0.5 to this parameter will make the element 50% transparent when the mouse is over the element. This is a nice effect use if you like :)
A note about styles
When the editable element is hovered its class will change to editable. By writing a css for this class you can change the view of the editable object as much as you like. Add this to the end of the style.css file and see the change if you like.
Please also have a look at the quickEdit Live Demo 2 and give feedback us both about the demo and the tutorial.
This document is continuously being improved by the developers.
Sign in to add a comment
Nice script.