Some concerns about recent changes

[Ced]

I'm concerned about the changes being made to Flot.

I've been a user of this library for many years and I just had a unreasonably bad experience getting the most basic use case to work.

If I had this experience as a new user I would just use another library.

Proper distribution of the library needs to be addressed.  NPM is great but it should not be the primary mode of distribution because it assumes the user is working in a Node environment.  I shouldn't have to navigate to another site to download Flot.  The zip file that used to be available was ideal in this regard.  At a minimum, I should be able to download the concatenated unminified jquery.flot.js file.  I understand why this is not easy to do, but it's critical for a good user experience in using Flot.

The example pages have been updated to individually include each of Flot's component js files.  This is not a useful example of how to use Flot since the packaged  version of Flot concatenates these files into jquery.flot.js.  Showing this as an example conflicts with the Installation instructions that specify you only need to include one file (jquery.flot.js).

I'm also seeing some problems with quality assurance.

What is this file? https://github.com/flot/flot/blob/master/flot-2.1.3.tgz

It's not a tgz.  It's actually an HTML document with a .tgz extension.  It's also now three patch revisions behind the NPM linked on the Flot homepage.

I'm guessing this should not have been merged.

jquery.canvaswrapper.js should be named jquery.flot.canvaswrapper.js.

I gave up trying to use the new version of Flot this morning which is frustrating because I just don't have time to chase this down right now.  Having an unminified, concatenated jquery.flot.js would have helped tremendously.  I hope you can address that.

[Jarek Dobrzanski]

The best thing to move things forward and help the team is to create a separate issue for each of the problem, that you've encounter, so they could be handled one by one. It's been long time before the new team took over, when the plugins were separated from the core and distributed separately. Have a look at the 0.8.3 release zip on github where pllugins are already separated, and loaded in examples separately as required.

NPM is not the only distrubution mode. If you don't use NPM you can try unpkg as suggested here:

https://github.com/flot/flot/issues/1577

and if you don't want to use CDN you still download ZIP of current repo snapshot via github.

I think it's a transition period now once the new team took over and it will take some time to polish things out, create proper zip releases ect. There's been a substantial version bump and that also causes compatibility problems that are discussed.

Overall it's much better to have flot back alive and maintained again as opposed to dead.

--

---
You received this message because you are subscribed to the Google Groups "Flot graphs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to flot-graphs...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Ced]

Perhaps I didn't explain clearly.

There is an important distinction between Flot's core plugins (distributed with Flot eg. jquery.flot.resize.js) versus Flot's internal components that get concatenated into jquery.flot.js in build.js. (eg. jquery.flot.uiConstants.js)

The Examples were updated to include the individual pre-build components.  The point I'm trying to make is that this is not a good example to help a new user start using Flot.  The example to follow would be to include only jquery.flot.js which includes all of the components post-build, as a user would expect.  Also, if a user follows the examples, it's possible they would include the post-build jquery.flot.js and then unnecessarily include the component js files because that's what the example instructs them to do.

On the topic of distribution, neither unpkg, or a zip file from Github provide an unminified post-build jquery.flot.js.  So if I want to use the unminified version for any reason, I would currently need to set up a Node environment and build Flot.  I just think it's reasonable to have the unminified version readily available somewhere.

[Jarek Dobrzanski]

Thanks for clarification. It all makes sense now. I've created issues #1615 and #1616 to reflect that.

[Andrew Dove]

I have created a pull request (https://github.com/flot/flot/pull/1623) that creates a jquery.flot.js that is unminified, unbabelified concatenated source in the folder dist/source. The file flot-2.1.3.tgz has been removed.

The reason that the examples are the way they are is that they illustrate which scripts are needed for which features. If a person wants to use the minimum amount of code necessary then they can use the minified version or just the scripts they need for the features they are using. The examples help them with that.

[Ced]

Thanks!  But I'm still confused about the examples.  Maybe I still didn't explain myself well enough before.

The example pages are more than just a visual presentation. They also serve as code samples that developers can inspect to see how things should be done.

The examples are using <script> tags to include javascript files that a typical Flot user should never need to include because those files are concatenated into jquery.flot.js during the build process.

I don't understand how it is beneficial to instruct a Flot user to include the individual source files when they should be using the built product. I feel like it's especially important to avoid this confusion for new users.

Here is the minimum set of source scripts I had to include to get a simple line graph.  Flot did not work until I included all of these.

<script src="jquery.canvaswrapper.js"></script>
<script src="jquery.colorhelpers.js"></script>
<script src="jquery.flot.js"></script>
<script src="jquery.flot.saturated.js"></script>
<script src="jquery.flot.browser.js"></script>
<script src="jquery.flot.uiConstants.js"></script>
<script src="jquery.flot.drawSeries.js"></script>

jquery.flot.uiConstants.js is a good example of what I'm trying to convey.  It's just a source module that encapsulates some internal Flot functionality.  There is no benefit for a user to include that file separately.  It does not provide some optional feature that a user might be interested in.

The examples should not include source files directly.  They should use the post-build jquery.flot.js.

[Andrew Dove]

Ced,

So our thinking is that including individual scripts rather than the entire built script teaches new users two things. One it saves page size - typically 200k, not that much nowadays but its something. Two it teaches about what individual scripts do since each example more or less includes different scripts - there are some common ones, but overall it helps to understand the internals.

So there are a couple of options to compromise moving forward. One is collapse more common scripts into a single file, but leave less common ones separate. Two is to using just the built script in all the examples but document which scripts any given example is actually using as a comment. That second one could become a maintenance problem - the comment could become out of date.

[mtower]

I've had the same issues as Ced and had to create another similar post here (https://groups.google.com/forum/#!topic/flot-graphs/DCxuJKS9Wk0) that focussed on it. A number of your assumptions are incorrect. You've mentioned 

 "Two it teaches about what individual scripts do since each example more or less includes different scripts"

This is actually false. EVERY examples includes ALL the scripts. Like Ced found out the basic-usage example should only have those 6 scripts that are actually needed. Can you tell me why the touchNavigate scripts was included for a basic example that doesn't even have it enabled. That list of requires scripts is literally located no where, not even as an example. By showing users that they need all the scripts you actually aren't saving page size and if these 6 files are required regardless anythings to get the basics working you're not saving any space by separating them (if anything your increase it a tiny bit by having to process multiple files now). Its really the small things that matter. 

It could be as simple as remaining the filenames so that actual plugins are named jquery.flot.plugin.*.js so they they appear to have an extra layer of functional next to the other ones. Currently everything script name is 4 parts making it look like they're all of the same importance.

There also isn't any error handling in this regard. For instance if you include just the basic jquery.flot.js you'll find out that you need jquery.canvaswrapper.js. The issue is that the error doesn't help because you get a generic interpreter error like "object does not exist" making it look like the there's a bug in the code; not a proper handled error message like "the following script/objects are required". This is especially true for the uiConstants scripts where yet again you get a 'object does not exist' instead of a 'this property must be set before plot initialization'.

[Andrew Dove]

I created issue #1668 https://github.com/flot/flot/issues/1668 for this.

[Ced]

Based on the wording of issue #1668, I still get the impression that the root of the complaints is not understood.

Some of the files in the source directory are named like plugins but in fact provide core functionality. Eg. uiConstants.js

Flot will not work without this bit of code and the build process concatenates this into jquery.flot.js.

Here is where that concatenation happens.

A user who obtained a distribution of Flot should never need to include a script tag for uiConstants.js, yet it's in the examples.

The examples are using the pre-build version of Flot when they should be using a post-build distribution.

That's the root issue, which is a very different problem than including script tags for files that aren't used.

[mtower]

I have happy with the post for issue #1668. 

To help clarify, Ced are you talking specifically in instances where users are downloading via npm? For my company we just downloaded the original source files in which case the the files would always be separated (already have tool to filter out scripts we don't need)

[Andrew Dove]

It looks like there are two scenarios for the examples - use the built version of flot (dist/es5/jquery.flot.js) which includes everything but is minimized - or - use the source versions of the files. The issue I filed was intended to address an issue where more source scripts are included that actually required for the example. We could include a comment in each example.html stating that a user can also just include the built version and get everything they need. But if a user is interested in making a contribution it helps to know what scripts contribute to what functionality and the source version is more helpful.