Adding, Editing or Removing Form fields
To add/remove a field from a form on a page, you will need to edit the file:
/smartway/conf/PAGE_NAME.xml where PAGE_NAME is the name of the page that contains the form. Please note that sometimes there are multiple xml files associated with a single form and all of them need to be editted in order to have the change fully in effect. For example the search form on the index page is represented by 6 files: index.xml, index_both.xml, index_city.xml, index_city_no_state.xml, index_no_state_no_city.xml, index_state_no_city.xml. As you can see all filed that are related to the form on the index page start with "index" prefix so it is easy to tell which files need to be editted.
In the case of "index" page multiple xml files are present to handle location change. Each files is a snapshot of the form. There is an xml file for "..., country, state, city, ...", for "..., country, ...", and so on. This means that almost always the form that has country/state/city fields will be powered by multiple files. However this is only an example and there are other things that can cause this, for example registration forms have multiple files because of captcha feature.
General structure of an XML file
Each XML file used by webJobs can be split into three parts. Let's check index.xml for example
<?xml version="1.0" ?> <!-- This file dictates the edit resume form syntax for job seekers. --> <!-- Do not add/delete fields by hand! --> <formdata name="quicksearch" method="get" class="qs_index"> <default name="required">1</default> <default name="type">text</default> <default name="blank"></default> <default name="class">qs_index</default> <default name="break">yes</default> <needselect from_table="jb_select_boxes">job_types</needselect> <needtable fields="id,name" where="country='{{country}}'" orderby="relative_order">jb_states</needtable> <needtable fields="id,name" orderby="relative_order">jb_countries</needtable> <needtable fields="name" where="state='{{state}}'" orderby="relative_order">jb_states_cities</needtable> <input name="keywords" required="1" class="qs_index">keywords</input> <input name="industry" type="select" required="1" group="job_types" class="qs_index" store="value" blankline="all_categories">job_category</input> <input name="country" type="select" table="jb_countries" key="name" value="name" required="1" otherattr="onChange="javascript:document.quicksearch.action.value='load_states';document.quicksearch.state.value='';document.quicksearch.page.value='index';submit_ajax_form(document.quicksearch);"" blankline="all_countries">country</input> <input name="state" type="select" table="jb_states" store="value" key="id" value="name" required="0" otherattr="onChange="javascript:document.quicksearch.action.value='load_cities';document.quicksearch.city.value='';document.quicksearch.page.value='index';submit_ajax_form(document.quicksearch);"" blankline="all_states">state</input> <input name="city" type="select" table="jb_states_cities" key="name" value="name" required="0" blankline="all_cities">city</input> <submit action="quick_search" class="button_submit">search</submit> </formdata>
The first part is
<?xml version="1.0" ?> <?xml version="1.0" ?> <!-- This file dictates the edit resume form syntax for job seekers. --> <!-- Do not add/delete fields by hand! --> <formdata name="quicksearch" method="get" class="qs_index"> ... </formdata>
It's the least interesting part. Basically it's only purpose is to state that this XML is going to describe a form. There are also a couple of minor things you can configure here, like form ID, etc..
The second part is
<default name="required">1</default> <default name="type">text</default> <default name="blank"></default> <default name="class">qs_index</default> <default name="break">yes</default> <needselect from_table="jb_select_boxes">job_types</needselect> <needtable fields="id,name" where="country='{{country}}'" orderby="relative_order">jb_states</needtable> <needtable fields="id,name" orderby="relative_order">jb_countries</needtable> <needtable fields="name" where="state='{{state}}'" orderby="relative_order">jb_states_cities</needtable>
Here you can set different form defaults, select which data should be loaded from DB (for later use in dropdowns), and so on.
And finally the third part is
<?xml version="1.0" ?> <input name="keywords" required="1" class="qs_index">keywords</input> <input name="industry" type="select" required="1" group="job_types" class="qs_index" store="value" blankline="all_categories">job_category</input> <input name="country" type="select" table="jb_countries" key="name" value="name" required="1" otherattr="onChange="javascript:document.quicksearch.action.value='load_states';document.quicksearch.state.value='';document.quicksearch.page.value='index';submit_ajax_form(document.quicksearch);"" blankline="all_countries">country</input> <input name="state" type="select" table="jb_states" store="value" key="id" value="name" required="0" otherattr="onChange="javascript:document.quicksearch.action.value='load_cities';document.quicksearch.city.value='';document.quicksearch.page.value='index';submit_ajax_form(document.quicksearch);"" blankline="all_states">state</input> <input name="city" type="select" table="jb_states_cities" key="name" value="name" required="0" blankline="all_cities">city</input> <submit action="quick_search" class="button_submit">search</submit>
These are the actual fields. Each xml element represents a form element.
What can be done with the first part (setting form id, class, etc.)
Basically in the first part of the XML file everything you can do is change or add parameterss to this element
<formdata name="quicksearch" method="get" class="qs_index" usefile="1">
- name="quicksearch" - this will be used for "name" and "id" parameter in HTML <form> tag
- method="get" - this parameter can be either "get" or "post" and it defines the method that the form will use to submit data
- class="qs_index" - the css class of the form, you can later use to to css the form
- usefile="1" - indicates that the form will have a file-upload fiels. If present, the enctype='multipart/form-data' parameter will get added to the html form when it is rendered.
What can be done with the second part (form configs, defaults, loading data from DB, etc)
<default name="required">1</default> <default name="type">text</default> <default name="blank"></default> <default name="class">qs_index</default> <default name="break">yes</default> <needselect from_table="jb_select_boxes">job_types, majors, experience_levels, education_types</needselect> <needtable fields="id,name" where="country='{{country}}'" orderby="relative_order">jb_states</needtable> <needtable fields="id,name" orderby="relative_order">jb_countries</needtable> <needtable fields="name" where="state='{{state}}'" orderby="relative_order">jb_states_cities</needtable>
The first element we'll look at is
<default name="required">1</default>
You can use it to default any param to a certain value. These parameters are then used in the third part of the form, where we define actual fields, and will be explained in details later. The <default> element is just a small tool to make code smaller and easier. For example if you need to create 100 different fields and make them all mandatory, you don't need to write required="1" for each and every of them, instead you can make this param always default to "1" and then omit it during actual field declaration. In the example above "require" is the name of the param and "1" is its default value. You can default absoutely any param to any value in the same way.
<needselect from_table="jb_select_boxes">job_types, majors, experience_levels, education_types</needselect>
This element instructs framework to pre-load some data from DB. This data can be later used to fuel dropdowns. The only thing that can be changed here is the types of data that gets selected (job_types, majors, experience_levels, education_types). The types are taken from this field jb_select_boxes.group_name and you can add any new ones there. For example if you want to add a "how did you find about us" dropdown with values "google, yahoo, other", you would need to go to DB and create three new rows (group_name, name, relative_order): ("how_found", "google", "1"), ("how_found", "yahoo", "2"), ("how_found", "other", "3"). Relative order is the order in which the values will appear in the dropdown, group_name is an unique text ID of this drop-down (it can be anything you want) and name is the actual text that will appear in the dropdown. After adding these 3 rows in the DB, you can add this line (or if needselect si alrady there, just add how_found to the list)
<needselect from_table="jb_select_boxes">how_found</needselect>
which will cause the framework to pre-load the data from DB. This doesn't create the dropdown yet, the line only causes the data to be pre-loaded. However after that you can create the actual dropdown and make it hook up this data. This will be demonstrated later.
<needtable fields="id,name" where="country='{{country}}'" orderby="relative_order">jb_states</needtable> <needtable fields="id,name" orderby="relative_order">jb_countries</needtable> <needtable fields="name" where="state='{{state}}'" orderby="relative_order">jb_states_cities</needtable>
Needtable is used to make more complex dropdowns where a simple list of values is not enough. For most of the mods needselect will be enough, however sometimes more complex dropdown are reuqired. The element value (in the example above: jb_states, jb_countries, jb_states_cities) defines the name of the table that will be queried. Other supported parameters are "where", "groupby", "orderby", "limit" and "fields". Each of them corresponds to the specific part of an SQL query which you can construct bit by bit in this element. If you need to do JOINs, you can place them like this
<needtable fields="b.id, b.name, b.quantity" where="b.type='job_postings' AND (b.quantity=1 OR(bh.pending=0 AND bh.available>=0 AND bh.user_id='{{user_id}}'))" orderby="quantity asc" groupby="name">jb_billing AS b LEFT JOIN jb_billing_history AS bh ON b.name = bh.name</needtable>
Also as you can see, you can use dynamic variables here (user_id, country, etc). These are taken from $application->_input array.
What can be done with the third part of an XML file (creating actual form fields)
<todo: specs of all possible field elements and params>
What's next?
After you've successfully added a field to the form, you've only added it to the HTML form: it will get submitted to the server but the server doesn't nkow what to do with it. Depending on what you are going to do with the field, you might need to do MySQL and PHP changes in order to achieve the required functionality.
Let's go through this on an example: we need to add two new fields to the employer registration form. One field will be a simple non-mandatory text field called "Alternative Phone". The other field is going to be a mandatory "how did you find about us" dropdown which will go after "Other Titles" field.
First let's add the text field, it's the easiest part.
... <input name="phone" validate="/^[-+0-9\.() ]*$/"><![CDATA[phone_number]]></input> <input name="alt_phone" required="0"><![CDATA[alt_phone_text]]></input> <input name="fax" validate="/^[-+0-9\.() ]*$/" required="0"><![CDATA[fax_number]]></input> ...
name="alt_phone" is the name of the field, it defined the name of the input variable submitted to the server. alt_phone_text is the text that will appear near the field, later we'll add a translation entry for that. required="0" means that the field is optional.
Now let's add a dropdown. As described above this a two-step process:
1. add and pre-load data
2. craete a dropdown that uses this data
Let's add the data first. Since it's a simple dropdown, we'll use needselect. Let's call the new group - "how_found". Please open phpmyadmin and add some values to jb_select_boxes table with group_name="how_found". For test pourposes I'll be using this data however you can add absolutely anything
INSERT INTO `jb_select_boxes` (`id`, `group_name`, `name`, `relative_order`) VALUES (NULL, 'how_found', 'Google', '1'), (NULL, 'how_found', 'Yahoo', '2'), (NULL, 'how_found', 'Facebook', '3'), (NULL, 'how_found', 'Other', '4');
After adding the data we need to instruct form to pre-load it by adding our new group_name called "how_found" to the needselect element.
<needselect from_table="jb_select_boxes"><![CDATA[titles, suffixes, company types, how_found]]></needselect>
The data part is now fully ready, now all we need to do is to define add the dropdown element.
... <input name="suffix_titles" required="0"><![CDATA[other_titles]]></input> <input name="how_found" type="select" required="1" group="how_found" store="value" blankline="select_found_source"><![CDATA[how_found_text]]></input> <fieldset legend="privacy_settings" class="register_employer2_privacy_div"> ...
The important parameters here are:
- group="how_found" - this is the group_name field we created and inserted into DB above
- blankline="select_found_source" - the text that will be displayed for the default blank element, you can leave it empty blankline="" or omit this parameter at all.
- how_found_text - text that will appear near the dropdown
If you save all these changes and refresh the page, the fields should be there. As you can see, the actual texts don't appear, instead the form uses text codes, like how_found_text. Let's fix that and add actual texts. The translations for the text codes are stored in smartway/conf/lang/.../ folders. There might be more than one folder depending on the number of languages at your site. I'll be updating english files only, they are located in smartway/conf/lang/eng/. However if you need to have other translations as well, just re-apply the changes to other language directories.
The names of the lang files used depend on the name of the page. For register_employer page the files are
/conf/lang/eng/text.register_employer.php
/conf/lang/eng/text.register_employer_both.php
/conf/lang/eng/text.register_employer_city.php
If you are not sure which file to use, you can use /conf/lang/eng/text.common.php which is a global lang file that gets always loaded. However if you use this file, make sure the names of your text codes don't have generic names that might be used elsewhere at the site (e.g. title - bad name likely to be used elsewhere; my_new_title_var - good name, unlikely to be used anywhere).
The files have pretty simple format so let's add the translations:
... 'backfilling_disabled' => 'Disable backfilling:', 'select_found_source' => 'Select...', 'how_found_text' => 'How Did You Find Us?', 'alt_phone_text' => 'Alternative Phone:', ...
The form is fully ready now and it's time to start with PHP and MySQL changes. MySQL changes are realtively simple: we'll just add several new fields to jb_users table. These fields will hold the data user enters during registration. You can add the fields via phpmyadmin interface, the resulting query will be
ALTER TABLE `jb_users` ADD `how_found` VARCHAR( 255 ) NOT NULL , ADD `alt_phone` VARCHAR( 255 ) NOT NULL;
To avoid confusion the MySQL field names are usually given the same name as the form HTML fields.
Now we need to modify PHP files. Here we'll instruct server to save the values from the new html elements into the new MySQL fields.
The PHP file has the same name as the page name, in our case it's engine/pages/register_employer.php. If you look through it, you'll find a big insert query that adds that submitted data to the DB. It's syntax is quite simple and we just need to add the names of our new fields there
$sql->insert('jb_users', array(array(
'alt_phone' => $sql->escape_string($input['alt_phone']),
'how_found' => $sql->escape_string($input['how_found']),
'login' => $sql->escape_string($input['login']),
'password' => $sql->escape_string($input['password']),
'status' => $sql->escape_string('employer'),
'salutation' => $sql->escape_string($input['title']),
'first_name' => $sql->escape_string($input['first_name']),
'middle_initial' => $sql->escape_string($input['middle_initial']),
'last_name' => $sql->escape_string($input['last_name']),
'suffix' => $sql->escape_string($input['suffix']),
'suffix_titles' => $sql->escape_string($input['suffix_titles']),
'company_name' => $sql->escape_string($input['company_name']),
'completed' => 1,
'signup_time' => time(),
'timezone' => $sql->escape_string($application->config('time_adjustment')),
'language' => ($t_lang?$sql->escape_string($t_lang):$sql->escape_string($application->config('default_lang'))))),
array('alt_phone', 'how_found', 'login', 'password', 'status', 'salutation', 'first_name','middle_initial', 'last_name',
'suffix', 'suffix_titles', 'company_name', 'completed', 'signup_time', 'timezone', 'language'));
This is everything we need. If you register a new user and look at jb_users table via phpmyadmin, you'll notice that the data gets successfully saved to the new fields.