matleppa commented 7 years ago

Similar functionality as in issue #2311.

Goal

Administrators can select certain APIs to be "Featured APIs" on APInf Catalog page.
Maximum amount of Featured APIs is 4.
The Featured APIs
- are displayed at the top of Catalog page as their own section.
- are displayed on Front page instead of Latest APIs (current implementation). (This will a separate task later.)
If the APIs are sorted by name Featured APIs (in their own section) always precede any other APIs. Sorting by name means Featured APIs sorted by name followed by all other APIs sorted by name. Likewise for sorting by time added.
There is a small visual indication of featured API on the API card, which can be toggled on and off. This is visible for admins only.

Refer to the Featured APIs implementation for Organization profile.

Wireframe

Under Branding menu, a new dropdown named "Featured APIs" appears in between Site Slogan and Colors controllers. The menu has the following default text "Select upto 8 APIs to be featured on the Homepage."
On clicking the dropdown, site admin can see the list of APIs available in the platform. The API names appear with checkboxes.
On checking an API name, it appears under the dropmenu as Bootstrap tag. The dropmenu should remain open on clicking checkboxes as long as user checks 8 boxes. If user needs to close the menu before 8 APIs are checked., s/he should click manually.
When user tries to select more tham 8 APIs, alert text appears with CSS alert class.

matleppa commented 7 years ago

Requirement is based on discussion Jarkko/Matti 2017-07-25

Nazarah commented 7 years ago

@matleppa isn't pinned APIs in an organization doing the similar functionality as same as the proposed one here? What are the user needs to introduce a similar feature?

matleppa commented 7 years ago

Issue 2311 Introduced the possibility to mark certain APIs as featured on Organization level. The person to set the featured mark is the Manager of the Organization.

Here the goal is to be able to mark APIs as featured on global level. The person to set the mark is Admin and the purpose is to set some exceptionally good APIs as examples for other API managers.

These two feature pins are independent from each other.

Nazarah commented 7 years ago

Where the feature can be seen in the UI? Home Page? Catalog?

kyyberi commented 7 years ago

I would like to see Featured APIs in APinf.io SaaS version instead of Latest APIs. Reasoning: latest APIs are mostly development/beta version or even alpha lacking documentation and meta information and whatnot. The user experience with such an opening is poor. If we instead push classroom example APIs in the frontpage, APIs which utilize most of the platform features and contain easy start for API consumer, we sell more.

bajiat commented 7 years ago

I agree that random Latest APIs on the front page do not bring the best image about the APIs in the catalog: they might be non-functional, profiles have missing information and APIs are even poorly named. So developers might not be interested to see More APIs. Also, as mentioned earlier, Latest APIs do not serve as a good example for other API owners.

Do we want to use the global option for marking APIs as Featured only on front page or should they be promoted on the API Catalog as well?

kyyberi commented 7 years ago

On second thought, perhaps we could leave the latest APIs, but put Features APIs on top of it. That would follow the logic in organisation level as well.

One addition to frontpage is a few links. Some of the customers (prospects) go directly production API management (apinf.io) and not to apinf.com which is the sales channel for us (needs rewamping contentwise.) Therefore I suggest adding a block between Featured APIs and Latest APIs. The block contains a few links laid out nicely:

New to API management? Check our offering
APInf is part of FIWARE Smart city platform. Read more
We focus on enabling top quality Developer eXperience. Read more.

Nazarah commented 7 years ago

On second thought, perhaps we could leave the latest APIs, but put Features APIs on top of it. That would follow the logic in organisation level as well.

I'd like to go with featured APIs in homepage. Having latest APIs is different and separate than Featured APIs. However, this would introduce two identical sections (in terms of look and feel and purpose). It safer to have production level APIs than latest ones (which might be in design/development phase and not functioning properly) The settings can be included in the Branding page of the site.

Nazarah commented 7 years ago

@saransh-dev I am working on the wireframe, it would be added in the later part of the day. :)

Nazarah commented 7 years ago

@bajiat @saransh-dev wireframes are added. Please leave your feedback.

marla-singer commented 7 years ago

@Nazarah @bajiat If an Admin doesn't select Featured APIs then how will Homepage look?

saransh-dev commented 7 years ago

@brylie @marla-singer Hi, when we use above wireframe (all select-checkbox apis in dropdown) and if we select more than 8 and try to submit then it shows error message inside the dropdown. For resolving this, I removed maxCount from schema and shows error message by salert.error() when user going to select 9th api.

But I don't think it's a good way.

Please advise.

brylie commented 7 years ago

if we select more than 8 and try to submit then it shows error message inside the dropdown. For resolving this, I removed maxCount from schema and shows error message by salert.error() when user going to select 9th api.

@saransh-dev, based on the discussion in this issue, the 8 API maximum is the desired feature.

What is the problem with the error message?

saransh-dev commented 7 years ago

@brylie the error message is displayed inside the dropdown below last api name and it should be shown below the drop down.

     <div class="form-group">
    <label for="branding-site-featured-api" class="control-label">
      {{_ "branding_projectFeaturedApiTitle_featuredApiTitle" }}
    </label>
    <div class="dropdown">
      <p class="branding-site-featured-api dropdown-toggle form-control" type="button" id="dropdownMenuButton " data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
        <span class="black-text">
          {{_ "branding_projectFeaturedApisMessage_featuredApiMessage" }}
          <i class="fa fa-caret-down pull-right"></i>
        </span>
      </p>
      <div class="dropdown-menu featured-api-list" aria-labelledby="dropdownMenuButton">
        {{> afQuickField name='featuredApis' id="branding-featured-apis" options=optionsAPi}}
      </div>
    </div>
    </div>

brylie commented 7 years ago

Lets try using autoform-select2 for the API select field. It integrates well with AutoForm, so should display error messages correctly (below the field).

brylie commented 7 years ago

Also, what pull request is related to this issue? Once development is in progress, we ask that a pull request be opened.

saransh-dev commented 7 years ago

Currently i have not been open any pull request and have not commit the code.

brylie commented 7 years ago

Alright. Go ahead and open a new branch/PR with autoform-select2.

saransh-dev commented 7 years ago

@brylie by using aldeed:autoform-select2 package and add code {{> afQuickField name='featuredApis' id="branding-featured-apis" multiple=true options=optionsAPi }} and schema is below

featuredApis: {
    type: [String],
    optional: true,
    maxCount: 3
  },

Is below output ok ? error

Please advise.

brylie commented 7 years ago

It looks good, and behaves as expected. Can you enable it to show tag-style selection, similar to the wireframes?

peek 2017-09-11 10-11

saransh-dev commented 7 years ago

But for multiple selection we need to select multiple options by pressing and hold ctrl key (for windows and linux ) or command key (for mac OS) and select multiple options .

brylie commented 7 years ago

The Select2 widget should allow multiple selection without holding ctrl or command. See above animation.

brylie commented 7 years ago

Follow the documentation in meteor-select2 README. Your example code above is missing the autoform declarations.

autoform: {
  type: 'select2',
  afFieldInput: {
    multiple: true
  }
}

OR

{{> afQuickField name="featuredApis" type="select2" multiple=true }}

Nazarah commented 7 years ago

@marla-singer If the admin doesn't select even one API to be featured on the Homepage, I suggest we don't show the section at all.

brylie commented 7 years ago

If the admin doesn't select even one API to be featured on the Homepage, I suggest we don't show the section at all.

@Nazarah might we show a message on the front page to the admin user saying something like "Add featured APIs from the Settings section"?

The Add Featured APIs call-to-action would be a similar to the Add Related Media on the API Profile view:

screenshot_20170911_104015

Nazarah commented 7 years ago

@brylie that's a good idea. But only site admin should be able to see this message and section. No other users. For unlogged users and logged in users, if there is no featured APIs added by the site admin, the whole section should not appear at all.

The message should be: "You can add featured APIs from Branding section under Settings."

marla-singer commented 7 years ago

@brylie @Nazarah If no featured APIs then should we display the Latest APIs in this section to make Homepage not so "empty"?

Nazarah commented 7 years ago

@marla-singer I don't have problem with it. If the implementation is easier. I was just wondering that when site admin logins, is s/he going to see both sections? (case: empty Featured APIs section and Latest APIs section with 8 APIs)

marla-singer commented 7 years ago

If the implementation is easier.

@Nazarah I predict yes, it would be easy

I was just wondering that when site admin logins, is s/he going to see both sections? (case: empty Featured APIs section and Latest APIs section with 8 APIs)

Yes, something like that joxi_screenshot_1505116565718

Nazarah commented 7 years ago

Looks good to me. Just please clarify me that if the site admin adds even a single Features API in the section, would the Latest APIs section become invisible to all users?

marla-singer commented 7 years ago

Just please clarify me that if the site admin adds even a single Features API in the section, would the Latest APIs section become invisible to all users?

@Nazarah If this behavior is expected then the developer should try to make it. I don't predict any problem with that

marla-singer commented 7 years ago

@saransh-dev Sum up our discussion with @Nazarah I suggest the scenario

If a user is Admin

If no Featured API is provided then
1. Display block "Latest APIs" for all users
2. Display block "Featured APIs" with text ""You can add featured APIs from Branding section under Settings.""
if any Featured API is provided then
1. Display block "Featured APIs" for all users
2. Hide block "Latest APIs" and title for all users

If a user is non Admin

If no Featured API is provided then
1. Display block "Latest APIs"
2. Don't display block "Featured APIs" and title as well
if any Featured API is provided then
1. Display block "Featured APIs" for all users
2. Hide block "Latest APIs" and title

saransh-dev commented 7 years ago

@brylie @marla-singer Hi, I need your help.

I have set maxCount 3 for featuredApi in schema. When I have select 3 APIs and click on the update button, it updates successfully but after updated, I checked it shows only 1 selected API which was first on the list and after reloading page, it shows all 3 selected API.

I also have attached GIF for this issue.

branding-featured-api

Please advise.

saransh-dev commented 7 years ago

If no Featured API is provided then

Display block "Latest APIs" for all users

Display block "Featured APIs" with text ""You can add featured APIs from Branding section under Settings.""

@marla-singer , if no Featured API is provided then, first i need to display Latest APIs and then Featured APIs message below to the Latest API, And No user is login, in that case do I need to show Featured APIs (If availabe) ? Please advise.

marla-singer commented 7 years ago

I have set maxCount 3 for featuredApi in schema. When I have select 3 APIs and click on the update button, it updates successfully but after updated, I checked it shows only 1 selected API which was first on the list and after reloading page, it shows all 3 selected API.

I've never worked with this type of schema field. Can't give some advise

if no Featured API is provided then, first i need to display Latest APIs and then Featured APIs message below to the Latest API,

No, change order. The first block is Featured and the second block is Latest

And No user is login, in that case do I need to show Featured APIs (If availabe)

If a user is non login

If no Featured API is provided then
1. Don't display block "Featured APIs" and title as well
2. Display block "Latest APIs"
if any Featured API is provided then
1. Display block "Featured APIs"
2. Hide block "Latest APIs" and title

brylie commented 7 years ago

An edge case comes to mind. How do we handle featured APIs that are marked as private?

Basically, new feature we add tend to intersect with existing features, sometimes in complex and unanticipated ways. It is getting increasingly difficult to add new features, as we accrete layer after layer of features. I again urge us to keep things simple.

cc: @bajiat

Nazarah commented 7 years ago

@brylie would it suffice if the dropdown populates no APIs that are labeled private? I know Site admin can see the private APIs as well. But for the sake of the feature, we can consider this.

cc: @bajiat

brylie commented 7 years ago

@brylie would it suffice if the dropdown populates no APIs that are labeled private?

@Nazarah one possibility that may also arise is that the Admin features an API that is marked as public, and then the API Owner later marks that API as private.

Any solution should probably check for the public/private status when displaying the Featured APIs (at runtime), so that we get consistent behavior. A possible solution might include:

change the 'featuredApis' publication to be publicFeaturedApis and make it return only featured APIs that are public
- (enforce a runtime check to ensure that no private API will appear in the Featured APIs block)
add an inline text next to the Branding form that 'private APIs will not appear in the Featured APIs section'
- (an admin understands that private APIs will be treated as private, and will not appear as Featured)
limit the list of APIs to be those that are currently public
- (an admin cannot feature a private API)

cc: @bajiat

Nazarah commented 7 years ago

@brylie Liked your proposed solution. There is an alternative to make the featured API disappeared from the Homepage list if it is marked as private. But I guess it would add too many complexities. I vouch for your suggestion.

brylie commented 7 years ago

There is an alternative to make the featured API disappeared from the Homepage list if it is marked as private.

My proposal includes that in the first bullet item. It would have the effect that the Featured API would not show up if it is private.

apinf / platform

Mark APIs featured on global level #2786

Goal

Wireframe

If a user is Admin

If a user is non Admin

If a user is non login