Skip to content

UI Documentation

Jump to bottom
meghasandesh edited this page Jun 22, 2017 · 1 revision

Javascript Libraries

https://api.jquery.com/ https://api.jqueryui.com/ http://foundation.zurb.com/sites/docs/ http://getbootstrap.com/getting-started/ https://developers.google.com/maps/documentation/javascript/

Styling Libraries

http://sass-lang.com/ http://compass-style.org/help/

Metadata

Metadata files are used to specify how different forms should be constructed on the UI, as well as the display of datasets, sites and plots. Each JSON object in the metadata file describes a single field/property of the dataset/site/plot. The identifier for the JSON object corresponds to the name of the field.

Fields

Metadata Field Description type Datatype required Compulsory/optional attribute label Display name for the attribute read_only Allow the attribute to be edited by the user sequence Order in which the attribute will be displayed on the UI multiple Allow multiple entries for the attribute list_name Name of the list to fetch using AJAX choices Possible choices for attribute of type choice

Datatypes

string - creates a textarea reference_list - creates a dropdown menu. The list_name property is used to get the options for the dropdown menu. field - creates a textbox date - creates a date input in HTML 5 supported browsers, which behaves as a textbox in older browsers. The date format can be specified using the format property choice - creates a radio button element with multiple options populated from choices property boolean - creates a yes/no selection element datetime - creates a datetime input

ngt-archive/ui: Most UI code lives here templates/ contains HTML template files (django + HTML) static/ contains styles and javascript

Coding Conventions

HTML

  1. Try to follow semantic HTML5 as much as possible.
  2. Use ‘data-’ attributes in tags for specifying parameters to be passed in and used by Javascript
  3. Avoid using id for styles and javascript as much as possible Use classes. Use ‘js-’ for elements which have javascript events attached to them. Never use a ‘js-’ class for styling (i.e., in the SCSS or CSS file)
  4. To locate the event listener attached to an element, find out its ‘js-’ classname and search for it in the javascript container. For locating its styling, find out the classname(s) and search in the SCSS/CSS container

CSS

app.js Workflow $(document).ready() The main wrapper function for the app. All events and initialized and executed here.

  1. Load metadata JSON for sites, plots and datasets (stored locally for now) (69-81)
  2. Get the ‘view’ parameter from the page URL. This will tell us which page needs to be loaded (91)
  3. Show the corresponding HTML container and hide others (93-97)
  4. Depending on the view, initialize and load contacts, datasets, sites, etc. (99-177)
  5. Initialize plots, variables and sites. These are preloaded so that when the corresponding pages are loaded, the page can be constructed (183-209)
  6. Wait for user action (the home view will be loaded by default)

CRUD Methods

Creating Drafts $('body').on('click', '.js-create-dataset', function(event)) Scans the Create Dataset form and invokes the creation of a new draft. No arguments expected 834-943

  1. Initialize submission object (this will be populated with all the properties specified for the draft)
  2. If the user has created a new author/contact, stop processing the form and deal with the author first. In order to create a new author first name, last name and email should be present - otherwise a message will be shown to the user asking them to input the values If all the required fields are present, create a new contact (862-912)
  3. Check to see if there are datasets with the same name/title. Confirm with the user before proceeding (925-939)
  4. process the dataset form (926)
  5. Invoke createDraft() method (935, 938)

processForm()

Processes the dataset form and checks for missing or invalid fields. Returns a javascript object containing the parameters of the dataset submit property set to true by default (1825-1884) check for null/empty values for required fields if the dataset is being submitted read all the properties specified for the dataset if there are any required properties which are missing, mark them if the dataset if being submitted mark the submit property as false (1876, 1884) deduplicate the submission object return submission object

createDraft()

Invokes the REST API to submit the dataset

create draft (1444) if the user is trying to submit the dataset if a file isn’t attached to the dataset show a message to the user (1438-1440) else upload the attached file if successful show confirmation message (1517-1521) else show fail message (1530-1538) if draft creation is successful show confirmation message (1517-1521) else show fail message (1530-1538)

Submitting Datasets $('body').on('click', '.js-submit-dataset', function(event))(736-832) Checks if the dataset being submitted already exists as a draft or is a new draft and takes further action if the user is trying to create a new dataset and there is a file attached upload file (in case of new dataset it will already have been created at this point) (747-823)

else if this is an existing dataset being edited and already has a file invoke processEditingForm() to complete the submission else show message to user asking to upload a file

processEditingForm(submissionObj, url) submissionObj: object containing the parameters of the dataset url: url for the dataset Processes the dataset parameters and submits the dataset check for new contacts/authors (2221-2229) if there are new contacts/authors and all required fields are present create new contact/authors (2243-2254) when done process dataset properties invoke submitDataset (2260) if submission successful show success message (2262) else show fail message (2267) if there was a problem creating author/contact show fail message to user (2282-2288) else if required fields are not present show message asking the user to input required fields (2322) else if there are no new contacts/authors process dataset properties invoke submitDataset (2260) if submission successful show success message (2262) else show fail message (2267)

completeEdit(submissionObj, url, submitMode) submissionObj: object containing the parameters of the dataset url: url for the dataset submitMode: boolean value indicating the dataset should be submitted after edit Calls the REST API to complete edit and then submit the dataset invoke editDataset() method (1730) if edit successful (1733 - 1793) if there is a file attached upload file if file upload successful show success message else show fail message else show success message else show fail message

Start editing a dataset from view screen $('body').on('click', '.js-edit-draft', function(event)) (464-568) get dataset URL and use it to find the dataset to populate editing form (467 - 479) populate editing form with dataset properties (480 - 506) initialize miscellaneous properties required for editing form (509-566)

Helper Functions

getParameterByName(name, url)

Used for extracting GET parameters from the URL, specially the current screen (view)

createDraft(submissionObj, submitMode) submissionObj - javascript object containing all the properties inputted by the user submitMode - boolean value indicating if the draft will go though submission after creation

createEditForm(templateType) creates two forms - one for creating datasets and the other for editing datasets for each parameter in template (1959 - 2062) initialize corresponding container type (textbox, dropdown etc.) and add display name to container add container to form clone the form initialize datepicker, modal and other supporting UI elements (2081-2110)

getCookie(name)

REST API Access Methods

For more detail please refer to REST API documentation

createDataset(submissionObj) submissionObj: object containing the parameters of the dataset Call to create a new draft Requires a clean javascript object containing the properties specified for the draft Returns new dataset information (including URL) upon success, error object upon failing

editDataset(submissionObj, url) submissionObj: object containing the parameters of the dataset url: url for the dataset

Call to specify edits to a dataset/draft Requires a clean javascript object containing the properties (existing, modified and new) specified for the dataset, plus the URL for the dataset Returns new dataset information upon success, error object upon failing

createContact(fname, lname, email, institute) fname: First Name lname: Last Name Email: email Institute is an optional parameter Call to create a new author/contact First name, Last name and Email are mandatory. Institute is optional (empty string will be specified by default) Returns new contact information upon success, error object

getDataSets(url) url: url for the dataset Call to retrieve all or one single dataset Returns all datasets if url is not specified, otherwise returns corresponding dataset Returns error object upon failure

getVariables()

Call to retrieve all variables Returns all variables if successful, error object upon failing

getSites()

Call to retrieve all sites Returns all sites if successful, error object upon failing

getContacts()

Call to retrieve all contacts Returns all sites if successful, error object upon failing

getPlots()

Call to retrieve all plots Returns all sites if successful, error object upon failing

getFileTypes()

Call to retrieve allowed file types (to be attached when submitting datasets) Returns list of all allowed file types if successful, false upon failing

submitDataset(url) url: url for the draft Call to submit a single dataset Requires the draft already exist and the url of the dataset to be specified Returns submitted dataset information if successful, error object upon failing

Jquery events

beforeunload

Activated when the user tries closing the tab/window. This event is used on pages which need to warn the user to double check before closing

Clone this wiki locally