easyObject - User Manual - EN
Contents
1. Returns the list of the objects identifiers matching a given domain sorted on a given field possibly limited to a specific section update method mixed update string object_class array ids array values lang DEFAULT_LANG This method serves for creating new objects as well as for modifying them When an item of the ids list is set to zero a new object is created and its identifier placed in the array returned by the method For examples see BSUR Browse Search Update Remove remove method mixed remove string object_class array gids boolean permanent false This method allows to remove one or more objects If the parameter permanent is left to FALSE the field delete of the object is set to TRUE and the object does not appear in the lists but the object may be retrieved and the removal canceled If the parameter permanent is set to TRUE then is object is removed from the database and can no longer be retrieve unless the database has been backed up documentation easyObject v 1 0 December 2012 JOSO 17 20 BY NC SA get method mixed amp get string object_class integer object_id Itis also possible to get the instance of an object To retrieve or change the value of the fields declared in the getColumns method it is then possible to use getters and setters using standard OO syntax implemented with the PHP magic method __ call Example SUser am2. string Used for fields holding a short string with no formatting nor carriage returns ex lastname place short_text Used for fields holding a string of characters that may contain carriage returns but no formatting ex a short description an address text Used for fields holding a text that might be long and include formatting notes with SQL the types TEXT BLOB or MEDIUMTEXT MEDIUMBLOB are recommended binary Used for fields holding any binary value ex a picture a document notes with SQL the MEDIUMBLOB type is recommended selection Used for fields holding a value selected from a pre defined list Example from the corel Log class action gt array type gt selection selection gt array R_CREATE gt R_CREATE R READ gt R_READ R WRITE gt R_WRITE R DELETE gt R_DELETE R_ MANAGE gt R_MANAGE Note the part at the left side of the arrow is the one that will be outputted in the selection box the right part is the one stored in DB date Used for fields holding a date with the following format YYYY mm dd time Used for fields holding a time with the following format HH mm ss documentation easyObject v 1 0 December 2012 JOSO 8 20 BY NC SA datetime Used for fields holding a date with the following format YYYY mm dd HH mm ss timestamp Equivalent to datetime but measured in number of seconds since
3. if S rights amp R_DELETE Srights_txt delete if Srights amp R_MANAGE Srights_txt manage return implode rights_txt public static function onchange_Rights Som Suid Soid Slang Som gt update Suid core Permission array Soid array rights_txt gt Permission callable_getRightsTxt Som Suid oid lang Slang getDefaults method The returned values are either the result of a closure or a static method from the current class or any other class Example from the school Student class Extrait de la m thode getColumns birthdate gt array type gt date subscription gt array type gt date M thodes additionnelles public static function getDefaults return array subscription gt school Student default_subscription birthdate gt function return 2000 01 01 di public static function default_subscription return date Y m d documentation easyObject v 1 0 December 2012 JOSO 11 20 BY NC SA getTable method Itis also possible to rewrite the getTable method This can be useful when the name by default is not a good choice or if for any reason it does not fit the developer needs Example school _ Class public function getTable return school_class Inheritance It is possible to rewrite a class in some situations the overwriting is even mandatory To set
4. lt form action core_objects_update gt lt section name identification gt lt fieldset title identification gt lt span width 50 gt lt label for firstname gt lt label gt lt var id firstname required true gt lt var gt lt br gt lt label for lastname gt lt label gt lt var id lastname required true gt lt var gt lt span gt lt span width 50 gt lt label for birthdate gt lt label gt lt var id birthdate required true gt lt var gt lt br gt lt label for subscription gt lt label gt lt var id subscription required false gt lt var gt lt span gt lt fieldset gt lt section gt lt section name data gt lt fieldset title data gt lt span width 100 gt lt label name classes_ids gt lt label gt lt br gt lt var id classes_ids view list default gt lt var gt lt span gt lt fieldset gt lt section gt lt form gt documentation easyObject v 1 0 December 2012 JOSHO BY NC SA 19 20 Example of a list for the school Student class Student list default html lt ul gt lt li id id width 10 gt lt 1li gt lt li id firstname width 23 gt lt li gt lt li id lastname width 23 gt lt 1li gt lt li id birthdate width 22 gt lt 1li gt lt li id subscription width 22 gt lt 1li gt lt ul gt Basic applications Some applications show queries are included in the core
5. error is raised in charge of url rewriting folders actions Folder containing scripts that do some operations on objects and that might return JSON data do apps Folder containing applications scripts that output HTML pages 2showe data Folder containing scripts that give information about objects by returning JSON answers get library Folder containing every file that might be included by PHP scripts files and classes classes dossier contenant les classes php objects Folder containing objects definitions files class php so that the edition templates views and translation i18n files orm Applicative core contains classes object class php objectManager class php IdentificationManager class php 118n class php and ErrorHandler class php db Dossier contenant les classes associ es a l interface avec la base de donn es DBConnection class php factory pattern DBManipulator cass php et classes h rit es adaptation des m thodes avec les commandes propres au DBMS utilis utils Classes utilitaires utilis es par le coeur applicatif files contains config inc php Zend If required this is where the Zend framework must be placed Note it s not required by easyObject html js The javascript libraries used by applications scripts apps css html stylesheets required by application scripts apps Object definition The structure of every object class is defined in a class php placed into library classes
6. the Unix Epoch 1 January 1970 00 00 00 GMT many2one Used for fields holding a N 1 relation that is to say a numeric value that represents the identifier of the pointed object Attribute Description foreign_object the class toward which is pointing the current field Example from the school Course class school_id gt array type gt many2one foreign_object gt school School one2many Used for a field holding a 1 N relation Attribute Description foreign_object the class toward which is pointing the current field foreign_field the name of the field of the pointed class that is pointing back toward the current class foreign_key the field that serves as identifier for objects pointed by the relation by default id field Example from the school Teacher class classes_ids gt array type gt one2many foreign_object gt school _Class foreign_field gt teacher_id many2many Used for a field holding a M N relation Attribute Description foreign_object the class toward which is pointing the current field foreign_field the name of the field of the pointed class that is pointing back toward the current class rel_table the name of the SQL table dedicated to the m2m relation recommended syntax package_rel_class1_class2 rel_local_key name of the column in rel_table holding the identifier of the current object rel_foreign_k
7. to ease management and development of new packages core_manage management of existing objects list creation edition removal by package URL example http localhost easyobject show core_manage core_utils see Utility and stand alone scripts URL example http localhost easyobject show core_utils core_setup to validate a fresh install of easyObject Utility and stand alone scripts Utility scripts allow to achieve some tasks that are not handled by the core for instance checking the consistency of a new package They act like some sort of plugins written in PHP and located in the folder data utils Some scripts are planned in progress or already available Available beta core validation package validation consistency checks between DB and class as well as syntax validation for classes PHP views HTML and translation files json Planned Create a compatible database based on a SQL schema Generate a PHP class from an existing table Generate files for default views list default html and form default html Data import export To consult the list of the plugins and apply them to one or more package you may use the core_utils application URL example http localhost easyobject index php show core_utils Note Of course those scripts may be written by the user developer or adapted to any particular purposes documentation easyObject v 1 0 December 2012 JOSO 20 20 BY NC SA
8. up an inheritance mechanism the class must not extend the core Object class but the class from which it inherits the getTable method must be used to define the name of the related table in database by default the name of the related table will be the one of the parent class the getColumns class must return an associative array holding every field of the new class in order not to rewrite the fields that are common with the parent class one may use the PHP function array_merge with parent getColumns as first parameter Example knine User namespace knine class User extends core User public function getTable return core_user public static function getColumns return array_merge parent getColumns array articles_ids gt array type gt many2many foreign_object gt kninelArticle foreign_field gt authors_ids rel_table gt knine_ rel article _user rel_foreign_key gt article_id rel_local_key gt user_id Permissions management system The Permission class is dedicated to the rights management for each object class including the Permission class itself rights can be defined for one or more user groups Involved classes are documentation easyObject v 1 0 December 2012 JOSO 12 20 BY NC SA core User library classes objects core User class php public static function getColumns return array
9. bject Sids update corelUser array 0 update an object update corelUser Sids array firstname gt John lastname gt Doe password gt secret 1 create and update 3 objects at once Sids update corelUser array 0 0 0 array firstname gt John lastname gt Doe password gt secret 1 update several objects update corelUser Sids array password gt md5 test search for one or more objects ids search core User array array lastname like Soe array id in range 1 100 browse one or more objects obtain firstnames of users whose id is in the list Svalues amp browse core User Sids array firstname For a complete list of methods and their signatures see description of the main methods documentation easyObject v 1 0 December 2012 JOSO 3 20 BY NC SA Tree structure description Location Description Root Directory where the easyObject application is located ex home easyobject www files htaccess Apache configuration file used to prevent directory listing and handle 404 errors fc lib php Classes and files inclusion library index php This script is also referred to as the dispatcher its task is to include required libraries and to set the context This is the unique entry point rpc_server php Server script for client server mode url_resolver php Script invoked when a 404
10. ccessible via HTTP request library classes objects package_name 118n lang object_name json On the other hand to obtain the file via script you have to invoke get core_ 18n_lang Location data core i18n lang php URL example http localhost easyobject get core_i18n_lang amp class school Student amp lang fr Translation of objects fields values All basic fields can be translaterd see Fields types To allow this a table in DB is dedicated to the translation terms When a field is marked as multilang the values of its translations can be retrieved with a SQL query Translation object fields string lang code ISO 639 1 string object_class string object_field integer object_id mediumblob value For the value field the SQL MEDIUMBLOB type is used overhead of 3 bytes max size of 16 7 Mo Indeed the size of the value column may vary greatly from one type to another the binary type may represent a document a picture a video And most of the time fields that must be translated are documentation easyObject v 1 0 December 2012 JOSO 14 20 BY NC SA texts string short_text ou text In any case a 3 characters overhead is acceptable and set a 16 Mo limit should not be a problem Note as the only condition for the SQL type is to be compatible with the associated easyObject type one must pay attention in order for a binary field to be translated for instance a PDF doc available in differe
11. e assigned are defined in the file config inc php define R_CREATE 1 define R_READ 2 define R_WRITE 4 define R_DELETE 8 define R_MANAGE 16 Q020 documentation easyObject v 1 0 December 2012 autorisation to manage the rights 13 20 The field rights of the Permission class is a binary mask logical OR of the rights given to the related group If for some class no permission is defined for none of the groups to which belongs a user this one receives the default permissions defined in the configuration file DEFAULT_RIGHTS constant Translation mechanism Two distinct mechanisms are used depending on what we are handling 1 translation of the terms related to a class 2 translation of object fields values instance Translation of the terms related to a class Each package has a folder named i18n containing for each language a subfolder which name matches the ISO 639 code of the language ex fr_BE ou zh_CN Inside those folders for each class is a json file which prefix is identical to the class it refers to ex Student json Those translation files are in UTF 8 and in JSON format and contain the translation terms of all items that might be translated attributes label et help This system is not the lighter in terms of overhead but offers the advantage of being usable as is by the Ul no processing server side Indeed the translation file is directly a
12. easyObject modern web applications made easy User Manual version 1 0 December 2012 by Cedric Francoys http www cedricfrancoys be easyobject This document is released under the Attribution NonCommercial ShareAlike 3 0 Unported Contract available online at http creativecommons org licenses by nc sa 3 0 or by mail writing to Creative Commons 171 Second Street Suite 300 San Francisco California 94105 USA Table of contents Ts H wisitworkihg ecteiii pecs csnekesccadautadssenesin nc dwnaacteeedaduaisenuedcceshdiayekeihdwenhendecdle seule aelaandeccuases EE ER 3 BSUR Browse Search Update REMOVE ccccecccccecasssseseseeeeeeeececeesaeaeususeseseeeeseesauseneaeeseseeeeeeeaeaes 3 Tree structure descriptio sssaaa a E E aE aa a a holed RESE E 4 Object definition dida 4 Consistency between a class php definition and database schema occccconcccncnnnnannnnnnnnnnnn cnn nnnnonos 5 Fields type See ROA Po o a o E 5 SEM A A i 6 COMON MEt cuisine ia 6 getColumns method ccoccocnnnninucunuouoononononononnnononnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn non ron n nro nnnnn nro nnnnnnnnnnnnnnnnnnnninnnannns 6 getDefa lts MEA ni A a 11 PEt Table method dei 12 PA ORGAN CO cata lin aii 12 Permissions management SysteM ooocccccnnoccnncnnnanennnnnnanononononnncnnnnnnnnnnnnnnncnnrnnnnnnnnnnnnnnnnnnnnnncnnnnnineninos 12 Translation mechani eona a a 14 Translation of the terms related to a ClaSS oooonoccccnnnncncnnncnnnn
13. entification succeeds the method returns TRUE and the current session is then bound to the id of the related User object validate method mixed validate string object_class array values Checks whether the values of given object fields are valid or not The returned value is either FALSE or an array associating for each invalid field the field name and the associated error message id documentation easyObject v 1 0 December 2012 0SO 16 20 BY NC SA browse method mixed amp browse string object_class ids null fields null lang DEFAULT_LANG On success this method returns for the specified class an array associating the list of the values of each given field for each given object id If an error occurs an integer holding one or more error codes is returned Note This method may generate a SQL query for each of the specified ids for objects that have not yet been loaded into the manager A good practice then consists of not calling the method for each field separately but by grouping all required fields in the Sfields array Example Svalues amp browse core User array 3 array login firstname lastname echo values 3 login Svalues 3 firstname Svalues 3 lastname search method mixed search string object_class array domain null string order string sort asc integer start 0 limit lang DEFAULT_LANG
14. ey name of the column in de rel_table holding the identifier of the pointed object documentation easyObject v 1 0 December 2012 JOSO 9 20 BY NC SA Example from the school Teacher class courses_ids gt array type gt many2many foreign_object gt school Course foreign_field gt teachers_ids rel_table gt school_rel _ course _teacher rel_foreign_key gt course_id rel_local_key gt teacher_id Ve related This kind of field allows to specify an indirect relation of type many2one or one2many The principle is to indicate the field of another object accessible by successive relations Attribute Description result_type the type resulting from the indirect relation i e type of the final pointed field foreign_object name of the final pointed field path array holding the names of the cascade fields to consult in order to get to the final field note the first field must belong to the current class Example of the school_id field from the school Lesson class sechool_id gt array type gt related result_type gt many2one foreign_object gt school School path gt array class_id course_id school_id function A functional field or calculated field allows to provide a class with fields which value depend on one or more other fields from the current object or any other object Notes the use o
15. f the store attribute require most of the time that the fields on which depends the value of the functional field have an onchange event triggering the update of the calculated field see example Attribute Description result_type type of the value resulting from the invoked function store boolean telling if the function result must be stored in database in that case the related table must contain a column for the field function string holding the name of the method to invoke with format package Class method note this method will be called with PHP function call_user_func documentation easyObject v 1 0 December 2012 JOSO 10 20 BY NC SA Example of the field rights_txt from the core Permission class Extrait de la m thode getColumns rights gt array type gt integer onchange gt corelPermission onchange_Rights rights_txt gt array type gt function store gt true result_type gt string function gt core Permission callable_getRightsTxt M thodes additionnelles public static function callable_getRightsTxt Som Suid Soid lang Srights_txt array res Som gt browse Suid corelPermission array oid array rights lang Srights res oid rights if Srights amp R_CREATE Srights_txt create if Srights amp R_READ Srights_txt read if Srights amp R_WRITE Srights_txt write
16. firstname gt array type gt string lastname gt array type gt string login gt array type gt string label gt Username password gt array type gt string label gt Password language gt array type gt string groups_ids gt array type gt many2many foreign_object gt core Group foreign_field gt users_ids rel_table gt core_rel_group_user rel_foreign_key gt group_id rel_local_key gt user_id core Group library classes objects core Group class php public static function getColumns return array name gt array type gt string users_ids gt array type gt many2many foreign_object gt core User foreign_field gt groups_ids rel_table gt core_rel_group_user rel_foreign_key gt user_id rel_local_key gt group_id permissions_ids gt array type gt one2many foreign_object gt corelPermission foreign_field gt group_id core Permission library classes objects core Permission class php public static function getColumns return array class_name gt array type gt string group_id gt array type gt many2one foreign_object gt core Group foreign_field gt permissions_ids E rights gt array type gt integer The possible rights that can b
17. foreign_object gt school _Class foreign_field gt course_id Common base Here is the list of the attributes common to all fields Attribute Description type the field type a valid easyObject type abel the label of the field that may appear in the edition forms default value name of the field help a tip to provide the final user about the role of the field or the way to fill it in multilang boolean telling if this field can be translated dafult value false note only basic fields can be translated that excludes relational and functional fields search boolean telling if the UI have to present this field as a search criteria default value false notes a search query is possible on complex fields that have the store attribute set see below search queries have better performances if related fields are indexed in database domain attribute for many2many and one2many fields allows to limit the list of related objects to those that match a specific criteria same format as the one used in the search method Q020 7 20 Available types boolean Used for fields holding a numeric value of Boolean type true or false notes we use the PHP built in constant true and false integer Used for fields holding a signed numeric value negative or positive notes with PHP it depends on the platform generally 32 bits signed with SQL it depends on the chosen type and size
18. function or two categories 1 Basic fields the value of those fields is stored directly in the SQL table related to the object and don t need to be processed boolean integer string short_text text date time datetime timestamp selection binary many2one 2 Complex fields those fields require more work to be retrieved one2many many2many related function documentation easyObject v 1 0 December 2012 JOSO 5 20 BY NC SA System fields Some fields are common to all objects Field Description id unique identifier of the instance created date and time of the object creation modified creator modifier published deleted date and time of the last modification of the object identifier of the user that created the object identifier of the user that made the last changes boolean telling if the object has been published boolean telling if the object has been deleted object in the trash bin Common methods Some methods defined in the core Object class are common to all objects Method __construct getSpecialFields getColumns getSchema gettable getld getModifiedFields getModifiedFields resetLoadedFields resetModifiedFields getUsedLangs getFieldsNames getValues setValues Description the constructor invoked when a new instance is created returns the names and types of the system fields described above returns the description of the user fields returns the full schema syste
19. m fields fields defined in getCo umns returns the name of the related SQL table return the identifier of the current object returns the list of loaded fields returns the list of fields that have been modified since the object has been loaded reset load flags reset modification flags returns the list of the languages for which at least one field is defined returns the names of the fields which type is mentioned in the specified list returns an associative arrau containing the names and values of the specified fields assign the specified values to the fields of the object getColumns method The definition of this method is mandatory for every object It returns the structure of the object list of fields and their attributes under the form of an associative array documentation easyObject v 1 0 December 2012 Q020 6 20 Example from the school Course class documentation easyObject v 1 0 December 2012 public static function getColumns return array label gt array type gt string school_id gt array type gt many2one foreign_object gt school School teachers_ids gt array type gt many2many foreign_object gt school Teacher foreign_field gt courses_ids rel_table gt school_rel course _teacher rel_foreign_key gt teacher_id rel_local_key gt course_id classes_ids gt array type gt one2many
20. nnaccnonancnnnnnncnnnno cnn ran n cnn nnnn cnn 14 Translation of objects fields Values ccccccnnnnonnoonononononononononnonnnnnnnnnonnnnnnnnnnnnnnnnnnnnnnnnnannnnanr cnn nnn anos 14 2 HONTON TO 16 Maim methot e iran a E E E ir O OOA 16 user WA ECHO sxe sasedesxetmennetcencsteygataaneqestesngnaed A rE En E nEn E EIERNE 16 user l ng method ireren a e E Ea E E E E E RRE 16 Tal A O 16 validate method iii a 16 BFOWSE Method citada e A even a ae 17 search Method eeaeee E acto eoatecossatarsgues E a E 17 update Method lt rara Ree 17 FEMOVE method aa da 17 POU METH Am Em o sitesuus seeesendauesstacenecgeuutlaagnanycuerseubadduaaes EE EEEE ERRAN 18 getStatic Method cccccccccnnnnnonnnnnnanonannnnnnono E E E E E a EE E e nnnnennnnnnnnanenos 18 Objects Clica a 18 Basic application turis aii 20 Utility and stand alone Scripts ssenarisi cranca ree E K E a a ara EEEn ERER ERENS 20 documentation easyObject v 1 0 December 2012 0SO 2 20 BY NC SA 1 How is it working BSUR Browse Search Update Remove There are only four main methods to handle objects and they are the same for all objects classes browse to obtain the value of one or more fields from one or more objects search too look for identifiers of objects matching one or more criteria update to create an object or modify one or more fields of one or more objects remove to delete one or more objects Examples create a new o
21. nt languages that the value of this field never has a greater size to the one of the SQL MEDIUMBLOB type by example BLOB LONGBLOB documentation easyObject v 1 0 December 2012 0SO 15 20 BY NC SA 2 How to use it Main methods The following methods can be invoked as is at any time Note these methods are defined in PHP easyobject api php as well as in Javascript easyobject api js and their signatures are strictly identical in both languages If an error is raised most of these methods return an integer holding one or more error codes that can be isolated with a binary mask that are defined in the config inc php file Constant Value Description UNKNOWN_ERROR INVALID_PARAM SOL_ERROR UNKNOWN_OBJECT NOT_ALLOWED something went wrong that requires to check the logs one or more parameters have invalid or incompatible value error while building SQL query or processing it unknown class or object action violates some rule or user don t have required permissions UNEO user_id method integer user_id Returns the identifier of the current user based on the current PHP session id user_lang method string user_lang Returns the language ISO 639 format of the current user based on the current PHP session id login method boolean login string ogin string password This method tries to validate the identification of a user If the id
22. objects package documentation easyObject v 1 0 December 2012 JOHO 4 20 BY NC SA Every class inherits from a common ancestor the Object class declared in the core namespace and defined in library classes orm Object class php A class is always referred to with the package name to which it belongs The syntax is package_name class_name ex school Teacher A class consists of several fields each of them having a name and a type and a list of methods Some methods are system their name is standard and used by the ORM and others are specific to a class and defined by the user see below Consistency between a class php definition and database schema In parallel a table must be defined in the database that has a structure matching the related class definition The main constraint being that the types must be compatibles ex a varchar 255 column in the database may represent a string as well as a short_text or a text in the related class Consistency between type definition and related table structure in DB must be permanently maintained This is left to the responsibility of the developer no process neither checks nor fixes potential errors seeUtility and stand alone scripts Fields types There are three kinds of fields 1 Direct types boolean integer string short_text text date time datetime timestamp selection binary 2 Relational types one2many many2many many2one related 3 Functional types
23. p get core User 3 Sfirst_name User gt getFirstname SUser gt setFirstname Lulu Notes This method implies the loading of all fields that may be numerous and which value may require a lot of processing to be obtained So it is recommended to use it only when the complete instance of the object is actually needed and not in order to retrieve only one specific field in which case it is preferable to use the browse method getStatic method mixed amp getStatic string object_class In some cases it s necessary to get an empty object for a specific class for instance while validating the schema of a class Objects edition To define the layout the list of the fields and the possible interactions between the fields of an edition form we use a system of views similar to templates Each package has a folder names views that contains for each class one or more HTML file These files are written in HTML5 and contain information about the fields and labels to display and their positioning for the edition of the related class Again this system is not the lightest in terms of overhead but has the advantage of being usable as is by the Javascript client no server side processing Their name format is object_name list form view_name html A series of HTML5 tags has been chosen in order to be used in views Those tags were chosen because of the usage that is generally done of them
24. reserved to inputs as this part is generated automatically having by default no visual impact documentation easyObject v 1 0 December 2012 JOSO 18 20 BY NC SA Tags and attributs for the views Tag Attribute Description form action the action to be executed when form is submitted button save section name used to group several items in sections accessible by selecting tabs fieldset title displays a frame that allows to group several items span width width of the span in of the parent width div width width of the du div in of the parent width label for the name of the field the label is related to if any name the identifier of the independent label if any var id name of the field onchange action to be executed in case the field is modified by the user written in javascript using Query syntax readonly boolean telling if the Ul must allow the modification of the field default value false note this mechanism is limited to the presentation layer and must not be used as right management required boolean telling if the field is mandatory default value false domain string containing the domain to which we want to limit the items to display applicable with m2m or 02m lists view the name of the view to be used if this attribute is not specified the related list default html file will be used Example of a form for the school Student class Student form default html
Download Pdf Manuals
Related Search