Documenting your Xap

Spending a few minutes to state a clear name, purpose, image and tags about your new Xap makes it easy for you and others to discover and understand it later.

Include the following information for your Xap:
  • A descriptive name, which usually includes the name of the organization (if applicable) and project or main purpose for the Xap, e.g. "US Census City Clustering"
  • A link to a relevant image, often the logo for the organization or an abstract representation of what the Xap accomplishes
  • One or more searchable tags, usually the organization, purpose, key algorithms or visualizations used, etc, e.g. #census, #clustering, #reference, #uscities
  • A description of the Xap's intended audience, the problem it solves, and any important notes to share with users or other Xap builders. (See the article on markdown for how to style your description).

 Click on the name of the Xap, or "Untitled Xap", in the top-left corner of the Xap Builder to provide this information. Be sure to click Save when finished.



Organizing Components in your Xap


As you build larger Xaps in the dataflow, organizing your components in a logical, consistent manner will make it easier to maintain and enhance it in the future, and it allow others to quickly understand what is going on. While everyone can have a different style, the following guidelines tend to work well for most developers.

  • Layout components in the dataflow to follow the user interface: Keeping your components generally aligned with where they appear on the screen makes understanding and finding components much easier. For instance, lay out multiple controls like buttons or visualizations like trees, graphs, etc. in the order they appear in the user interface. If the save button appears to the left of the cancel button in the live Xap, also put the Save button component to the left of the Cancel button component.
  • Layout components to follow the data flow: Many applications have a common pattern of fetching data, performing some analysis, and visualizing results. Laying out the components in left-to-right fashion of data access, analysis, and visualization helps you and others quickly locate elements of interest.
  • Use whitespace to your advantage: You can zoom in and out within the dataflow, so use white space to logically separate groups of components.


Working with HTML and CSS


The Files tab in the Xap Builder allows you to control the HTML and CSS of your Xap as you would in any HTML5 application. Best practices for HTML and CSS apply here as well.

  • Do as much through components as possible. Limit custom HTML to styling and the occasional plain text field. Do not embed custom forms, Javacsript, etc. You lose the power and extensibilty of Exaptive's component framework when doing so.
  • The most common CSS changes involve styling the overall Xap and overriding default styling of UI components to match the branding of a particular organization.
  • Use a layout manager like Bootstrap to help manage laying out your page and ensuring it is mobile-ready with minimal coding. Exaptive has several components for layout managers.
  • Avoid inline styling wherever possible, instead using classes or element selectors to style specific components.
  • Use comments in more complex Xaps to explain particular layout/organization and UI design decisions made.

1471393231_Info.png A number of sample template Xaps are available as a starting point. Search for layout template in the Explore page and limit results to Xaps. You can learn more about a particular layout by opening the Xap's info page.

1471393231_Info.png For more information about styling Xaps, view this article about styling Xaps


Managing Saved State in Components


One of the more powerful but potentially confusing aspects of the data flow is its ability to selectively save the state of components' inputs. Incorrect saved state can lead to poor Xap performance and unintended behavior in the application. Follow these guidelines to optimize your Xap and avoid potential bugs.

  • Save the state of any static or default configuration settings: any settings or values that drive your application's behavior. Examples include configuration options for algorithms, UI parameters for charts and other visualizations, and selectors for data elements. In most cases, component inputs are saved by default (the exception being certain elements like an input with the name "data"), so you should be fine with the default behavior.
  • Do NOT save the state of data inputs, particularly those expecting to receive very large data files. Use an asset or secondary storage like a database or Amazon's AWS S3 to store the data until it needs accessed by the Xap.
  • Use button values and other "triggering events" to feed data into other components based on a user's action.
  • Use a component like "Simple Init" to feed data into components on page load.

1471393231_Info.png To check if state is being saved for a particular input, left-click on the desired component input in the Dataflow view and hover anywhere in the input's value field. You will see a series of icons, including a Save disk icon, along the title bar of the input. If the icon has a gray background behind it, the state will be saved with the Xap. The below screenshot shows that state will be saved for a component input.



Managing Larger, More Complex Xaps


When creating production-level Xaps, you can quickly reach a level of complexity that can be difficult to manage and extend. Follow these guidelines to keep things manageable.

  • Plan ahead: Exaptive's rapid development platform makes it easy to build prototype on the fly, but when constructing more robust applications, a bit of upfront planning pays significant dividends. Before diving in, sketch out the key elements required of the Xap, how they will be laid out, and most importantly which off-the-shelf components will be used versus customized ones for this project.
  • Encapsulate functionality and data: Often, you can construct a functioning Xap to meet a specific user need through a combination of off-the-shelf components. But if you need 20-30 components to replicate the unique functionality, say, of reading and writing objects or laying out a complex form, you may be better off creating a few custom components that handle all functionality. Your Xap will be much more understandable and legible. Exaptive continues to add capabilities to combine more granular components into an aggregate component, which gives the best of both worlds.
  • Each web page as its own Xap: Much like you'd manage a complex website, creating separate Xaps for different pages of functionality can keep each Xap's data flow manageable. You can use shared CSS, HTML and components to replicate common behavior like menus, authentication, etc. and simply link to the other Xap as you would any other webpage.
  • Document your work: Capture your design and key implementation decisions along with any specific connection information or confusing aspects of the Xap, so that your future you and others can benefit from this context. Use a Wiki, shared document, or other content capture system early and often, to avoid needing to go back and document everything at the end.